> ## 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.

# hCaptcha بروتوكول التعرف على API توصيل التعليمات

> hCaptcha verification code recognition service API guide - Ace Data Cloud

ستقدم هذه الوثيقة شرحًا عن كيفية توصيل بروتوكول التعرف على hCaptcha API، والذي يسمح للمستخدمين بتجاوز التعرف على صور التحقق من hCaptcha والنقر عليها، حيث يمكنهم فقط تقديم مفتاح الموقع لتحقيق فك التشفير التلقائي في الخلفية وإكمال التحقق.

## عملية التقديم

لاستخدام بروتوكول التعرف على hCaptcha API، يجب أولاً الذهاب إلى [لوحة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications) للحصول على رمز API الخاص بك، للاحتفاظ به كنسخة احتياطية.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد الانتهاء، سيتم العودة تلقائيًا إلى الصفحة الحالية.

**رمز API واحد يكفي لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة.** عند التقديم لأول مرة، ستحصل على رصيد مجاني لتجربته مجانًا؛ وعند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في [لوحة التحكم](https://platform.acedata.cloud/console/coin).

> 📘 الوثائق الكاملة: [hCaptcha بروتوكول التعرف على API →](https://platform.acedata.cloud/documents/captcha-token-hcaptcha)

## الاستخدام الأساسي

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال URL الموقع الذي يحتاج إلى معالجة رمز التحقق hCaptcha، للحصول على النتيجة المعالجة. أولاً، نحتاج إلى تمرير حقل `website_url` ببساطة، وموقعنا التجريبي هو: `https://accounts.hcaptcha.com/demo`، نحتاج إلى الحصول على `website_key` من صفحة `website_url`، يجب أولاً فتح هذه الصفحة، ثم الضغط على F12 للدخول إلى وحدة التحكم، وأخيرًا إجراء بحث شامل في صفحة العناصر عن `hcaptcha-demo`، وسنحصل على النتيجة التالية:

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

حيث أن السلسلة المقابلة لـ `data-sitekey` هي قيمة `website_key`، وفيما يلي النتائج المحددة للمعلمات:

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

يمكننا أن نرى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:

* `accept`: نوع التنسيق الذي ترغب في تلقيه كاستجابة، هنا يتم ملؤه بـ `application/json`، أي بتنسيق JSON.
* `authorization`: مفتاح استدعاء API، يمكن اختياره مباشرة بعد التقديم.

بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:

* `website_url`: URL الموقع الذي يحتاج إلى معالجة رمز التحقق.
* `website_key`: معرف مفتاح الموقع في hCaptcha.

بعد الاختيار، يمكننا أن نلاحظ أن الجانب الأيمن قد أنشأ أيضًا الكود المقابل، كما هو موضح في الصورة:

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

يمكنك النقر على زر "Try" لإجراء الاختبار، كما هو موضح في الصورة أعلاه، وهنا حصلنا على النتيجة التالية:

```json theme={null}
{
  "token": "P1_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.hadwYXNza2V5xQda4nQzFgUbYJqILiiwbvyhjocSilg8RjFHvIHmCzmqUNZa9hesIWEVRx5KIbMVeAQzSTWCwXmiQrPZuIEmZz-ZPL6DPNmB3ZXtJNsVYRLdRyvWPTB7EYskJG85yDVor2TcgQFNqAahhKT3WXjtk3S54ZBhv7QvaImUmos8MWgUOvUZHsvUtojN-izWIrBkD1if_71quOHvcvEVTLcSLx9dOgzpNAJ8_6BmJEsGlPbMGnSKrS1QfpPyzvgrnpjjIY_6TMYwJrR0EwJgCdp_lfc4mkxl0NJsZt8D_q7jcv3v6jt1CZ2qbqF5_-i4y0MYnQMCm1T62xBPdiEyst_FtGuWxJllkrrmWN0edyWcWeasLcCS6qpRry0H7RU7DYQnML6dmQoZg15NT0tFrAYeLK7EwvJxzcFbvUQ-Tc5QVk7tzvKpDtUVfQeZmRRgxWbCFf6bAT1z0uUwdma1O1lcTkSZCC5cVTaprkkKE04Ov4aCIKg2N7WGj4r0AOykisAISX5oidF3gejDTJy9vU1hgaCYFOimnwRKyqRsJdznptzhzDOQuICuAHYT3is1sY26ltJGOZTdDKkt2i2owCoAylgLbBP8VjTOGrsM12IH3Xsy076O40RCG6zThWN5TFKSpl7PNA6l2KoW-P3_K9WORjx2DSvKTAwqcouSU-0Rc_8Hlq9cIuS1iDhiNfJnJ_zNy_2gXSR2j7NP7m_lsfwELKypKm6pPzIhOuz5RwPotfPQfXOMdF3Xy98iQiihZmuHENvLAhjV_W7NL9TK3THPwDTFriS8ghIncl02v-fVARXDiuFTvjjlegL7xbHgIrOhLpunsxLiwdImUWatEI9jqaf84X4BtoS0TGYo4pHkpIG10dhoz3vooeSToAws6tz7ZWSHm6naksZ41X_WIxd7N8P9yzxrbLgVv-nHia5qHQLDmiZf3alITKhtisennw8NpespaQIVZzw_B16bdUNKqHCCTLdFbr16-3KpRoHzOOU2kBhV-gDN0NiA3ecqIMnyMdnpKlUpnjJ5sMA3e0pKEX_Vbu8DE8zfkcwLIwCIb2BLrKEHnCvv4JX8TfBktzMc5oTtZyEu-E_6ew0mSm_nhVsGtmLXSsB81FP9VGGRd50buIXRNW4GFp3XdTmYyuN32kc-AHJ5kKDj2HGraHxKco0McT7nV2bgx97k-C7hgxL2x5t3lC97edphh2kt2-gXuTxxfB7K-ZG6w5d1MnRte4ZG7TxvPFFi5693IFRFbvcr-U3WyGZJmGGdfV55PnoIU9Qn-WDtBU4EXyvd_KTt-asHtI6VQiVSNzacemTfsu9WBF33f2gafDY4qqhyXDPNsu6BZCGMSBhxDPURY74OBr4mYOdhjELY07nSkr9RQtQwiiSa8B8XFlezCPafjgdbmmNzG3PXa3n23sSwVnJHpHhq79eTP_KeeCiqlCvNsHLEfiH5HCNRGp7v5b342wBk__BWFimJMvohz0rucTVYgVFBdTOomUTuqCPeUgDP3X6BnNqyVDRA-HrdRl-RkU6mnw-3-IwyMZQ-fEnFMzbGp3zaoY7Do2jKvKKILoq6Q8zlDYkrLwuXjDP-nernI2hxP9wVOUVmtq5Rs19RLUI4MNWZAqwG-wGnaoB756d8nfmh5XhFzvArE5bpL50FY1yJqv7nbPW7JNnkfZG80yVRrIZO_F9NEb3n4eiIzg9Gu9fv8ncyChiCCp-swK5B7_w-XsAlco98bO-YK-fFMJOhyt0PU8Zc-hYoCa6cLVTvhdPzIUA0CQOemg4Pz6PX6SVwLYSlOXYkzbrgBlyH5YBS3oaRCeavVLrJsKt0_KwHwgBa1mdP5mlYUpBDbKR4PKwknU7y111JH0B4fO39dOVA-zecvDG0bnuy98Jym4KUchZr1tXabMcM20mg1UvcxMfnKOx0ojBcVwYA7kPQK3EzMnwX9NbAzYP6IlMgjFK9ZM7HCXxN6J1_6kw10RT4O58-Pbh3cMSrZDfM-GuG7p7XrVpJrX8TD195DCJqx-DmVv3Bs3CiuCPTvGrSZ58KE4hQagidGreUD2WXxLBFfTv1RgM3eXMtROs7hddyBajIu401lxucNbpRB7lYV7pJwxG7LQoSZ2G2LzG8eFPVPIkDNVOa8nGzh-sWaF7kc7bVv-P4FXbLX0WCjvQRES2MCbXPyJ-OpZZXZcJy7SOsGY3jZbTkGoez19cRQLiFO35gA5l9FBptDKW-_yGemt5XeKsR_FwGPN9C-0k1E-28oB4iKo-h1zb2kJpilhnmG36Z59F5T6W77M7OD_N6VHRWuPClLElO09OrPLHbJmxq9JvMWjTg5JjEaqyTLyLXWgw0N3kZMCqJJeqNj5w5I7dpuJ6ScfXKVaT96v2UESebdbMFT7vkZAkFF8LIowkN56pNwXLHkB2KyIWR2WQL-335BEpQ0AVB6RX4kdociIhtvAdsIE6pvFIwkzyO0OvIHxzOwPxZKdmDmBVMu7YxJStrhY-XWCu4kO5gDIJ0iedPWKNleHDOZuZqGKhzaGFyZF9pZM4xrUyBomtyqDE1ZmUwNDhkonBkAA.dVWyVc6N3lx2ZJQ7NJ9aEsWA-KAIuQ4PMSKVGQuWyCA"
}
```

可以看到我们得到了处理 hCaptcha验证码 的验证结果，然后我们可以用于POST或模拟提交给目标网站，一次性使用，有效期120s，建议在60s内使用，接下来将提供一段CURL版本将处理后token提交到目标网站来通过Recaptcha2验证码。

首先我们需要获取网站是如何发送POST请求，这样我们才能将生成的token传入进去，我们需要先打开F12控制台，然后人工先通过一下，最后我们可以看到网站发送了一个POST请求，我们只需要查看这次的POST请求构造，具体的过程如下：

* 先人工通过验证，具体的如下图：

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

* 再点击submit，观看控制台的network变化，具体的如下图：

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

* 分析此次提交的POST请求构造，最后可以右键该请求复制CURL的代码，具体的如下图：

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

由上图分析可知，此次POST请求的URL为：`https://accounts.hcaptcha.com/demo`，我们仅需要提交参数 `g-recaptcha-response`、`h-captcha-response` 和 `email`，然后我们只需要将处理后的token传入下面的data中即可，调用token验证所对应CURL代码如下：

```shell theme={null}
curl 'https://accounts.hcaptcha.com/demo' \
  --data-raw 'email=&g-recaptcha-response={token}&h-captcha-response={token}'
```

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

```python theme={null}
import requests

token = '{token}'

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

response = requests.post('https://accounts.hcaptcha.com/demo',
                        data=data)

if response.status_code == 200:
    print(response.text)

```

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

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

最后我们就通过了hCaptcha验证码的验证。

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

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/captcha/token/hcaptcha' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_key": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
  "website_url": "https://accounts.hcaptcha.com/demo"
}'
```

Python 的对接代码如下：

```python theme={null}
import requests

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

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

payload = {
    "website_key": "a5f74b19-9e45-40e0-b45d-47ff91b7a6c2",
    "website_url": "https://accounts.hcaptcha.com/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`，而不会阻塞等待：

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

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

## 错误处理

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

* `400 token_mismatched`：请求错误，可能是由于缺少或无效的参数。
* `400 api_not_implemented`：请求错误，可能是由于缺少或无效的参数。
* `401 invalid_token`：未授权，授权令牌无效或缺失。
* `429 too_many_requests`：请求过多，超出了速率限制。
* `500 api_error`：内部服务器错误，服务器出现问题。

### 错误响应示例

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

## 结论

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