انتقل إلى المحتوى

توثيق API

ثلاث نقاط نهاية، وأمثلة شيفرة كاملة بست لغات. أكمل التكامل في أقل من 60 ثانية مع عنقود أدوات الحل عالي الأداء من Capzy.

البدء السريع

الخطوة 1
POST /createTask

أرسل نوع الكابتشا ومعاملات الموقع. احصل على taskId فورًا.

الخطوة 2
POST /getTaskResult

استعلم كل ثانية تقريبًا حتى تصبح الحالة ready. يصل الرمز في كائن solution.

الخطوة 3
POST /getBalance

تحقّق من الرصيد المتبقي. تُسترد عمليات الحل الفاشلة هنا تلقائيًا.

عنوان URL الأساسيhttps://api.capzy.aiالمصادقة عبر clientKey في نص الطلب

نقاط النهاية

POST/createTaskإنشاء مهمة جديدة لحل كابتشا
الطلب
{
  "clientKey": "capzy_...",
  "task": {
    "type": "AntiTurnstileTaskProxyLess",
    "websiteURL": "https://example.com",
    "websiteKey": "0x4AAA..."
  }
}
الاستجابة
{
  "errorId": 0,
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "status": "processing"
}
POST/getTaskResultالاستعلام عن نتيجة المهمة
الطلب
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
الاستجابة
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "0.eyJhbGci..."
  }
}
POST/getBalanceالتحقق من رصيد الحساب
الطلب
{ "clientKey": "capzy_..." }
الاستجابة
{ "errorId": 0, "balance": 9.50 }
POST/reportScoreاختياري: أبلغ عن النقاط التي تحقّقت منها Google لمهام V3. يغذّي عرض جودة V3 في لوحة التحكم. تقرير واحد لكل مهمة؛ ويجب أن تصل التقارير خلال 24 ساعة من اكتمال الحل.
الطلب
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
  "score": 0.9,
  "action": "login",
  "hostname": "example.com"
}
الاستجابة
{ "errorId": 0 }
POST/reportCorrectCaptchaاختياري: أخبرنا بأن الموقع المستهدف قبِل الحل. مفيد بشكل خاص للأنواع التي تُرجع إحداثيات (مثل شريط التمرير في Shopee) حيث نُرجع موضعًا ويجري متصفحك عملية السحب. هذا التقرير هو مؤشرنا الوحيد على الدقة الفعلية. تقرير واحد لكل مهمة، خلال 24 ساعة؛ ولا يؤثر أبدًا في الأسعار.
الطلب
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
الاستجابة
{ "errorId": 0 }
POST/reportIncorrectCaptchaاختياري: أخبرنا بأن الموقع المستهدف رفض الحل. يغذّي تتبّع الدقة الفعلية نفسه مثل /reportCorrectCaptcha. تقرير واحد لكل مهمة، خلال 24 ساعة؛ ولا يؤثر أبدًا في الأسعار.
الطلب
{
  "clientKey": "capzy_...",
  "taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}
الاستجابة
{ "errorId": 0 }

أنواع المهام المدعومة

جارٍ التحميل…

قائمة مباشرة بأنواع المهام المفعّلة حاليًا، مجمّعة حسب مزوّد الكابتشا. تُحدَّث الأسعار ومتوسط وقت الحل تلقائيًا من بيانات العنقود.

جارٍ تحميل أنواع المهام…

حدود المعدل

تُطبَّق الحدود لكل حساب، مجمّعة عبر جميع مفاتيح API التي تملكها. يؤدي تجاوز الحد إلى إرجاع رمز خطأ دون استهلاك الرصيد.

افتراضي
30 متزامن · 30 طلبًا/ثانية

يبدأ كل حساب جديد هنا

تزامن أعلى
300+ متزامن · أكثر من 100 طلب/ثانية

افتح تذكرة دعم بالحجم المتوقع (لا توجد فئة سعرية منفصلة، والسعر نفسه لكل عملية حل)

المهام المتزامنة

عدد المهام التي يمكن أن تكون في قائمة انتظار الحل في وقت واحد. تُحتسب المهمة ضمن حدك من createTask حتى تنتهي (نجاحًا أو فشلًا أو انتهاء مهلة).

حد المعدل

عدد استدعاءات createTask التي يمكنك إجراؤها في الثانية. نافذة منزلقة تُطبَّق لكل حساب. يؤدي تجاوز المعدل إلى إرجاع ERROR_RATE_LIMITED دون خصم أي رصيد.

رموز الأخطاء

كل خطأ تُرجعه /createTask / /getTaskResult مع طريقة إصلاحه. تُسترد عمليات الحل الفاشلة تلقائيًا: يعود الرصيد إلى حسابك فورًا.

المصادقة

مشكلات في مفتاح API أو عنوان IP.
  • ERROR_KEY_DOES_NOT_EXIST

    لم يتم التعرّف على مفتاح API الخاص بك.

    الإصلاحتحقّق مجددًا من القيمة في لوحة التحكم ← مفاتيح API. تبدأ المفاتيح بـ `capzy_`. تُبطَل المفاتيح التي تم تدويرها فورًا.

    #
  • ERROR_IP_NOT_ALLOWED

    عنوان IP الخاص بطلبك غير موجود في قائمة السماح لمفتاح API.

    الإصلاحأضف عنوان IP إلى قائمة السماح للمفتاح في لوحة التحكم ← مفاتيح API، أو أزل قائمة السماح كليًا إذا لم تكن بحاجة إلى تثبيت عنوان IP.

    #
  • ERROR_IP_BLOCKED

    عنوان IP الخاص بك محظور مؤقتًا بسبب إرسال طلبات غير صالحة كثيرة جدًا.

    الإصلاحنحظر عناوين IP التي ترسل أكثر من 100 طلب غير صالح خلال 10 دقائق (بشكل متصاعد). أصلح الخلل المسبب للطلبات غير الصالحة، ثم انتظر. ينتهي الحظر تلقائيًا بعد مدة تتراوح من دقيقة واحدة إلى 24 ساعة بحسب الفئة.

    #

التحقق من الصحة

معاملات مهمة خاطئة أو نوع غير صحيح لـ sitekey.
  • ERROR_INVALID_PARAMS

    نص الطلب مشوّه أو تنقصه حقول مطلوبة.

    الإصلاحتأكد من أن `clientKey` في المستوى الأعلى وأن `task` يحتوي على `type` بالإضافة إلى المعرّف المطلوب (websiteURL/websiteKey/captchaId/إلخ). راجع قسم أنواع المهام لمعرفة المعاملات المطلوبة لكل نوع.

    #
  • ERROR_BAD_SITEKEY

    قيمة `websiteKey` غير مسجّلة لدى أي مزوّد كابتشا يمكننا تحديده.

    الإصلاحتأكد من نسخ sitekey كاملًا من الصفحة المستهدفة (ابحث عن `data-sitekey` أو `sitekey:` أو المعامل في `grecaptcha.render` / `hcaptcha.render`).

    #
  • ERROR_TASK_NOT_SUPPORTED

    قيمة `type` التي أرسلتها ليست نوع كابتشا يدعمه Capzy حاليًا.

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

    #
  • ERROR_WRONG_TASK_TYPE

    نوع المهمة لا يطابق المزوّد الفعلي لـ sitekey.

    الإصلاحنفحص sitekey مسبقًا مقابل مزوّده الحقيقي. تتضمن استجابة الخطأ حقل `recommended`: انتقل إلى نوع المهمة ذاك. (لا يُخصم أي رصيد.)

    #
  • ERROR_PROXY_REQUIRED

    هذه الكابتشا مرتبطة بعنوان IP: رموزها مقيّدة بعنوان IP الذي حلّها.

    الإصلاحانتقل إلى صيغة `*Task` (بدلًا من `*TaskProxyLess`) ومرّر `proxyAddress` المطابق لعنوان IP الذي ستستخدمه لإرسال الرمز. ينطبق على: Cloudflare Challenge وCaptchaFox وAWS WAF وDataDome وPerimeterX وKasada وAkamai وImperva.

    #
  • ERROR_NO_PROXY

    حقول البروكسي مطلوبة لنوع المهمة هذا لكنها مفقودة.

    الإصلاحأدرج `proxyType` و`proxyAddress` و`proxyPort` (واختياريًا `proxyLogin`/`proxyPassword`/`userAgent`) في نص المهمة.

    #
  • ERROR_PROXY_CONNECT_REFUSED

    رفض البروكسي الذي قدّمته الاتصال.

    الإصلاحتحقّق من بيانات اعتماد البروكسي، وإمكانية الوصول إلى المضيف، وأن عنوان IP يعمل. جرّب البروكسي نفسه من جهازك أولًا لعزل مشكلات المزوّد.

    #

حدود المعدل

حدود التزامن / الطلبات في الثانية / نسبة الاسترداد.
  • ERROR_MAX_TASKS_REACHED

    لقد بلغت حد المهام المتزامنة لفئة حسابك.

    الإصلاحانتظر حتى تنتهي المهام الجارية قبل إرسال المزيد. الحد الافتراضي للفئة العادية 30 مهمة متزامنة؛ تواصل مع الدعم للترقية.

    #
  • ERROR_RATE_LIMITED

    ترسل طلبات /createTask أسرع من حد المعدل الخاص بك.

    الإصلاحأبطئ وأعد المحاولة. الحد الافتراضي للفئة العادية 30 طلبًا/ثانية بنافذة منزلقة. تجاوز المعدل لا يستهلك رصيدًا.

    #
  • ERROR_NO_SLOT_AVAILABLE

    سعة العنقود مشبعة مؤقتًا.

    الإصلاحأعد المحاولة بعد بضع ثوانٍ (هذا أمر مؤقت). إذا استمر لدقائق، تحقّق من status.capzy.ai.

    #
  • ERROR_SYSTEM_MAINTENANCE

    Capzy في صيانة مجدولة.

    الإصلاحأعد المحاولة بعد انتهاء فترة الصيانة. ننشر إشعارات مسبقة في صفحة الحالة.

    #

نتائج الحل

ما أرجعته أداة الحل. تُسترد عمليات الحل الفاشلة تلقائيًا.
  • ERROR_TIMEOUT

    لم تكتمل المهمة ضمن المهلة القصوى المحددة لنوعها.

    الإصلاحاسترداد تلقائي، بلا رسوم. معظم حالات انتهاء المهلة مؤقتة. إذا كانت كابتشا معيّنة تنتهي مهلتها باستمرار، افتح تذكرة مع UUID المهمة.

    #
  • ERROR_CAPTCHA_UNSOLVABLE

    استنفدت أداة الحل ميزانية إعادة المحاولة لهذا التحدي.

    الإصلاحاسترداد تلقائي، بلا رسوم. الأسباب الشائعة: sitekey قديم، أو أن websiteURL لا يطابق النطاق المضمِّن، أو أن الموقع المستهدف عطّل الكابتشا.

    #
  • ERROR_NULL_RESULT

    انتهت أداة الحل لكنها لم تُرجع أي رمز.

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

    #
  • ERROR_INTERNAL

    خطأ غير متوقع داخل مسار الحل.

    الإصلاحاسترداد تلقائي. أعد المحاولة (هذه الأخطاء نادرة). إذا رأيتها في حلقة متكررة، افتح تذكرة مع UUID المهمة.

    #
  • ERROR_ZERO_BALANCE

    رصيد الحساب منخفض جدًا لتغطية تكلفة المهمة.

    الإصلاحأضف رصيدًا من لوحة التحكم ← الفوترة. تُسترد عمليات الحل الفاشلة تلقائيًا، فلا تدفع إلا مقابل الرموز الناجحة.

    #

الإبلاغ عن النقاط

أخطاء خاصة بـ /reportScore (ملاحظات جودة V3).
  • ERROR_TASK_NOT_FOUND

    /reportScore: لا ينتمي taskId إلى حسابك أو تم حذفه.

    الإصلاحيجب أن تشير تقارير النقاط إلى مهمة تملكها، وأن تُقدَّم خلال 24 ساعة من اكتمال الحل.

    #
  • ERROR_TASK_NOT_READY

    /reportScore: المهمة لا تزال قيد المعالجة أو فشلت بالفعل.

    الإصلاحلا يمكن تقييم سوى المهام بحالة `ready`. انتظر حتى يُرجع /getTaskResult الحالة ready قبل الإبلاغ.

    #
  • ERROR_REPORT_TOO_LATE

    /reportScore: مرّ أكثر من 24 ساعة منذ اكتمال الحل.

    الإصلاحأبلغ عن النقاط خلال دقائق من استدعاء siteverify. حينها تكون البيانات أكثر فائدة للوحة جودة V3 لدينا.

    #
06

بيئة تجربة الشيفرة

أمثلة عملية كاملة بكل اللغات الرئيسية. انسخ، والصق مفتاح API، وشغّل.

solve.py
import requests, time

API = "https://api.capzy.ai"
KEY = "capzy_your_key_here"

# Create task
task = requests.post(f"{API}/createTask", json={
    "clientKey": KEY,
    "task": {
        "type": "AntiTurnstileTaskProxyLess",
        "websiteURL": "https://example.com",
        "websiteKey": "0x4AAA..."
    }
}).json()

task_id = task["taskId"]

# Poll for result
while True:
    result = requests.post(f"{API}/getTaskResult", json={
        "clientKey": KEY,
        "taskId": task_id
    }).json()

    if result["status"] == "ready":
        token = result["solution"]["token"]
        print(f"Solved: {token[:50]}...")
        break
    elif result["status"] == "failed":
        print(f"Failed: {result.get('errorDescription')}")
        break

    time.sleep(1)
معاينة المخرجاتنجاح (200 OK)
{ "errorId": 0, "status": "ready", "solution": { "token": "0.eyJhbGci..." } }

أكمل التكامل في أقل من 60 ثانية.

رصيد مجاني بقيمة $0.10 عند التسجيل. لا حاجة إلى بطاقة ائتمان.

احصل على مفتاح API المجاني ←