---
type: how-to
title: Migre do Cloudflare Turnstile
summary: "Troque o Cloudflare Turnstile pelo Caputchin com mudanças mínimas: o mesmo formato de widget no cliente mais verificação no servidor mapeia quase um para um, e como no Turnstile o resultado é um aprova/reprova limpo, aqui está o antes e depois."
---

O Caputchin usa o mesmo modelo em duas partes do Cloudflare Turnstile, 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. O Turnstile é o mais próximo do Caputchin entre os provedores comuns, porque ambos retornam um aprova/reprova autoritativo em vez de um score de risco, então não há limiar para reajustar. 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 Turnstile.

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

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

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

| | Turnstile | Caputchin |
|---|---|---|
| Endpoint | `POST https://challenges.cloudflare.com/turnstile/v0/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", action, cdata }` | `{ success, challenge_ts, hostname, error-codes }` |
| 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; ambos já ramificam em `success`, então não há limiar de score para portar. O Turnstile também aceita JSON na chamada de verificação, exatamente como o Caputchin, então o formato do corpo se mantém inalterado. 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).

Se a sua integração com o Turnstile lia `action` ou `cdata` na resposta, note que o Caputchin não tem equivalente direto; esses são rótulos específicos do Turnstile que você define no widget. O metadado análogo do Caputchin (qual jogo foi jogado, sua pontuação) vive no bloco `platform` da resposta e é apenas informativo.

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

- **Ainda um aprova/reprova limpo.** Você mantém a regra de confiança mais simples possível, `if (success)`, sem probabilidade nem limiar para manter.
- **A postura de privacidade pela qual você escolheu o Turnstile, 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. Veja a [filosofia](/docs/understanding-caputchin/philosophy).
- **Um jogo opcional.** Em vez de um desafio invisível ou gerenciado, 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 Turnstile. Não envie o segredo ao navegador.
- **O token é de uso único.** Como no Turnstile, 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 `cf-turnstile-response`, um deslize comum de uma linha.
- **Sem `action` / `cdata`.** Se você ramificava nesses, mova essa lógica para outro lugar; o Caputchin não os carrega.

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