> ## 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. # Recaptcha3 Protocolo de Reconocimiento API Integración > Recaptcha verification code recognition service API guide - Ace Data Cloud Este documento presentará una descripción de la integración del API de reconocimiento del protocolo Recaptcha3, que permite a los usuarios completar la verificación sin necesidad de identificar y seleccionar imágenes de captcha, 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 Recaptcha3, primero dirígete a [Ace Data Cloud Console](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 Recaptcha3 →](https://platform.acedata.cloud/documents/captcha-token-recaptcha3) ## Uso Básico Primero, es importante entender la forma básica de uso. A diferencia de Recaptcha2, necesitamos pasar un parámetro adicional `page_action`, que debe obtenerse del código. La URL de la demostración de velocidad de la red es: `https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php`, a continuación se muestra un método para obtenerlo: ### Método Rápido: Abre f12, luego busca en la página de Elementos `.execute(`, en el área del cuadro rojo podemos ver el parámetro `action`, y al mismo tiempo, después de execute hay una cadena de caracteres, que también es el contenido necesario más adelante, como se muestra en la imagen a continuación.

Además, necesitas ingresar la URL del sitio web que requiere el captcha, para obtener el resultado procesado. Primero, debes pasar un campo `website_url`, y finalmente, también necesitas ingresar el parámetro `website_key`, que se puede obtener en el texto anterior, también es una cadena de caracteres que sigue a execute. A continuación, podemos completar los campos correspondientes en la interfaz, como se muestra en la imagen:

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, formato JSON. * `authorization`: la clave para llamar al API, que puedes seleccionar directamente después de solicitar. Además, se configuró el Cuerpo de Solicitud, que incluye: * `page_action`: debe obtenerse del código del sitio web que requiere el captcha. * `website_url`: la URL del sitio web que necesita procesar el captcha. * `website_key`: el identificador de clave del sitio en Recaptcha3. 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í hemos obtenido el siguiente resultado: ```json theme={null} { "token": "03AFcWeA5mfdNlQD0RGX9PTWPs0l65QukjwbYObCue5hygRuA6jJmBtwR98S2bmmZOjbLh7ogEMDd8NzJdq8DoHOD_LHIUWmdEL3HJS0pP2nmTTSoU_ltxORWA4sVsrWiXDgkARA4wAhJCegD6PftkRuu0KKbqRsJ7KVKukUbLU1ThBu7P3r0fybwpS11yQmF7xpbEZeFzRm_osERk9tQzs1lEYORZSVA5dimbWi42TqUC87mJHCKO0HMiU404LOyER84It7ne51V5YXEHR_o6-ORr2CmBOawdTDTsqWUwT8vyEvzy-ov-pZdl0B0A_U59_uZd7vbIwv937-iXyzkVWbakUXNMdXlHffpFYd7OLTSBhJu6nasV3IhrbnxO8eGIbPDoHIyGpA74D882ALwTnXMgkcmGeGM9YuqCrf7F06cNKY7yKiisZIU-7v3ZnHV3JUkODGpXQ6dwq2fuP5o6kgeUQVdkv4fAZ_Tx_TB_R6gPSgwulr8Q5hH34bs-v1oUl2S9mLhXT9SWvgYizU_4FN2Ou23ETXTAVD_uI9fWaDgKaLOKI1i-xHCF_LKU3wKjyYJfQhFSCSyoeGL4o1j9lZ27cEHL5AlCm_jcCiXhe2_LT_dI-r5ozuyOGv-iDZ_1XTSSnCGdmroXX56XsZAytU52zBAlYVe_aRAojruc9KdkhK4kdeBESBbDLVe3-jNFwYspe0R93SORxXXIqR9CtZrIjI_2U8XjCHFz_euChdU_wkH5BjvONVbUT1DQNuoo0ugJL5kUkFrubHppOKvoZMwIKjjK_ZX1NBeCvQvYm6IpwBWfvM4hjGI7UVXH3iZkrX9PLATIIIkA8PxTeN45k8DulzOhKLSFKK196fRlH83S8UAaM-vjBxf32Vg83C1gWzKB5sYhxqEtZeB7DNpmAkozFfubljURr7YTjtq8Bgnj0PkfzbgKk8FRl-hMUb9BUjNNuSuFC7GZVim6xQnIV9ZPaAcuzJTYcOizFJePbVEXlc9A5Vq2rDh3D7Ld5o5oqc2kK4eCrO_38le6EVTs_fRY2nXy6RMyjjaJN12lOKYwYzGKhm52gTZTrJXqeTAW8o2KfwZ9iek-tr5qxj5b40iY4V2PY6SflMQvmKLAgFhB-yo-o5PEkikQ98T-bE-wG2-3kd5NRMiD132kIhf48zhVJUGeJqdV_3m8ukyqTk26KisM12kN-h9uYefvUCxzd_mBuWlHzH9rFMlJSe8Z6lcZIVcqNF4fcEM-ukNnwMUK5H_SC48U7O_xfOaEqEpAHDC7CCyVwlGCFh0uAT8KSpaNFfxBmMPXeYrGYn83PCgMg1NZA-7PrpeidXmWdBZ2yY8MA__7uCe8clCmINseBTCIbNmAHPlI_zJKqQfhXaDbaELeD62P0Pquu_SBtdEtqPeB9Esn_yjbK3IFvAaGSnFhwhHHK8dpOI7v-rJvTigPu8MMrEUTvug_zog81kCG8HY3xorTj2OdTwdEYpeMJ1VIHSjdTcnepLB0Cffx5wAdk-gf1TGEnEyTiwII4A4vtq8r0LFK4YObOzNmBTl3IoTNheYYKpheTKH3KShMK6hXDKxDRGEUhdsW4TRtVT-dwJDqY_F7J1RwKP-xDuN98VgwQmQuhJteQUALevgI2jAGFCFfSeFbQ8BOT6ekEI0m30zDX0kh83mkE7-u9qKljYifjqbLarMNPP51QRbvAS3mHlP17PMhIKzjuIka4T2Y9XdRwDgRRdEkYiJgDvkcABTknGBMezraon8JNDRhIJMUIKpidWTdhEQ79qAEfZkowdbnTdKeWeayi1OmV_W4aox-aC62H-VIn70McXXB6zRyYlA2NvTUWgNhHWkSO1SW7uflNEyUeWFRLBZV_firMEVfIGirHOAbQqsn83BirDNPHl4xevf4nRu4gWpgOGBrzeUXQeuMWO4ZFsdWxJ2VsT19t0H5DJtxtHYXFtPZ8tFDFY-r8JKFab4S6e5v8PCrfjCWkPmDaRJal_vLFa1V1dF1l0ARu9NLW4mEuT600azFms8cMlvuCTvWI2VWyn4Wk05UvcR8FYO2-ke4E-ZFRl0jSxjlEutzbOwm2ik4eF0Wh2DBliaSr1obHaxkmLJDUIzGQ3wi49Nyn0SSOdz_BGaxuRrrxCZ4ci0e2b5cxLtkv64Njy7IYJURaBuQk99ijdw7rg3pssAa_uJSMQeZe_kLtgEWF73uT4ceSOFPVuxMGLrJRQTBYxAHVKq7kloS5wtphUr2Sp-b4kezKnCV9HNfC5NRk2KqDT-bkJ6cUYN_0yauyZK1_F4BVTk36IOCe1Cqfe3K-wAZBzvrI_Vz8Li1uEWe0b5KOQ", "elapsed": 31.6 } ``` 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 Recaptcha3. * `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 Recaptcha3, que luego podemos usar para simular el envío a un sitio web objetivo mediante POST o GET, de un solo uso, con una validez de 120 segundos, se recomienda usarlo dentro de los 60 segundos. A continuación, se presentará brevemente una forma de enviar el token generado al sitio web objetivo: Código en Python para llamar a la verificación del token: ```python theme={null} import requests url = "https://recaptcha-demo.appspot.c/recaptcha-v3-verify.php?action=examples/v3scores&token='{token}'" r = requests.get(url) if r.status_code == 200: return r.text ``` Por lo tanto, podemos obtener el resultado: ```json theme={null} { "success": true, "hostname": "recaptcha-demo.appspot.com", "challenge_ts": "2024-09-14T08:52:26Z", "apk_package_name": null, "score": 0.9, "action": "examples/v3scores", "error-codes": [] } ``` 可以看到，其中 `success` 表示此处验证的处理结果，所有我们成功通过Recaptcha3验证码的验证。 另外如果想生成对应的对接代码，可以直接复制生成，例如 CURL 的代码如下： ```shell theme={null} curl -X POST 'https://api.acedata.cloud/captcha/token/recaptcha3' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "website_url": "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php", "website_key": "6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9", "page_action": "examples/v3scores" }' ``` Python 的对接代码如下： ```python theme={null} import requests url = "https://api.acedata.cloud/captcha/token/recaptcha3" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "website_url": "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php", "website_key": "6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9", "page_action": "examples/v3scores" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` ## 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 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, programar otros solucionadores y luego volver a obtener 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: ```shell theme={null} curl -X POST 'https://api.acedata.cloud/captcha/token/recaptcha3' \ -H 'accept: application/json' \ -H 'authorization: Bearer {token}' \ -H 'content-type: application/json' \ -d '{ "website_url": "https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php", "website_key": "6LdKlZEpAAAAAAOQjzC2v_d36tWxCl6dWsozdSy9", "page_action": "examples/v3scores", "async": true }' ``` ```json theme={null} { "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab" } ``` Luego, usa ese `task_id` para hacer polling a `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, se devolverá `status: processing`: ```json theme={null} { "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "processing" } ``` Al completar el procesamiento, se devolverá `status: ready` y el token: ```json theme={null} { "success": true, "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002", "status": "ready", "token": "03AFcWeA5mfdNlQD0RGX9PTWPs0l65QukjwbYObCue5hygRuA6......" } ``` Descripción de facturación: en modo asíncrono, la creación de tareas y el polling "en procesamiento" no se facturan; **solo se factura una vez al obtener el resultado exitosamente** (el mismo precio que en modo sincrónico). Por lo tanto, cancelar tareas que aún no se han completado durante la rotación no generará costos. `/captcha/tasks` es común para todas las interfaces de captcha (token y reconocimiento) y se puede hacer polling con el mismo `task_id`. ## 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 ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Conclusión A través de este documento, has aprendido cómo usar la API de reconocimiento del protocolo Recaptcha3 para permitir que los usuarios no necesiten identificar y seleccionar imágenes de captcha de Recaptcha3, 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.