Skip to main content
Este documento presentará una descripción de la integración de la 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 la API de reconocimiento del protocolo Recaptcha3, primero dirígete a la consola de Ace Data Cloud para obtener tu token de 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 de 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 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 demostración de la 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 siguiente imagen.

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 la 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 a la API, que puedes seleccionar directamente después de solicitarla.
Además, se configuró el cuerpo de la 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 la 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:
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:
Por lo tanto, podemos obtener el resultado:
可以看到，其中 success 表示此处验证的处理结果，所有我们成功通过Recaptcha3验证码的验证。 另外如果想生成对应的对接代码，可以直接复制生成，例如 CURL 的代码如下：
Python 的对接代码如下：

​
Modo asíncrono (async)

默认情况下 API 是同步阻塞的：一次请求会一直等待，直到 token 处理完成才返回。如果你在做多打码器轮换（multi-solver rotation），希望「提交任务后立即拿到 task_id，先去调度其他打码器，稍后再回来读取结果」，可以在请求体中传入 async: true。 传入 async: true 后，接口会立即返回一个 task_id，而不会阻塞等待：
如需主动查看进度，可使用该 task_id 查询 POST /captcha/tasks（建议每 3~5 秒一次）。本接口不会触发或推进任务处理；即使不查询、断网或退出客户端，服务器仍会继续处理：
处理中会返回 status: processing：
处理完成会返回 status: ready 和 token：
计费说明：异步模式下，创建任务和读取「处理中」状态都不计费；客户端首次读取成功结果时计费一次（与现有行为及同步模式价格一致）。服务器会自主推进任务，但不会因为后台先完成就提前扣费。任务在 120 秒内未成功会终止为 HTTP 504 timeout，不计费。/captcha/tasks 不负责推进任务。

​
处理错误

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：
  • 400 token_mismatched：请求错误，可能是由于缺少或无效的参数。
  • 400 api_not_implemented：请求错误，可能是由于缺少或无效的参数。
  • 401 invalid_token：未授权，授权令牌无效或缺失。
  • 429 too_many_requests：请求过多，您已超出速率限制。
  • 500 api_error：内部服务器错误，服务器出现问题。

​
错误响应示例

​
结论

通过本文档，您已经了解了如何使用 Recaptcha3 协议识别 API 让用户无需识别和点选 Recaptcha3 验证码图片，仅需通过提交 Website Key 即可实现后台自动解码，完成验证。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。