---
type: how-to
title: Migra desde reCAPTCHA
summary: "Cambia reCAPTCHA por Caputchin con cambios mínimos: la misma forma de dos partes (un widget de cliente más una verificación en el servidor) mapea casi uno a uno, aquí está el antes-y-después exacto de cada pieza."
---

Caputchin usa el mismo modelo de dos partes que reCAPTCHA, un widget en la página que produce un token, y una comprobación en el servidor que lo confirma, así que migrar es sobre todo un cambio mecánico, no una reescritura. El intercambio del servidor en particular refleja la forma del `siteverify` de reCAPTCHA a propósito. Esta guía da el antes-y-después de cada pieza.

Si todavía no has creado una cuenta de Caputchin y una clave de sitio, [crea tu cuenta](/docs/getting-started/create-your-account) primero; necesitarás una **clave pública** (`cpt_pub_...`) para la página y un **secreto** (`cpt_sec_...`) para tu backend, la misma división que la site key y la secret key de reCAPTCHA.

## El modelo mental no cambia

```mermaid
flowchart LR
  A["Widget en tu página"] -->|token| B["Tu formulario / petición"]
  B -->|token| C["Tu backend"]
  C -->|secreto + token| D["endpoint siteverify"]
  D -->|¿success?| C
```

Todo lo que ya construiste alrededor de reCAPTCHA, renderizar un widget, recoger un token, hacer POST a tu servidor, verificarlo antes de fiarte de la petición, se queda. Solo cambian los nombres y los endpoints.

## 1. Cambia el snippet del cliente

| | reCAPTCHA (v2 checkbox) | 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 en un formulario | `g-recaptcha-response` (auto-inyectado) | `caputchin-token` (auto-inyectado) |
| Leer el token en JS | `grecaptcha.getResponse()` | el `detail.token` del [evento `pass`](/docs/references/widget-methods-and-events) |

Como reCAPTCHA, el widget de Caputchin **auto-inyecta un campo de token oculto** en el formulario en el que está, así que si tu formulario ya hacía un POST normal, solo cambias el elemento y el nombre del campo que tu backend lee. Mira [añade el widget](/docs/getting-started/add-the-widget) para la configuración completa del cliente y [la elección entre CDN y npm](/docs/integration-guides/cdn).

## 2. Cambia la verificación del servidor

Aquí es donde los dos están más cerca, las formas de petición y respuesta se alinean casi campo por campo.

| | reCAPTCHA | Caputchin |
|---|---|---|
| Endpoint | `POST https://www.google.com/recaptcha/api/siteverify` | `POST https://verify.caputchin.com/v1/siteverify` |
| Campos de petición | `secret`, `response` | `secret`, `response` (idéntico) |
| Respuesta | `{ success, challenge_ts, hostname, "error-codes" }` | `{ success, challenge_ts, hostname, error-codes, score? }` |
| Regla de confianza | actúa solo si `success === true` | actúa solo si `success === true` (idéntico) |

En la mayoría de los stacks el único cambio a tu código de verificación es la URL y el valor del secreto. La referencia completa de petición/respuesta, incluidos los códigos de error, está en [verifica un token en tu backend](/docs/integration-guides/verify-on-your-backend); los snippets por framework están en [ejemplos de backend](/docs/integration-guides/backend-examples).

## 3. Mapea el score, si usabas reCAPTCHA v3

reCAPTCHA v3 devuelve un `score` (0.0 a 1.0) y te pide elegir un umbral, estás adivinando cuán humana parecía una petición. Caputchin **no** funciona así: `success` es un aprobado/fallo autoritativo, porque la verificación se superó realmente (una comprobación de proof-of-work, o una [ronda de juego vuelta a derivar en el servidor](/docs/understanding-caputchin/gaming-anti-cheat)), no una probabilidad.

Si tu código tenía `if (data.score >= 0.5)`, reemplázalo con `if (data.success)`. El campo `score` de Caputchin existe solo para rondas de juego y es la puntuación del **juego** (informativa, para tus propios marcadores), nunca una probabilidad-de-bot, así que no condiciones el acceso a él.

## Qué mejora en el cambio

- **Sin recogida de datos de visitante.** reCAPTCHA perfila a tus visitantes; Caputchin no recoge IP, User-Agent, huella, ni telemetría de comportamiento, el protocolo no tiene dónde poner un identificador de visitante. Mira la [filosofía](/docs/understanding-caputchin/philosophy).
- **Un widget, no v2-frente-a-v3.** No hay un producto invisible/de score separado entre el que elegir; un elemento cubre la checkbox y el juego opcional.
- **Un juego opcional.** En vez de una rejilla de semáforos, puedes convertir la verificación en un juego corto que tus visitantes de verdad juegan. Mira [añade un juego](/docs/getting-started/add-a-game).
- **Una CSP estricta se queda estricta.** Caputchin corre bajo una Content-Security-Policy apretada; permites unos pocos origins en vez de aflojar tu política. Mira [cómo Caputchin pone los juegos en sandbox](/docs/understanding-caputchin/game-sandboxing#the-csp-you-set-on-your-own-page).

## Gotchas

- **Dos claves, dos hogares.** La clave pública (`cpt_pub_...`) va en la página; el secreto (`cpt_sec_...`) se queda solo en el servidor, exactamente la disciplina de reCAPTCHA. No envíes el secreto al navegador.
- **El token es de un solo uso.** Como reCAPTCHA, un token verifica una vez. No lo caches ni lo repitas.
- **Cambia el nombre del campo que tu backend lee.** El campo oculto es `caputchin-token`, no `g-recaptcha-response`, un fallo común de una línea.

## Véase también

- [Añade el widget](/docs/getting-started/add-the-widget): la configuración completa del cliente.
- [Verifica un token en tu backend](/docs/integration-guides/verify-on-your-backend): la referencia autoritativa de `siteverify`.
- [Ejemplos de backend](/docs/integration-guides/backend-examples): la llamada de verify en cada lenguaje.
- [Añade un juego](/docs/getting-started/add-a-game): convierte la verificación en un juego.