Verificação no Servidor

Sempre verifique o nonce do SilentShield no seu servidor. Verificações apenas no lado do cliente podem ser contornadas por bots.

Por Que no Servidor?

O Widget é executado no navegador e injeta um nonce nos formulários. Um bot poderia ignorar o Widget e enviar o formulário diretamente. A verificação no servidor garante que o nonce foi legitimamente emitido e verificado pelo SilentShield.

Endpoint da API

Method: POST
URL: https://api.silentshield.io/api/v1/captcha/verify-nonce
Headers: X-Api-Key: YOUR_API_KEY Content-Type: application/json
Body: { "nonce": "the-nonce-from-the-form" }

Formato de Resposta

Responsejson

{
  "ok": true,
  "verdict": "human",
  "confidence": 0.92,
  "requested_nonce": "..."
}

human: human — O utilizador é muito provavelmente humano. Processe o formulário.
suspicious: suspicious — o servidor rejeitou (HTTP 403, `ok: false`). O veredicto indica o motivo, não a decisão: essa já foi tomada pelo limiar da sua conta.
bot: bot — Alta confiança de que é um bot. Rejeite o formulário.

Lógica Recomendada

O servidor já aplicou o limiar da sua conta: uma rejeição chega como HTTP 403 com `ok: false`. Verifique portanto a passagem, e não `bot` — caso contrário deixa passar todas as rejeições emitidas como `suspicious` e todas as respostas sem veredicto (chave inválida, quota esgotada).

Server-Side Logicjavascript

if not ok or verdict != "human":
    rejeitar o formulário (403)
else:
    processar o formulário normalmente

Formulários enviados por AJAX

O widget comunica um envio quando o formulário é enviado com um submit normal. Comunica também os pedidos feitos com XMLHttpRequest, incluindo jQuery.ajax, desde que o corpo do pedido contenha o campo behavior_nonce: retém o pedido por instantes, comunica os dados de escrita e de rato e envia o pedido assim que o veredito chega, o mais tardar após 15 segundos. Serialize, por isso, o formulário inteiro, incluindo os campos ocultos. A sua verificação no servidor não muda.

Não abrangidos: pedidos feitos com fetch() e pedidos síncronos. Nestes casos, o servidor não recebe dados de escrita nem de rato e /v1/verify responde suspicious.

Tratamento de Erros

Se a API do SilentShield estiver inacessível (timeout, erro 5xx), decida a sua estratégia:

Fail Open: Fail open — Aceitar o formulário (melhor experiência de utilização, menos seguro)
Fail Closed: Fail closed — Rejeitar o formulário (mais seguro, pior experiência de utilização)

Para a maioria das aplicações, recomendamos fail open com registo em log. Formulários críticos (login, pagamento) devem usar fail closed.