Recaptcha2 Protocolo de Reconocimiento API Integración

Recaptcha verification code recognition service API guide - Ace Data Cloud

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 luego realiza una búsqueda global en la página de Elementos por recaptcha-demo, así obtendremos el siguiente resultado:

Donde 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 upstream 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:

{
  "token": "03AFcWeA5kjJyDQ9S1a9UYimR6nuxnpEnAs5x2Pixao0dXZhMBjiR2MwAwN7K3NXik02Vl--cEmCwxDuf7mNBMbGlfLHb5948cvCdk1jnp_mjbWzT9ZyxzSnny52TiWVZo1xvTTad5QIQz9iRfJrjcM1BkBj5OpwT4mRVK-Yoz8Q8m5MlXEwQ5Zyp0Lxh_L-32EkdwyyCIOlG-Q1wJ-lR7utNB6E8MCrtTM1tox75-3KPvMNHbTjvqSf1l3FO_bASk39mtleI_NjThAPHCBL__cHu2wJxRYITYxqYgCu3FYcmC3OfcUJJEmgg4KEpQTIjo1X2N1m81obHWKrOrrNqfQvELnXrhHU4gVcFwpaMladoLysqOrDqHsYxNeUTp5YiEu6_Xl2eC6r9IKTbeddIf5QXQML_OILc4Ee3-vEUepmelWq7GE4wOKf8zQ8Xfz1MbJM3daEmiVEMFs4EQsjGgioPeyQUjiJT5U2sZfiJbgyGdUVletCBn4abnSLBYVI-rKKlETKu4IQVGCmh_hNn7cnkX3E5p_Kqu3gifOYHSbCu2ctuaPe9G3M8XxbQ57b_UFgg1MMToSAcZDL2NWtL4yPag5Y4lCnpmfrGOwvX-QFF0JF-DrbRn_Opv52JrLD9GrfGxo99kiucQIZkAzpWLV3Kkhtep2DB8OiA4rSb5R6xT4nNoawg1BM2cM5jazL-1U6LzSs9Hq1XWV1nwj-8-mTDwHmBYMI6fmSfl1-bOX0uHGgWHnzEAW2mw4EErVVUTUJJcUr_LZ2woRkexk-CPQTtdlHmQHbt_1FsOzfGtnXY87xIbhCJReVyv-_HQ48d9xCDuQ-JnNjX98NfDsfvpxe9Zar_LjcQCBNtvHgKH_JkniBDiWrZBAoDJIonDjJ6X1mmWLyPDxYmBR6O7QkxR3DxdDvZQRaZnfD-_sA9T9JEkYWHdBlpumEBq9wVs8dSm60TiRAOZU1ZLjieGP5vI5_aV-ct5SwOmWHF-VQkJUfNZ33MoEkZW2Rvh7_ERbI_PRS_u65BCkhuOh8fmQcxJU5YACpoLXXkwGM8qmSB1yBBeOQL-wWUfo8GREpZIu1oGQVQ8k3FcNJzFQQAYcLBWfGn-8qMxfAJEd356lJYIUuU1CY2rhR1u_7C1R_bH0WTifDqYLCRGzn-tzqBOXybrkOs_KURL-gT6wAoZRpUvBBAEa1mRg5gxap0pOkpdf7MPb5PsWVME7E3stvordioyN2tdLKr6VC-0kiQZD1WzykazPZzkl302Y_kpQ2vKPawWVWmNhy5Vm_cwT6afOAuSHnU1aYtFNvEDpBcXXH2YcqS-sBnMb3KlO5KpfZSp-tGzvjds46ajyoD7bHGzxvCx9EplICVrGWQ8gRYe2MCVJ3OocE-VK7PxI1iKXJK_LBl4hQR7uUKaDVEbmBYMcgS1z5YmXbJV89yjrU-u5ncTn5JkJgoSdOvMi8l2fsZIl2wYi-hWgQjP6LLI6M6wr8AhyiSZBQ34adR07niQPzLfX5Ntwr_8NyMg69bWKlLXknv8O2KznYXQQwsWA3okJCGwhfJkp35QnkHsprTN9LD48cwg8zP7a1mgM-2WHuZmoCpqg1XJgT_tPjc7X9kCQt8e3YirW6IJs-CdBUDkbp12FCukip48mDz7SOWjnLruoNABfo_zCurdOQY_tfcWe4g_ef0y_vey3hLGvxuay_ZMGzDLIo-7_WEp7jU09YKqWOZV7cSxDPm65M1v69ND6b5awsopISEe7E3hKMGrVSonRa9_bkiQ2fuPa5-xitNr4IMxwWMepqDk54v_cyVzUBdAAq8V8w3VHvV4-tjTXFqp0L54RBhJ_EaCXO7nwNbVLqCirfDpKRASfkYoaqsoXbwFMpfFrh-KzDZVIuU6D-VBF5k50ufGPnoXTA8kIF0GjAepW5SCxYupoQos4La6W2f--cl4WAl8oKhSpFtRpb1CNMKmtD7_BJrPDxpnXiA-ENBFe8Y4EOoG5uavVeQl6YftHej52JOTKurOqD-NE-UDBLInNuOo0ayCdV1w8XDAnORgxbkYP65GO5FdytK4zrDVNQEK26D54e0xLpDqUG8UUmUT_VNj9UY78WyWGPTXiGwYAA2_iVUKbT8-phHLDDqeoG3Q5iTP7RUpaW49JmM-tlSeczqqyy9Wc8iZh2Cf9veRJ7HiUeIEMeKGnqD7E9nXxcjC75GzIo477c83U7QN_1QXQjWuAr0C3KFq2W7dJmO08pQ0Z13dG7tz4Ilg1Bc3LIcNgeJLkCTZYpDpn7JpeZRbe6fqvmbqWPQ",
  "elapsed": 31.6
}

Los resultados devueltos tienen varios 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 (segundos).

Se puede ver que 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, para poder 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 imagen a continuación:

• Luego haga clic en enviar, observe los cambios en la red de la consola, como se muestra en la imagen a continuación:

• Analice la construcción de la solicitud POST enviada esta vez, finalmente puede hacer clic derecho en esta solicitud para copiar el código CURL, como se muestra en la siguiente imagen:

Según 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 en los datos a continuación, el código CURL específico para llamar a la verificación del token es el siguiente:

curl 'https://www.google.com/recaptcha/api2/demo' \
  --data-raw 'g-recaptcha-response={token}’

El código Python correspondiente para llamar a la verificación del token es el siguiente:

import requests

token = '{token}'

data = {
    'g-recaptcha-response': token,
}

response = requests.post('https://www.google.com/recaptcha/api2/demo',data=data)

if response.status_code:
    print(response.text)

Luego ejecutamos el código y observamos que la consola muestra el siguiente resultado:

Finalmente, hemos pasado la verificación del protocolo del captcha Recaptcha2.

Además, si desea generar el código de integración correspondiente, puede copiarlo directamente, por ejemplo, el código CURL es el siguiente:

curl -X POST 'https://api.acedata.cloud/captcha/token/recaptcha2' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_key": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
  "website_url": "https://www.google.com/recaptcha/api2/demo"
}'

El código de integración en Python es el siguiente:

import requests

url = "https://api.acedata.cloud/captcha/token/recaptcha2"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "website_key": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    "website_url": "https://www.google.com/recaptcha/api2/demo"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

​

Modo asíncrono (async)

Por defecto, la API es síncrona y bloqueante: una solicitud esperará hasta que el token sea procesado para devolver la respuesta. Si está realizando rotación de múltiples solucionadores (multi-solver rotation) y desea “obtener inmediatamente el task_id después de enviar la tarea, para luego programar otros solucionadores y volver más tarde a obtener el resultado”, puede pasar async: true en el cuerpo de la solicitud.

Al pasar async: true, la interfaz devolverá inmediatamente un task_id sin bloquear la espera:

curl -X POST 'https://api.acedata.cloud/captcha/token/recaptcha2' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_key": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
  "website_url": "https://www.google.com/recaptcha/api2/demo",
  "async": true
}'

{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}

Luego use este task_id para hacer polling con POST /captcha/tasks (se recomienda cada 3~5 segundos) para obtener el resultado:

curl -X POST 'https://api.acedata.cloud/captcha/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002"
}'

Durante el procesamiento devolverá status: processing:

{ "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "processing" }

Al completarse devolverá status: ready y el token:

{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "ready",
  "token": "03AFcWeA5kjJyDQ9S1a9UYimR6nuxnpEnAs5x2Pixao0dXZhMB......"
}

Explicación de facturación: en modo asíncrono, la creación de la tarea y el polling con estado “procesando” no se cobran; solo se cobra una vez al obtener el resultado exitosamente (igual precio que el modo síncrono). Por lo tanto, cancelar tareas no completadas durante la rotación no genera costos. /captcha/tasks es común para todas las interfaces de captcha (series token y recognition), puede usar el mismo task_id para hacer polling.

​

Manejo de errores

Al llamar a la API, si ocurre un error, la API devolverá el código y mensaje de error correspondiente. Por ejemplo:

• 400 token_mismatched: Solicitud incorrecta, posiblemente por parámetros faltantes o inválidos.
• 400 api_not_implemented: Solicitud incorrecta, posiblemente por 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, ha excedido el límite de tasa.
• 500 api_error: Error interno del servidor, algo salió mal en el servidor.

​

Ejemplo de respuesta de error

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

Conclusión

Con este documento, ya ha aprendido cómo usar la API de reconocimiento del protocolo Recaptcha2 para que los usuarios no necesiten identificar ni hacer clic en la imagen del captcha Recaptcha2, solo enviando la Website Key puede realizar la decodificación automática en segundo plano y completar la verificación. Esperamos que este documento le ayude a integrar y usar mejor esta API. Si tiene alguna pregunta, no dude en contactar a nuestro equipo de soporte técnico.