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

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

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

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

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

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

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

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

> 📘 الوثائق الكاملة: [واجهة برمجة التطبيقات للتعرف على بروتوكول Recaptcha3 →](https://platform.acedata.cloud/documents/captcha-token-recaptcha3)

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

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، مقارنةً بـ Recaptcha2، نحتاج إلى تمرير معلمة إضافية `page_action`، والتي يجب الحصول عليها من الكود، عنوان URL لعرض سرعة الشبكة هو: `https://recaptcha-demo.appspot.com/recaptcha-v3-request-scores.php`، وفيما يلي طريقة للحصول عليها:

### الطريقة السريعة:

افتح f12، ثم ابحث في صفحة العناصر عن `.execute(`، في منطقة الإطار الأحمر يمكننا رؤية معلمة `action`، بينما تتبع execute سلسلة من الأحرف، وهذا هو المحتوى المطلوب في الأسفل، كما هو موضح في الصورة أدناه.

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

بعد ذلك، تحتاج أيضًا إلى إدخال عنوان URL للموقع الذي يحتاج إلى معالجة رمز التحقق، للحصول على النتيجة المعالجة، يجب أولاً تمرير حقل `website_url` ببساطة، وأخيرًا تحتاج إلى إدخال معلمة `website_key`، والتي يمكن الحصول عليها من النص السابق، وهي أيضًا سلسلة من الأحرف بعد execute. يمكننا بعد ذلك ملء المحتويات المقابلة في الواجهة، كما هو موضح في الصورة:

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

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

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

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

* `page_action`: يجب الحصول عليها من كود الموقع الذي يحتوي على رمز التحقق.
* `website_url`: عنوان URL للموقع الذي يحتاج إلى معالجة رمز التحقق.
* `website_key`: معرف مفتاح الموقع في Recaptcha3.

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

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

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

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

توجد عدة حقول في النتيجة، كما هو موضح أدناه:

* `token`، نتيجة التحقق من مهمة Recaptcha3.

يمكننا أن نرى أننا حصلنا على نتيجة معالجة Recaptcha3، ثم يمكننا استخدامها في POST أو GET لمحاكاة الإرسال إلى الموقع المستهدف، وهي صالحة للاستخدام مرة واحدة لمدة 120 ثانية، يُنصح باستخدامها خلال 60 ثانية. فيما يلي سنقدم باختصار طريقة لتقديم الـ token المولد إلى الموقع المستهدف:

استدعاء كود Python للتحقق من الـ 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
```

لذا يمكننا الحصول على النتيجة:

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

## الوضع غير المتزامن (async)

بشكل افتراضي، تكون واجهة برمجة التطبيقات متزامنة وتنتظر: ستنتظر الطلب حتى يتم معالجة الرمز. إذا كنت تقوم بتدوير حل متعدد (multi-solver rotation) وترغب في "تقديم المهمة والحصول على task\_id على الفور، ثم جدولة حل آخر، والعودة لاحقًا للحصول على النتيجة"، يمكنك تمرير `async: true` في جسم الطلب.

بعد تمرير `async: true`، ستعيد الواجهة على الفور `task_id`، دون الانتظار:

```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}
{
  "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` والرمز:

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

شرح الفوترة: في الوضع غير المتزامن، لا يتم احتساب رسوم لإنشاء المهام أو الاستعلام عن "قيد المعالجة"; **يتم احتساب الرسوم مرة واحدة فقط عند الحصول على النتيجة بنجاح** (بأسعار متطابقة مع الوضع المتزامن). لذلك، فإن إلغاء المهام التي لم تكتمل بعد أثناء التدوير لن ينتج عنه أي رسوم. `/captcha/tasks` متاحة لجميع واجهات برمجة التطبيقات الخاصة بالتحقق من الرموز (token و recognition series) ويمكن استخدام نفس `task_id` للاستعلام.

## معالجة الأخطاء

عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستعيد الواجهة رمز الخطأ والمعلومات ذات الصلة. على سبيل المثال:

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

## الخاتمة

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