Migración desde reCAPTCHA

Esta guía le ayuda a migrar de Google reCAPTCHA (v2 checkbox/invisible o v3) a MTCaptcha con cambios paralelos en el navegador y en su servidor.

Por qué los equipos migran de reCAPTCHA

• Utilice un proveedor enfocado en la protección contra abusos relacionados con CAPTCHA y en un manejo orientado a la privacidad de los datos.
• Mejore la accesibilidad para los usuarios que tienen dificultades con flujos de challenge frecuentes basados solo en imágenes.
• Mantenga una disponibilidad fiable para audiencias globales, incluyendo China continental.
• Conserve un modelo de integración familiar: cargar el script, renderizar el widget y verificar el token del lado del servidor.

Resumen de migración

	reCAPTCHA	MTCaptcha
Script cliente	https://www.google.com/recaptcha/api.js	https://service.mtcaptcha.com/mtcv1/client/mtcaptcha.min.js
Clase del widget	.g-recaptcha (contenedor de widget v2; v3 carga script sin widget visible)	.mtcaptcha (use <div class="mtcaptcha"></div>)
Nombre del token	g-recaptcha-response (campo de formulario o callback)	mtcaptcha-verifiedtoken (nombre del input oculto)
API backend	POST https://www.google.com/recaptcha/api/siteverify (secret + response)	GET https://service.mtcaptcha.com/mtcv1/api/checktoken (privatekey + token)

Verificación solo del lado servidor

Llame a CheckToken de MTCaptcha solo desde el backend. Nunca incluya su PrivateKey en código frontend ni la exponga al navegador.

Paso 1: Reemplazar el script y el widget del lado cliente

<!-- Remove [reCAPTCHA] -->
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
<div class="g-recaptcha" data-sitekey="YOUR_RECAPTCHA_SITE_KEY"></div>

<!-- Add [MTCaptcha] -->
<script>
  var mtcaptchaConfig = { "sitekey": "YOUR_SITEKEY" };
</script>
<script src="https://service.mtcaptcha.com/mtcv1/client/mtcaptcha.min.js" async defer></script>
<div class="mtcaptcha"></div>

Orden de carga

Defina var mtcaptchaConfig = { "sitekey": "YOUR_SITEKEY" }; antes de cargar mtcaptcha.min.js para que el cliente lea la clave al inicializar.

Si usaba reCAPTCHA v3 (solo score, sin widget visible), elimine el script v3 y cualquier llamada execute; agregue el ancla de MTCaptcha <div class="mtcaptcha"></div> (o use Renderizado Explícito si ya personaliza el renderizado).

Paso 2: Actualizar la verificación del lado del servidor

Reemplace la verificación de reCAPTCHA por la API CheckToken de MTCaptcha:

GET https://service.mtcaptcha.com/mtcv1/api/checktoken?privatekey=YOUR_PRIVATEKEY&token=VERIFIED_TOKEN

Lea VERIFIED_TOKEN desde el campo enviado mtcaptcha-verifiedtoken (no g-recaptcha-response).

Vida útil del token y uso único

Los tokens verificados tienen vida corta. Valide enseguida tras enviar el formulario y espere una verificación CheckToken exitosa por token; una segunda verificación puede fallar por token duplicado. Vea Validar Token (Con Clave Privada).

Si su infraestructura requiere IPs de salida fijas, use https://service2.mtcaptcha.com/mtcv1/api/checktoken y la allowlist documentada.

Solución de problemas

Síntoma	Qué revisar
El widget no aparece	Allowlist de dominio y configuración del sitio en MTCaptcha Admin Portal; consola del navegador para errores de script.
Script bloqueado (CSP)	Permita https://service.mtcaptcha.com (y https://service2.mtcaptcha.com si carga el script secundario según Quick Start).
invalid-token / token-expired	Envíe el mtcaptcha-verifiedtoken más reciente; evite cachear POST antiguos o doble submit sin refrescar widget.
privatekey-mismatch-token	SiteKey y PrivateKey deben pertenecer al mismo sitio MTCaptcha.
CheckToken falla desde servidor	Verifique egress; pruebe host service2 e IP allowlist de Validar Token.

Lecturas adicionales

• MTCaptcha inicio rápido
• Validar Token (Con Clave Privada)
• Cumplimiento de Privacidad y GDPR
• Cumplimiento de Accesibilidad

Post-Migration Checklist

• Se eliminaron todos los scripts reCAPTCHA y rutas backend de siteverify.
• mtcaptchaConfig con "sitekey": "YOUR_SITEKEY" está definido antes de mtcaptcha.min.js.
• El POST del formulario incluye mtcaptcha-verifiedtoken y el backend solo lee ese campo.
• El backend llama a https://service.mtcaptcha.com/mtcv1/api/checktoken (o service2 según política) y acepta solo success: true.
• Se probaron envío válido, token expirado y rechazo por token ausente/incorrecto.
• Los hostnames de producción y desarrollo coinciden con la configuración del Admin Portal.
• CSP/red permite hosts de script y API de MTCaptcha.