SilentShield

Endpoint del widget

Questi endpoint vengono richiamati dal widget SilentShield. Normalmente non li richiama lei — sono documentati perché possa seguire ciò che accade sulla sua pagina.

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

POST/api/v1/telemetry/behavior

Invia i dati comportamentali dell’interazione corrente (mouse, tastiera, scorrimento) e restituisce il nonce insieme a un verdetto. Il suo modulo invia quel nonce come campo `behavior_nonce`.

Auth: API Key (intestazione 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"}

Conta sulla sua quota non appena l’evento `submit` arriva con un nonce: esattamente una volta per invio. `init`, `telemetry` e `form_detected` non contano.

POST/api/v1/captcha/challenge

Richiede un calcolo da risolvere quando il verdetto era incerto. Il widget lo fa da sé; la prova è monouso e legata al nonce.

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

Request Body:

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

Response:

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

Necessario solo quando la risposta di telemetria ha segnalato `challenge_required: true`.

POST/api/v1/captcha/verified

Invia la prova risolta. Il nonce viene contrassegnato come umano solo se la risposta corrisponde a una prova emessa dal server per questa chiave.

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

Request Body:

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

Response:

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

Fail-closed: una risposta errata o scaduta restituisce 403 con `reason: "invalid_solution"`. La prova è monouso.

POST/api/v1/captcha/verify-nonce

Verifica un nonce generato dal widget. Chiama questo endpoint dal tuo server per confermare che l'invio del modulo è legittimo.

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

Request Body:

{"nonce": "nonce_xyz789"}

Response:

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

Questo endpoint conta per la quota. I nonce sono monouso e scadono dopo 5 minuti.