Skip to main content
Este documento presentará una integración del API de reconocimiento del protocolo Cloudflare Turnstile, que permite a los usuarios completar la verificación sin necesidad de identificar y seleccionar el captcha de Turnstile, simplemente enviando la clave del sitio web para lograr la decodificación automática en segundo plano.

​
Proceso de Solicitud

Para utilizar el API de reconocimiento del protocolo Cloudflare Turnstile, primero dirígete a Ace Data Cloud Console para obtener tu Token API, que debes guardar como respaldo. Si aún no has iniciado sesión o registrado, serás redirigido automáticamente a la página de inicio de sesión que te invitará a registrarte e iniciar sesión, y después volverás automáticamente a la página actual. Un Token API es suficiente para acceder a todos los servicios de la plataforma, no es necesario solicitar uno por cada servicio. La primera solicitud incluirá un crédito gratuito para que puedas probarlo; si el crédito se agota, puedes recargar el saldo general en la consola.
📘 Documentación completa: API de Reconocimiento del Protocolo Cloudflare Turnstile →

​
Uso Básico

Primero, debes entender la forma básica de uso, que consiste en ingresar la URL del sitio web que necesita procesar el captcha de Turnstile, para obtener el resultado procesado. Primero, necesitas pasar un campo website_url, nuestro sitio de ejemplo es: https://react-turnstile.vercel.app, y necesitamos obtener el website_key en la página website_url. Primero, abre esta página, presiona F12 para acceder a la consola, y busca globalmente cf-turnstile en la página de Elementos, donde podrás encontrar el elemento contenedor que lleva Turnstile, y la cadena correspondiente a data-sitekey es el valor de website_key. Los encabezados de la solicitud configurados incluyen:
  • accept: el formato de respuesta que deseas recibir, aquí se establece como application/json, es decir, formato JSON.
  • authorization: la clave para llamar al API, que puedes seleccionar directamente después de solicitarla.
Además, se configuró el cuerpo de la solicitud, que incluye:
  • website_url: la URL del sitio web que necesita procesar el captcha.
  • website_key: el identificador de clave del sitio en Cloudflare Turnstile (sitekey).
  • action: parámetro opcional, solo se necesita pasar si el sitio objetivo ha configurado un action personalizado para el componente Turnstile.
  • cdata: parámetro opcional, solo se necesita pasar si el sitio objetivo ha configurado un cData personalizado para el componente Turnstile.
Haz clic en el botón “Try” para realizar la prueba, y aquí obtendremos el siguiente resultado:
El resultado devuelto tiene varios campos, que se describen a continuación:
  • token, el resultado de la verificación del captcha de Cloudflare Turnstile procesado.
  • started_at, finished_at: el tiempo en que comenzó el procesamiento de esta solicitud y se produjo el resultado, en marca de tiempo Unix (segundos, punto flotante).
  • elapsed: el tiempo total de procesamiento (segundos).
Como puedes ver, hemos obtenido el resultado de la verificación del captcha de Turnstile, que luego podemos usar para enviar un POST o simular el envío al sitio web objetivo, de un solo uso, con una validez de 120s, se recomienda usarlo dentro de los 60s. Al enviar, normalmente se envía este token como el parámetro cf-turnstile-response al sitio web objetivo, el código Python correspondiente para llamar a la verificación del token es el siguiente:
Además, si deseas generar el código de integración correspondiente, puedes copiarlo directamente, por ejemplo, el código CURL es el siguiente:
El código de integración en Python es el siguiente:

​
Modo Asíncrono (async)

Por defecto, el API es sincrónico y bloqueante: una solicitud esperará hasta que el token se procese completamente antes de devolverlo. Si estás haciendo rotación de múltiples solucionadores (multi-solver rotation) y deseas “recibir el task_id inmediatamente después de enviar la tarea, para luego programar otros solucionadores y volver más tarde a leer el resultado”, puedes pasar async: true en el cuerpo de la solicitud. Al pasar async: true, la interfaz devolverá inmediatamente un task_id, sin bloquear la espera:
Si deseas verificar el progreso, puedes usar ese task_id para consultar POST /captcha/tasks (se recomienda cada 3~5 segundos). Esta interfaz no activará ni avanzará el procesamiento de la tarea; incluso si no consultas, pierdes la conexión o cierras el cliente, el servidor seguirá procesando:
Durante el procesamiento, se devolverá status: processing; al completarse, se devolverá status: ready y el token:
Descripción de facturación: en modo asíncrono, la creación de tareas y la lectura del estado “procesando” no se facturan; la primera lectura exitosa del resultado por parte del cliente se facturará una vez (coincide con el comportamiento actual y el precio del modo sincrónico). El servidor avanzará la tarea por sí mismo, pero no cobrará anticipadamente si se completa en segundo plano. Si la tarea no se completa con éxito en 120 segundos, se terminará con un HTTP 504 timeout, sin costo. /captcha/tasks no es responsable de avanzar la tarea.
Nota: Cloudflare Turnstile no admite proxies propios (Bring Your Own Proxy), por lo que esta interfaz no acepta el parámetro proxy; si se pasa, devolverá 400 invalid_proxy.

​
Manejo de Errores

Al llamar al API, si encuentras un error, el API devolverá el código de error correspondiente y la información. Por ejemplo:
  • 400 token_mismatched：Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
  • 400 invalid_proxy：Solicitud incorrecta, el proxy no es compatible con este tipo de captcha.
  • 401 invalid_token：No autorizado, token de autorización inválido o faltante.
  • 429 too_many_requests：Demasiadas solicitudes, ha superado el límite de tasa.
  • 500 api_error：Error interno del servidor, algo salió mal en el servidor.

​
Ejemplo de respuesta de error

​
Conclusión

A través de este documento, usted ha aprendido cómo utilizar la API de identificación del protocolo Cloudflare Turnstile para permitir que los usuarios no tengan que identificar y seleccionar el captcha de Turnstile, simplemente enviando la clave del sitio web para lograr la decodificación automática en segundo plano y completar la verificación. Esperamos que este documento le ayude a integrar y utilizar mejor esta API. Si tiene alguna pregunta, no dude en ponerse en contacto con nuestro equipo de soporte técnico.