توثيق API
ثلاث نقاط نهاية، وأمثلة شيفرة كاملة بست لغات. أكمل التكامل في أقل من 60 ثانية مع عنقود أدوات الحل عالي الأداء من Capzy.
البدء السريع
POST /createTaskأرسل نوع الكابتشا ومعاملات الموقع. احصل على taskId فورًا.
POST /getTaskResultاستعلم كل ثانية تقريبًا حتى تصبح الحالة ready. يصل الرمز في كائن solution.
POST /getBalanceتحقّق من الرصيد المتبقي. تُسترد عمليات الحل الفاشلة هنا تلقائيًا.
https://api.capzy.aiالمصادقة عبر clientKey في نص الطلبنقاط النهاية
/createTaskإنشاء مهمة جديدة لحل كابتشا{
"clientKey": "capzy_...",
"task": {
"type": "AntiTurnstileTaskProxyLess",
"websiteURL": "https://example.com",
"websiteKey": "0x4AAA..."
}
}{
"errorId": 0,
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
"status": "processing"
}/getTaskResultالاستعلام عن نتيجة المهمة{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{
"errorId": 0,
"status": "ready",
"solution": {
"token": "0.eyJhbGci..."
}
}/getBalanceالتحقق من رصيد الحساب{ "clientKey": "capzy_..." }{ "errorId": 0, "balance": 9.50 }/reportScoreاختياري: أبلغ عن النقاط التي تحقّقت منها Google لمهام V3. يغذّي عرض جودة V3 في لوحة التحكم. تقرير واحد لكل مهمة؛ ويجب أن تصل التقارير خلال 24 ساعة من اكتمال الحل.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca",
"score": 0.9,
"action": "login",
"hostname": "example.com"
}{ "errorId": 0 }/reportCorrectCaptchaاختياري: أخبرنا بأن الموقع المستهدف قبِل الحل. مفيد بشكل خاص للأنواع التي تُرجع إحداثيات (مثل شريط التمرير في Shopee) حيث نُرجع موضعًا ويجري متصفحك عملية السحب. هذا التقرير هو مؤشرنا الوحيد على الدقة الفعلية. تقرير واحد لكل مهمة، خلال 24 ساعة؛ ولا يؤثر أبدًا في الأسعار.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{ "errorId": 0 }/reportIncorrectCaptchaاختياري: أخبرنا بأن الموقع المستهدف رفض الحل. يغذّي تتبّع الدقة الفعلية نفسه مثل /reportCorrectCaptcha. تقرير واحد لكل مهمة، خلال 24 ساعة؛ ولا يؤثر أبدًا في الأسعار.{
"clientKey": "capzy_...",
"taskId": "df944101-64ac-468d-bc9f-41baecc3b8ca"
}{ "errorId": 0 }أنواع المهام المدعومة
جارٍ التحميل…قائمة مباشرة بأنواع المهام المفعّلة حاليًا، مجمّعة حسب مزوّد الكابتشا. تُحدَّث الأسعار ومتوسط وقت الحل تلقائيًا من بيانات العنقود.
حدود المعدل
تُطبَّق الحدود لكل حساب، مجمّعة عبر جميع مفاتيح API التي تملكها. يؤدي تجاوز الحد إلى إرجاع رمز خطأ دون استهلاك الرصيد.
يبدأ كل حساب جديد هنا
افتح تذكرة دعم بالحجم المتوقع (لا توجد فئة سعرية منفصلة، والسعر نفسه لكل عملية حل)
المهام المتزامنةعدد المهام التي يمكن أن تكون في قائمة انتظار الحل في وقت واحد. تُحتسب المهمة ضمن حدك من 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_MAINTENANCECapzy في صيانة مجدولة.
الإصلاحأعد المحاولة بعد انتهاء فترة الصيانة. ننشر إشعارات مسبقة في صفحة الحالة.
نتائج الحل
ما أرجعته أداة الحل. تُسترد عمليات الحل الفاشلة تلقائيًا.- #
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 لدينا.
بيئة تجربة الشيفرة
أمثلة عملية كاملة بكل اللغات الرئيسية. انسخ، والصق مفتاح API، وشغّل.
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)الموارد
أكمل التكامل في أقل من 60 ثانية.
رصيد مجاني بقيمة $0.10 عند التسجيل. لا حاجة إلى بطاقة ائتمان.
احصل على مفتاح API المجاني ←