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

# توضيح واجهة برمجة التطبيقات للتعرف على بروتوكول Cloudflare Turnstile

> Cloudflare Turnstile Captcha Service API guide - Ace Data Cloud

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

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

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

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

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

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

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

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

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال عنوان URL للموقع الذي يحتاج إلى معالجة CAPTCHA الخاص بـ Turnstile، للحصول على النتيجة المعالجة. يجب أولاً تمرير حقل `website_url` ببساطة، وموقعنا التجريبي هو: `https://react-turnstile.vercel.app`، نحتاج إلى الحصول على `website_key` من صفحة `website_url`، يجب أولاً فتح هذه الصفحة، ثم الضغط على F12 للدخول إلى وحدة التحكم، والبحث عالميًا في صفحة العناصر عن `cf-turnstile`، حيث يمكن العثور على عنصر الحاوية الذي يحمل Turnstile، حيث أن السلسلة المقابلة لـ `data-sitekey` هي قيمة `website_key`.

تتضمن رؤوس الطلب المحددة:

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

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

* `website_url`: عنوان URL للموقع الذي يحتاج إلى معالجة CAPTCHA.
* `website_key`: معرف مفتاح الموقع في Cloudflare Turnstile.
* `action`: معلمة اختيارية، تحتاج فقط إلى تمريرها إذا كان الموقع المستهدف قد أعد `action` مخصصًا لمكون Turnstile.
* `cdata`: معلمة اختيارية، تحتاج فقط إلى تمريرها إذا كان الموقع المستهدف قد أعد `cData` مخصصًا لمكون Turnstile.

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

```json theme={null}
{
  "token": "0.mNQ2f9uP6mQ0y3H5Q8bqO7iM......",
  "started_at": 1784885653.0,
  "finished_at": 1784885665.4,
  "elapsed": 12.4
}
```

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

* `token`: نتيجة التحقق من مهمة CAPTCHA الخاصة بـ Cloudflare Turnstile.
* `started_at`، `finished_at`: الوقت الذي بدأت فيه معالجة الطلب وإنتاج النتيجة، طابع زمني Unix (ثوانٍ، نقطة عائمة).
* `elapsed`: إجمالي الوقت المستغرق في المعالجة (ثوانٍ).

يمكننا أن نرى أننا حصلنا على نتيجة التحقق من CAPTCHA الخاص بـ Turnstile، ثم يمكننا استخدامها في POST أو محاكاة تقديمها إلى الموقع المستهدف، للاستخدام مرة واحدة، وصلاحيتها 120 ثانية، يُنصح باستخدامها خلال 60 ثانية. عادةً ما يتم إرسال هذا الرمز كمعلمة `cf-turnstile-response` معًا إلى الموقع المستهدف، ورمز Python لاستدعاء التحقق من الرمز كما يلي:

```python theme={null}
import requests

token = '{token}'

data = {
    'cf-turnstile-response': token
}

response = requests.post('https://react-turnstile.vercel.app', data=data)

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

إذا كنت ترغب في توليد رمز التكامل المقابل، يمكنك نسخه مباشرة، على سبيل المثال، رمز CURL كما يلي:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/captcha/token/turnstile' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "website_key": "0x4AAAAAAADnPIDROrmt1Wwj",
  "website_url": "https://react-turnstile.vercel.app"
}'
```

رمز التكامل بلغة Python كما يلي:

```python theme={null}
import requests

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

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

payload = {
    "website_key": "0x4AAAAAAADnPIDROrmt1Wwj",
    "website_url": "https://react-turnstile.vercel.app"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

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

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

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

```json theme={null}
{
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}
```

إذا كنت بحاجة إلى التحقق من التقدم، يمكنك استخدام `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`؛ وعند الانتهاء من المعالجة، ستعيد `status: ready` والرمز:

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

توضيح الفوترة: في الوضع غير المتزامن، لا يتم احتساب رسوم لإنشاء المهام أو قراءة حالة "قيد المعالجة"؛ **يتم احتساب الرسوم مرة واحدة عند قراءة العميل للنتيجة الناجحة لأول مرة** (متوافقة مع السلوك الحالي وسعر الوضع المتزامن). ستقوم الخادم بدفع المهام بشكل مستقل، ولكن لن يتم خصم الرسوم مقدمًا لمجرد أن الخلفية قد أكملت المهمة. إذا لم تنجح المهمة خلال 120 ثانية، ستنتهي إلى HTTP 504 `timeout`، ولن يتم احتساب الرسوم. `/captcha/tasks` لا تتحمل مسؤولية دفع المهام.

> ملاحظة: لا يدعم Cloudflare Turnstile استخدام وكيل خاص (Bring Your Own Proxy)، لذا لا تقبل هذه الواجهة معلمة `proxy`؛ إذا تم تمريرها، ستعيد `400 invalid_proxy`.

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

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

* `400 token_mismatched`：طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صالحة.
* `400 invalid_proxy`：طلب غير صالح، الوكيل غير مدعوم لهذا النوع من كابتشا.
* `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"
}
```

## الاستنتاج

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.