Migra desde hCaptcha
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 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
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 |
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 para la configuración completa del cliente y la elección entre CDN y npm.
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://caputchin.com/api/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; los snippets por framework están en ejemplos de backend.
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), 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.
- 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.
- 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.
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, noh-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: la configuración completa del cliente.
- Verifica un token en tu backend: la referencia autoritativa de
siteverify. - Ejemplos de backend: la llamada de verify en cada lenguaje.
- Añade un juego: convierte la verificación en un juego.