---
type: how-to
title: Migra desde hCaptcha
summary: "Cambia hCaptcha por Caputchin con cambios mínimos: la misma forma de widget-de-cliente-más-verificación-en-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 hCaptcha, 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` que el propio hCaptcha sigue. 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 hCaptcha.

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

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

Como hCaptcha, 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.

| | hCaptcha | Caputchin |
|---|---|---|
| Endpoint | `POST https://api.hcaptcha.com/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", score? }` | `{ success, challenge_ts, hostname, error-codes, score? }` |
| Regla de confianza | actúa solo si `success === true` | actúa solo si `success === true` (idéntico) |

Una nota de formato: el endpoint de verify de hCaptcha espera `application/x-www-form-urlencoded`, mientras que el de Caputchin acepta JSON. Si tu código existente enviaba campos form-encoded, cambia el cuerpo a JSON (`{"secret":"...","response":"..."}`) con `Content-Type: application/json`. Los campos en sí no cambian. La referencia completa de petición/respuesta 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. Deja caer el score, si usabas hCaptcha Enterprise

hCaptcha Enterprise devuelve un `score` de riesgo (donde un número **más alto** significa **más** riesgo) y te pide elegir un umbral. 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 estimación de riesgo.

Si tu código tenía `if (data.score < 0.7)`, reemplázalo con `if (data.success)`. El campo `score` de Caputchin no tiene relación: existe solo para rondas de juego y es la puntuación del **juego** (informativa, para tus propios marcadores), nunca un riesgo ni una probabilidad-de-bot, así que no condiciones el acceso a él. (Nota que la dirección también es opuesta, el score de hCaptcha sube con el riesgo; el de Caputchin sube con el rendimiento en el juego.)

## Qué se traslada, y qué mejora

- **La postura de privacidad por la que elegiste hCaptcha, conservada.** Caputchin no recoge IP, User-Agent, huella, ni telemetría de comportamiento; el protocolo no tiene dónde poner un identificador de visitante, así que no hay ninguno que filtrar ni vender. Mira la [filosofía](/docs/understanding-caputchin/philosophy).
- **Un juego opcional.** En vez de un reto de selección de imágenes, puedes convertir la verificación en un juego corto que tus visitantes de verdad juegan, y es la parte que aguanta frente a los solvers de IA. 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 hCaptcha. No envíes el secreto al navegador.
- **El token es de un solo uso.** Como hCaptcha, 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 `h-captcha-response`, un fallo común de una línea.
- **Formato del cuerpo.** Envía la petición de verify como JSON, no form-encoded.

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