SilentShield

Endpoints do widget

Estes endpoints são chamados pelo widget SilentShield. Normalmente não os chama diretamente — estão documentados para que possa acompanhar o que acontece na sua página.

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

POST/api/v1/telemetry/behavior

Envia os dados comportamentais da interação atual (rato, teclado, deslocamento) e devolve o nonce juntamente com um veredicto. O seu formulário envia esse nonce no campo `behavior_nonce`.

Auth: API Key (cabecalho 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 para a sua quota assim que o evento `submit` chega com um nonce — exatamente uma vez por envio. `init`, `telemetry` e `form_detected` não contam.

POST/api/v1/captcha/challenge

Solicita um desafio aritmético quando o veredicto foi incerto. O widget fá-lo por si; o desafio é de utilização única e está ligado ao nonce.

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

Request Body:

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

Response:

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

Necessário apenas quando a resposta de telemetria indicou `challenge_required: true`.

POST/api/v1/captcha/verified

Submete o desafio resolvido. O nonce só é marcado como humano quando a resposta corresponde a um desafio emitido pelo servidor para esta chave.

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

Request Body:

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

Response:

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

Fail-closed: uma resposta errada ou expirada devolve 403 com `reason: "invalid_solution"`. O desafio é de utilização única.

POST/api/v1/captcha/verify-nonce

Verifica um nonce gerado pelo widget. Chame este endpoint a partir do seu servidor para confirmar que o envio do formulario e legitimo.

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

Request Body:

{"nonce": "nonce_xyz789"}

Response:

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

Este endpoint conta para a quota. Os nonces sao de utilizacao unica e expiram apos 5 minutos.