Migra desde reCAPTCHA
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 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
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 |
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 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.
| reCAPTCHA | Caputchin | |
|---|---|---|
| Endpoint | POST https://www.google.com/recaptcha/api/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" } | { 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; los snippets por framework están en ejemplos de backend.
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), 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.
- 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.
- 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 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, nog-recaptcha-response, un fallo común de una línea.
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.