Skip to main content
Este documento presentará una integración del API de reconocimiento del protocolo Recaptcha2, que permite a los usuarios completar la verificación sin necesidad de identificar y seleccionar las imágenes del captcha de Recaptcha2, 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 Recaptcha2, primero dirígete a la consola de Ace Data Cloud 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 una vez completado, regresarás automáticamente a la página actual. Un Token API es suficiente para acceder a todos los servicios de la plataforma, sin necesidad de solicitar uno por cada servicio. La primera solicitud incluirá un crédito gratuito para que puedas probarlo; si el crédito es insuficiente, puedes recargar el saldo general en la consola.
📘 Documentación completa: API de Reconocimiento del Protocolo Recaptcha2 →

​
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, y así obtener el resultado procesado. Primero, necesitas pasar un campo website_url, nuestro sitio de ejemplo es: https://www.google.com/recaptcha/api2/demo, necesitamos obtener el website_key en la página website_url, primero abre esta página, presiona F12 para acceder a la consola, y finalmente busca globalmente en la página de Elementos recaptcha-demo, así obtendremos el siguiente resultado:

La cadena correspondiente a data-sitekey es el valor de website_key, a continuación se presentan los resultados de los parámetros específicos:

Aquí podemos ver que hemos configurado los Encabezados de Solicitud, que incluyen:
  • accept: el formato de respuesta que deseas recibir, aquí se establece como application/json, es decir, en formato JSON.
  • authorization: la clave para llamar al API, que puedes seleccionar directamente después de solicitarla.
Además, se configuró el Cuerpo de Solicitud, que incluye:
  • website_url: la URL del sitio web que necesita procesar el captcha.
  • website_key: el identificador de la clave del sitio en Recaptcha2.
  • proxy: opcional, trae tu propio proxy (Bring Your Own Proxy). Una vez configurado, el servicio utilizará la IP del proxy que proporcionaste para resolver el captcha, lo que ayuda a controlar la calidad de la IP de salida (por ejemplo, para evitar que la IP de un proxy público sea bloqueada por el sitio objetivo y devuelva 410 Gone). El formato es scheme://[user:pass@]host:port, donde scheme admite http/https/socks4/socks5, por ejemplo, http://user:pass@1.2.3.4:8080. Si no se completa, se utilizará el proxy predeterminado de la plataforma.
Después de seleccionar, puedes notar que también se generó el código correspondiente a la derecha, como se muestra en la imagen:

Haz clic en el botón “Try” para realizar la prueba, como se muestra en la imagen anterior, aquí obtuvimos el siguiente resultado:
Los resultados devueltos tienen múltiples campos, que se describen a continuación:
  • token, el resultado de la verificación después de procesar la tarea de Recaptcha2.
  • started_at, finished_at: el tiempo de inicio y finalización de esta solicitud, en marca de tiempo Unix (segundos, flotante).
  • elapsed: el tiempo total de procesamiento de esta tarea (segundos).
Como se puede ver, hemos obtenido el resultado de la verificación del Recaptcha2, 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 120 segundos, se recomienda usarlo dentro de los 60 segundos. A continuación, se proporcionará un fragmento de Python que enviará el token procesado al sitio web objetivo para pasar la verificación de Recaptcha2. Primero necesitamos averiguar cómo el sitio envía la solicitud POST, de esta manera podremos pasar el token generado. Necesitamos abrir la consola F12 y luego realizar la verificación manualmente. Al final, podemos ver que el sitio envió una solicitud POST, solo necesitamos revisar la construcción de esta solicitud POST, el proceso específico es el siguiente:
  • Primero, verifique manualmente, como se muestra en la siguiente imagen:

  • Luego haga clic en enviar, observe los cambios en la red de la consola, como se muestra en la siguiente imagen:

  • Analiza la construcción de la solicitud POST de esta entrega, al final puedes hacer clic derecho en la solicitud para copiar el código CURL, que es el siguiente:

De acuerdo con el análisis de la imagen anterior, la URL de esta solicitud POST es: https://www.google.com/recaptcha/api2/demo, solo necesitamos enviar el parámetro g-recaptcha-response, luego solo necesitamos pasar el token procesado a los datos a continuación, el código CURL específico para llamar al token para la verificación es el siguiente:
El código Python correspondiente para llamar a la verificación del token es el siguiente:
Luego ejecutamos el código y observamos que la consola muestra el siguiente resultado:

Finalmente, hemos pasado la verificación del protocolo Recaptcha2. 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, la API es sincrónica y bloqueante: una solicitud esperará hasta que se complete el procesamiento del token antes de devolver una respuesta. 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 consultar el progreso de manera activa, puedes usar ese task_id para consultar POST /captcha/tasks (se recomienda cada 3 a 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:
Mientras se procesa, devolverá status: processing:
Cuando se complete el procesamiento, 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 “en procesamiento” no se facturan; la primera vez que el cliente lee un resultado exitoso se factura una vez (igual que el comportamiento existente y el precio del modo sincrónico). El servidor avanzará la tarea por sí mismo, pero no cobrará anticipadamente porque la tarea se complete en segundo plano. Si la tarea no se completa con éxito en 120 segundos, se terminará con un HTTP 504 timeout, sin facturación. /captcha/tasks no es responsable de avanzar la tarea.

​
Manejo de errores

Al llamar a la API, si encuentras un error, la API devolverá el código de error y la información correspondiente. Por ejemplo:
  • 400 token_mismatched: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
  • 400 api_not_implemented: Solicitud incorrecta, posiblemente debido a parámetros faltantes o inválidos.
  • 401 invalid_token: No autorizado, token de autorización inválido o faltante.
  • 429 too_many_requests: Demasiadas solicitudes, has 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, has aprendido cómo utilizar la API de reconocimiento del protocolo Recaptcha2 para permitir que los usuarios no tengan que identificar y seleccionar imágenes de captcha de Recaptcha2, 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 te ayude a integrar y utilizar mejor esta API. Si tienes alguna pregunta, no dudes en contactar a nuestro equipo de soporte técnico.