> ## 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 verification code recognition service API guide - Ace Data Cloud

تقدم هذه الوثيقة واجهة استعلام مهام التحقق من الرمز غير المتزامنة `POST /captcha/tasks`. عند استدعاء أي واجهة تحقق من الرمز (سلسلة التوكن أو سلسلة التعرف) مع تمرير `async: true`، ستعيد الواجهة على الفور `task_id`، وسيتولى الخادم المعالجة على الفور؛ يمكنك استخدام `task_id` للاستعلام عن النتيجة النهائية، لكن الاستعلام ليس شرطًا لاستمرار تنفيذ المهمة. مناسب لسيناريوهات تبديل المحللين المتعددين (multi-solver rotation): بعد تقديم المهمة، تحصل على `task_id` على الفور، ثم تقوم بجدولة محللين آخرين، وتعود لاحقًا لقراءة النتائج.

> 📘 الوثيقة التفاعلية الكاملة (بما في ذلك التصحيح عبر الإنترنت): [واجهة استعلام مهام التحقق من الرمز →](https://platform.acedata.cloud/documents/captcha-tasks)

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

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

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

### الخطوة الأولى: إنشاء مهمة بطريقة غير متزامنة

في جسم الطلب لأي واجهة تحقق من الرمز، قم بتمرير `async: true`، ستعيد الواجهة على الفور `task_id` (HTTP 201)، دون حظر الانتظار:

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

### الخطوة الثانية (اختياري): استعلام النتائج باستخدام task\_id

إذا كنت بحاجة إلى عرض التقدم بشكل نشط، يمكنك استخدام `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` وحقول النتائج المقابلة - هيكل الحقول متطابق تمامًا مع وضع التزامن:

* **سلسلة التوكن** (hcaptcha، recaptcha2، recaptcha3) تعيد `token`:

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

* **تصنيف التعرف** (recognition/recaptcha2، recognition/hcaptcha) تعيد `solution`؛ **recognition/image2text** تعيد `text`.

`/captcha/tasks` متاحة لجميع واجهات التحقق من الرمز (سلسلة التوكن وسلسلة التعرف) ويمكن استخدام نفس `task_id` للاستعلام.

يستمر الخادم في المعالجة منذ الإنشاء، بحد أقصى 120 ثانية. إذا لم يتم الحصول على نتيجة في آخر استعلام قبل الموعد النهائي، سيتم إرجاع HTTP 504. هذه الحالة هي حالة نهائية، يجب على العميل التوقف عن الاستعلام؛ ستعيد الاستعلامات المتكررة لنفس `task_id` نفس نتيجة الفشل:

```json theme={null}
{
  "detail": "The captcha task timed out.",
  "code": "timeout",
  "success": false,
  "task_id": "61138bb6-19aa-11ec-a9c8-0242ac110002",
  "status": "failed",
  "started_at": 1784885653.0,
  "finished_at": 1784885765.4,
  "elapsed": 112.4
}
```

ستتضمن الاستجابة النهائية لـ `status: ready` وHTTP 504 حقول التوقيت.

* `started_at`، وقت بدء معالجة المهمة، طابع زمني Unix (ثوانٍ، عائم).
* `finished_at`، وقت إنتاج نتيجة المهمة، طابع زمني Unix (ثوانٍ، عائم). لن يتم إرجاع هذا الحقل أثناء المعالجة.
* `elapsed`، الوقت المستغرق في معالجة المهمة، وحدة بالثواني (عائم، يحتفظ بـ 3 أرقام عشرية). لن يتم إرجاع هذا الحقل أثناء المعالجة.

## توضيح الفوترة

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

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

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

* `400 invalid_request`: الطلب يفتقر إلى معلمة `task_id`.
* `401 invalid_token`: غير مصرح، رمز التفويض غير صالح أو مفقود.
* `404 not_found`: `task_id` غير موجود، أو لا ينتمي إلى الحساب الحالي.
* `504 timeout`: تم إنهاء المهمة ولم يتم إنتاج نتيجة؛ يرجى التوقف عن الاستعلام عن `task_id` هذا. لن يتم احتساب رسوم لهذا الفشل.

### مثال على استجابة الخطأ

```json theme={null}
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "task not found"
  }
}
```


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