---
type: how-to
title: Migre do reCAPTCHA
summary: "Troque o reCAPTCHA pelo Caputchin com mudanças mínimas: o mesmo formato em duas partes (um widget no cliente mais uma 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 reCAPTCHA, 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 de propósito o formato `siteverify` do reCAPTCHA. 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 reCAPTCHA.

## 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 reCAPTCHA, 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

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

Como o reCAPTCHA, 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.

| | reCAPTCHA | Caputchin |
|---|---|---|
| Endpoint | `POST https://www.google.com/recaptcha/api/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" }` | `{ success, challenge_ts, hostname, error-codes, score? }` |
| Regra de confiança | aja só se `success === true` | aja só se `success === true` (idêntico) |

Na maioria dos stacks, a única mudança no seu código de verificação é a URL e o valor do segredo. A referência completa de requisição/resposta, incluindo os códigos de erro, 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. Mapeie o score, se você usava o reCAPTCHA v3

O reCAPTCHA v3 retorna um `score` (de 0.0 a 1.0) e pede que você escolha um limiar, você está adivinhando o quão humana uma requisição parecia. 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 probabilidade.

Se o seu código tinha `if (data.score >= 0.5)`, troque por `if (data.success)`. O campo `score` do Caputchin existe só para rodadas de jogo e é a pontuação **do jogo** (informativa, para os seus próprios placares), nunca uma probabilidade de bot, então não condicione o acesso a ela.

## O que melhora na mudança

- **Sem coleta de dados de visitantes.** O reCAPTCHA traça o perfil dos seus visitantes; 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. Veja a [filosofia](/docs/understanding-caputchin/philosophy).
- **Um widget, não v2 contra v3.** Não há um produto invisível/de score separado entre os quais escolher; um elemento cobre a checkbox e o jogo opcional.
- **Um jogo opcional.** Em vez de uma grade de semáforos, você pode transformar a verificação em um jogo curto que seus visitantes de fato jogam. 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 reCAPTCHA. Não envie o segredo ao navegador.
- **O token é de uso único.** Como no reCAPTCHA, 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 `g-recaptcha-response`, um deslize comum de uma linha.

## 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.