> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://platform.acedata.cloud/console/applications) para obtener tu Token API, que debes guardar como respaldo. ![](https://cdn.acedata.cloud/5hmkdg.jpg) 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](https://platform.acedata.cloud/console/coin). > 📘 Documentación completa: [API de Reconocimiento del Protocolo Recaptcha2 →](https://platform.acedata.cloud/documents/captcha-token-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: ```json theme={null} { "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: ```shell theme={null} 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: ```python theme={null} 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: ```shell theme={null} 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: ```python theme={null} 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: ```shell theme={null} 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 }' ``` ```json theme={null} { "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: ```shell theme={null} 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`: ```json theme={null} { "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "processing" } ``` Al completarse devolverá `status: ready` y el token: ```json theme={null} { "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 ```json theme={null} { "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.