Integração no lado do servidor

O widget entrega ao navegador um token de uso único. Esse token não prova nada até que seu servidor o confirme com o Caputchin. Este é o passo que transforma um desafio visível em proteção de verdade, e é uma única chamada HTTPS.

Você precisa de um backend que consiga fazer uma requisição de saída, e do segredo da sua chave de site (cpt_sec_...) disponível ali, nunca no navegador.

1. Leia o token

Quando o formulário posta, seu handler recebe um campo extra ao lado dos seus: caputchin-token. O widget o injetou no formulário quando o visitante resolveu o desafio.

2. Confirme-o com /siteverify

Faça POST do token e do seu segredo. A requisição e a resposta têm o mesmo formato do siteverify do reCAPTCHA, então uma integração existente migra com pouca mudança:

POST https://caputchin.com/api/v1/siteverify
Content-Type: application/json

{ "secret": "cpt_sec_...", "response": "<caputchin-token>" }

// Node 18+
const verdict = await fetch("https://caputchin.com/api/v1/siteverify", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    secret: process.env.CAPUTCHIN_SECRET,
    response: token,
  }),
}).then((r) => r.json());

if (!verdict.success) {
  // reject the submission
}

A mesma chamada em outras linguagens está em exemplos de integração de backend.

3. Leia a resposta

{
  "success": true,
  "error-codes": [],
  "platform": { "game_id": "caputchin/games/leaf-memory", "score": 847, "duration_ms": 4200 }
}

• success é a única coisa em que ramificar. true significa que um visitante real resolveu o desafio; confie na requisição. false significa descartá-la.
• error-codes aparece quando success é false, nomeando o que deu errado (um token ausente, expirado ou já usado, e assim por diante).
• platform são metadados alegados pelo cliente (qual jogo, a pontuação, a duração). É anulável e não é um sinal de segurança. Registre-o para análises se quiser, mas nunca condicione a confiança à pontuação.

As regras que protegem você

• Uso único. Um token verifica uma vez. Enviar o mesmo de novo retorna success: false, então você não precisa rastrear replays por conta própria.
• Vida curta. Um token expira dez minutos depois de emitido, então verifique-o enquanto trata o envio, não em um job atrasado.
• O segredo fica no servidor. Ele nunca vai ao navegador, e é o que autentica a chamada.

Erros comuns

• Verificar no cliente. O evento pass e a presença do token são só de UX. Toda decisão de confiança acontece aqui, no servidor, com seu segredo.
• Condicionar ao score. É metadado, não um valor de confiança.

Veja também

• Exemplos de integração de backend para esta chamada na sua linguagem.
• Verificação hospedada para pular o backend por completo.