---
type: how-to
title: Migre do hCaptcha
summary: "Troque o hCaptcha pelo Caputchin com mudanças mínimas: o mesmo formato de widget no cliente mais verificação no servidor mapeia quase um para um, aqui está o antes e depois exato de cada peça."
---

O Caputchin usa o mesmo modelo em duas partes do hCaptcha, um widget na página que produz um token e uma conferência no servidor que o confirma, então migrar é em boa parte uma troca mecânica, não uma reescrita. A troca no servidor, em especial, espelha o formato `siteverify` que o próprio hCaptcha segue. Este guia dá o antes e depois de cada peça.

Se você ainda não criou uma conta e uma chave de site no Caputchin, [crie sua conta](/docs/getting-started/create-your-account) primeiro; você vai precisar de uma **chave pública** (`cpt_pub_...`) para a página e de um **segredo** (`cpt_sec_...`) para o seu backend, a mesma divisão da chave de site e da chave secreta do hCaptcha.

## O modelo mental não muda

```mermaid
flowchart LR
  A["Widget na sua página"] -->|token| B["Seu formulário / requisição"]
  B -->|token| C["Seu backend"]
  C -->|segredo + token| D["endpoint siteverify"]
  D -->|sucesso?| C
```

Tudo o que você já construiu em torno do hCaptcha, renderizar um widget, coletar um token, fazer POST dele no seu servidor, verificá-lo antes de confiar na requisição, permanece. Só os nomes e os endpoints mudam.

## 1. Troque o trecho do cliente

| | hCaptcha | Caputchin |
|---|---|---|
| Script | `<script src="https://js.hcaptcha.com/1/api.js" async defer>` | `<script src="https://cdn.jsdelivr.net/npm/@caputchin/widget@3/dist/widget.js">` |
| Elemento | `<div class="h-captcha" data-sitekey="...">` | `<caputchin-widget sitekey="cpt_pub_...">` |
| Campo de token em um formulário | `h-captcha-response` (autoinjetado) | `caputchin-token` (autoinjetado) |
| Ler o token em JS | `hcaptcha.getResponse()` | o `detail.token` do [evento `pass`](/docs/references/widget-methods-and-events) |

Como o hCaptcha, o widget do Caputchin **autoinjeta um campo de token oculto** no formulário em que fica, então se o seu formulário já fazia um POST normal, você só muda o elemento e o nome do campo que seu backend lê. Veja [adicionar o widget](/docs/getting-started/add-the-widget) para a configuração completa do cliente e [a escolha entre CDN e npm](/docs/integration-guides/cdn).

## 2. Troque a verificação no servidor

É aqui que os dois ficam mais próximos, os formatos de requisição e resposta se alinham quase campo a campo.

| | hCaptcha | Caputchin |
|---|---|---|
| Endpoint | `POST https://api.hcaptcha.com/siteverify` | `POST https://verify.caputchin.com/v1/siteverify` |
| Campos da requisição | `secret`, `response` | `secret`, `response` (idêntico) |
| Resposta | `{ success, challenge_ts, hostname, "error-codes", score? }` | `{ success, challenge_ts, hostname, error-codes, score? }` |
| Regra de confiança | aja só se `success === true` | aja só se `success === true` (idêntico) |

Uma nota de formato: o endpoint de verificação do hCaptcha espera `application/x-www-form-urlencoded`, enquanto o do Caputchin aceita JSON. Se o seu código existente enviava campos codificados como formulário, troque o corpo para JSON (`{"secret":"...","response":"..."}`) com `Content-Type: application/json`. Os campos em si não mudam. A referência completa de requisição/resposta está em [verificar um token no seu backend](/docs/integration-guides/verify-on-your-backend); trechos por framework estão em [exemplos de backend](/docs/integration-guides/backend-examples).

## 3. Largue o score, se você usava o hCaptcha Enterprise

O hCaptcha Enterprise retorna um `score` de risco (onde um número **maior** significa **mais** risco) e pede que você escolha um limiar. O Caputchin **não** funciona assim: `success` é um aprova/reprova autoritativo, porque a verificação foi de fato resolvida (uma conferência de proof-of-work, ou uma [rodada de jogo rederivada no servidor](/docs/understanding-caputchin/gaming-anti-cheat)), não uma estimativa de risco.

Se o seu código tinha `if (data.score < 0.7)`, troque por `if (data.success)`. O campo `score` do Caputchin não tem relação: ele existe só para rodadas de jogo e é a pontuação **do jogo** (informativa, para os seus próprios placares), nunca um risco ou probabilidade de bot, então não condicione o acesso a ele. (Repare que a direção também é oposta, o score do hCaptcha sobe com o risco; o do Caputchin sobe com o desempenho no jogo.)

## O que se mantém, e o que melhora

- **A postura de privacidade pela qual você escolheu o hCaptcha, mantida.** O Caputchin não coleta IP, User-Agent, impressão digital nem telemetria comportamental; o protocolo não tem onde pôr um identificador de visitante, então não há nada para vazar ou vender. Veja a [filosofia](/docs/understanding-caputchin/philosophy).
- **Um jogo opcional.** Em vez de um desafio de seleção de imagens, você pode transformar a verificação em um jogo curto que seus visitantes de fato jogam, e é a parte que resiste a solucionadores de IA. Veja [adicionar um jogo](/docs/getting-started/add-a-game).
- **Uma CSP estrita continua estrita.** O Caputchin roda sob uma Content-Security-Policy apertada; você permite algumas origens em vez de afrouxar sua política. Veja [como o Caputchin coloca os jogos em sandbox](/docs/understanding-caputchin/game-sandboxing#the-csp-you-set-on-your-own-page).

## Pegadinhas

- **Duas chaves, dois lares.** A chave pública (`cpt_pub_...`) vai na página; o segredo (`cpt_sec_...`) fica só no servidor, exatamente a disciplina do hCaptcha. Não envie o segredo ao navegador.
- **O token é de uso único.** Como no hCaptcha, um token verifica uma vez. Não o cacheie nem o reenvie.
- **Mude o nome do campo que seu backend lê.** O campo oculto é `caputchin-token`, não `h-captcha-response`, um deslize comum de uma linha.
- **Formato do corpo.** Envie a requisição de verificação como JSON, não codificada como formulário.

## Veja também

- [Adicionar o widget](/docs/getting-started/add-the-widget): a configuração completa do cliente.
- [Verificar um token no seu backend](/docs/integration-guides/verify-on-your-backend): a referência autoritativa do `siteverify`.
- [Exemplos de backend](/docs/integration-guides/backend-examples): a chamada de verificação em cada linguagem.
- [Adicionar um jogo](/docs/getting-started/add-a-game): transforme a verificação em um jogo.