SilentShield

Endpoints del Widget

El widget de SilentShield llama a estos endpoints. Normalmente no los llama usted — se documentan para que pueda seguir lo que ocurre en su página.

Base URL: https://api.silentshield.io

POST/api/v1/telemetry/behavior

Envía los datos de comportamiento de la interacción actual (ratón, teclado, desplazamiento) y devuelve el nonce junto con un veredicto. Su formulario envía ese nonce como el campo `behavior_nonce`.

Auth: API Key (encabezado X-Api-Key)

Request Body:

{"ts": 1767225600000, "nonce": "bh_abc123", "event": "submit", "form_key": "contact", "feature_hash": "...", "metrics": {...}, "signature": "..."}

Response:

{"id": "...", "nonce": "bh_abc123", "status": "queued", "verdict": "human", "score": 0.87, "captcha_solved": false, "challenge_required": false, "difficulty": "pass", "reason_codes": [], "action": "allow"}

Cuenta para su cuota en cuanto llega el evento `submit` con un nonce: exactamente una vez por envío. `init`, `telemetry` y `form_detected` no cuentan.

POST/api/v1/captcha/challenge

Solicita un desafío aritmético cuando el veredicto fue incierto. El widget lo hace por sí mismo; el desafío es de un solo uso y está ligado al nonce.

Auth: API Key (encabezado X-Api-Key)

Request Body:

{"nonce": "bh_abc123", "difficulty": "medium"}

Response:

{"ok": true, "challenge_id": "ch_xyz789", "a": 7, "op": "+", "b": 5}

Solo es necesario cuando la respuesta de telemetría indicó `challenge_required: true`.

POST/api/v1/captcha/verified

Envía el desafío resuelto. El nonce se marca como humano solo cuando la respuesta coincide con un desafío que el servidor emitió para esta clave.

Auth: API Key (encabezado X-Api-Key)

Request Body:

{"challenge_id": "ch_xyz789", "answer": 12}

Response:

{"ok": true}   //  403: {"ok": false, "reason": "invalid_solution"}

Fail-closed: una respuesta incorrecta o caducada devuelve 403 con `reason: "invalid_solution"`. El desafío es de un solo uso.

POST/api/v1/captcha/verify-nonce

Verifica un nonce generado por el widget. Llame a este endpoint desde su servidor para confirmar que el envío del formulario es legítimo.

Auth: API Key (encabezado X-Api-Key)

Request Body:

{"nonce": "nonce_xyz789"}

Response:

{"valid": true, "verdict": "human", "score": 0.92, "timestamp": "2025-01-15T10:30:00Z"}

Este endpoint cuenta para su cuota. Los nonces son de un solo uso y caducan después de 5 minutos.