> ## 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 descripción de la integración de la 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 código 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 la 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; 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, es importante entender la forma básica de uso, que consiste en ingresar la URL del sitio web que necesita procesar el código 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 realiza una búsqueda global en la página de Elementos por `recaptcha-demo`, así obtendremos el siguiente resultado:

<p>
  <img src="https://cdn.acedata.cloud/hvx41c.png" width="500" className="m-auto" />
</p>

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

<p>
  <img src="https://cdn.acedata.cloud/8oowyw.png" width="500" className="m-auto" />
</p>

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 a la API, que puedes seleccionar directamente después de solicitarla.

Además, se ha configurado el Cuerpo de Solicitud, que incluye:

* `website_url`: la URL del sitio web que necesita procesar el código captcha.
* `website_key`: el identificador de la clave del sitio en Recaptcha2.

Después de seleccionar, puedes notar que también se ha generado el código correspondiente a la derecha, como se muestra en la imagen:

<p>
  <img src="https://cdn.acedata.cloud/pudujk.png" width="500" className="m-auto" />
</p>

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": "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"
}
```

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.

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, de esta manera podremos pasar el token generado. Necesitamos abrir la consola F12, luego realizar la verificación manualmente, y al final podremos 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, realizar la verificación manualmente, como se muestra en la siguiente imagen:

<p>
  <img src="https://cdn.acedata.cloud/gwiflr.png" width="500" className="m-auto" />
</p>

* Luego, hacer clic en enviar, observar los cambios en la red de la consola, como se muestra en la siguiente imagen:

<p>
  <img src="https://cdn.acedata.cloud/6hm5kj.png" width="500" className="m-auto" />
</p>

* Analizar la construcción de la solicitud POST enviada, al final se puede hacer clic derecho en esa solicitud y copiar el código CURL, como se muestra en la siguiente imagen:

<p>
  <img src="https://cdn.acedata.cloud/m7y35w.png" width="500" className="m-auto" />
</p>

由上图分析可知，此次POST请求的URL为：`https://www.google.com/recaptcha/api2/demo`，我们仅需要提交参数 `g-recaptcha-response`，然后我们只需要将处理后的token传入下面的data中即可，调用token进行验证的具体的CURL代码如下：

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

调用token验证所对应的Python代码如下：

```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)

```

然后我们运行后代码观察控制台变得了这样的结果：

<p>
  <img src="https://cdn.acedata.cloud/ku22tk.png" width="500" className="m-auto" />
</p>

最后我们就通过了Recaptcha2验证码的协议验证。

另外如果想生成对应的对接代码，可以直接复制生成，例如 CURL 的代码如下：

```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"
}'
```

Python 的对接代码如下：

```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)
```

## 异步模式（async）

默认情况下 API 是同步阻塞的：一次请求会一直等待，直到 token 处理完成才返回。如果你在做多打码器轮换（multi-solver rotation），希望「提交任务后立即拿到 task\_id，先去调度其他打码器，稍后再回来取结果」，可以在请求体中传入 `async: true`。

传入 `async: true` 后，接口会立即返回一个 `task_id`，而不会阻塞等待：

```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}
{
  "success": true,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab",
  "status": "processing"
}
```

随后使用该 `task_id` 轮询 `POST /captcha/tasks`（建议每 3\~5 秒一次）来获取结果：

```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"
}'
```

处理中会返回 `status: processing`：

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

处理完成会返回 `status: ready` 和 token：

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

计费说明：异步模式下，创建任务与轮询「处理中」都不计费；**仅在成功取到结果时计费一次**（与同步模式的价格一致）。因此在轮换中取消尚未完成的任务不会产生费用。`/captcha/tasks` 对所有验证码接口（token 与 recognition 系列）通用，用同一个 `task_id` 轮询即可。

## 错误处理

在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：

* `400 token_mismatched`：Bad request, possibly due to missing or invalid parameters.
* `400 api_not_implemented`：Bad request, possibly due to missing or invalid parameters.
* `401 invalid_token`：Unauthorized, invalid or missing authorization token.
* `429 too_many_requests`：Too many requests, you have exceeded the rate limit.
* `500 api_error`：Internal server error, something went wrong on the server.

### 错误响应示例

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

## 结论

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