Saltar al contenido principal

Migración desde Cloudflare Turnstile

Esta guía le ayuda a migrar de Cloudflare Turnstile a MTCaptcha sustituyendo el widget cliente y reemplazando el flujo siteverify por CheckToken de MTCaptcha.

Por qué los equipos migran de Cloudflare Turnstile​

  • Estandarice las operaciones CAPTCHA en un único proveedor entre varios productos o unidades de negocio.
  • Use el manejo de datos orientado a la privacidad de MTCaptcha y su conjunto de funciones específicas para CAPTCHA.
  • Mantenga un flujo de desafíos accesible y modos opcionales de validación de baja fricción.
  • Conserve una entrega global predecible del servicio, incluyendo China continental.

Resumen de migración​

Cloudflare TurnstileMTCaptcha
Script clientehttps://challenges.cloudflare.com/turnstile/v0/api.jshttps://service.mtcaptcha.com/mtcv1/client/mtcaptcha.min.js
Clase del widget.cf-turnstile (contenedor <div class="cf-turnstile" data-sitekey="…"></div>).mtcaptcha (use <div class="mtcaptcha"></div>)
Nombre del tokencf-turnstile-response (input oculto / campo de formulario)mtcaptcha-verifiedtoken (nombre del input oculto)
API backendPOST https://challenges.cloudflare.com/turnstile/v0/siteverify (secret + response)GET https://service.mtcaptcha.com/mtcv1/api/checktoken (privatekey + token)
Verificación solo del lado servidor

Mantenga el PrivateKey de MTCaptcha en el servidor. El navegador solo debe conocer el SiteKey dentro de mtcaptchaConfig.

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

<!-- Remove [Cloudflare Turnstile] -->
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
<div class="cf-turnstile" data-sitekey="YOUR_TURNSTILE_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 mtcaptchaConfig (con "sitekey") antes de cargar mtcaptcha.min.js.

Si usaba opciones de Turnstile como appearance, callback o refresh-expired, traslade ese comportamiento a MTCaptcha con APIs de JavaScript y JS Callbacks.

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

Reemplace las llamadas de verificación de Turnstile por el CheckToken de MTCaptcha:

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

Pase el valor enviado de mtcaptcha-verifiedtoken como token.

Vida útil del token y uso único

Trate cada token como de vida corta. Valide justo después del envío y evite reutilizar el mismo token en múltiples llamadas CheckToken salvo configuración intencional. Vea Validar Token (Con Clave Privada).

Solución de problemas​

SíntomaQué revisar
Widget en blanco / script 403Dominio no permitido para su SiteKey en Admin Portal.
Errores CSPPermita https://service.mtcaptcha.com (y service2 si se usa).
Aún se lee cf-turnstile-responseActualice toda la lógica de formularios a mtcaptcha-verifiedtoken (incluyendo tests).
token-expiredEl usuario envió tarde; regenere token con nueva resolución.
Firewall saliente estrictoCambie el host CheckToken a service2.mtcaptcha.com.

Lecturas adicionales​

Post-Migration Checklist​

  • Script, contenedor y siteverify de Turnstile eliminados.
  • mtcaptchaConfig con "sitekey": "YOUR_SITEKEY" definido antes de mtcaptcha.min.js.
  • El servidor verifica mtcaptcha-verifiedtoken vía https://service.mtcaptcha.com/mtcv1/api/checktoken.
  • Comportamientos callback/refresh de Turnstile migrados a MTCaptcha.
  • Hostnames de producción y staging validados contra Admin Portal.
  • CSP/red permite recursos y API de MTCaptcha.