[ API ]

API واحدة لحل الكابتشا
لكل أنواع التحديات

غيّر الحقل type، وليس التكامل لديك. كل تحدٍّ ندعمه يتشارك شكل طلب واحدًا وشكل استجابة واحدًا.

الطلب

POST https://api.captchano.com/v1/solve?wait=60
Authorization: Bearer cn-YOUR_API_KEY
Content-Type: application/json

{
  "type":    "recaptcha_v2",
  "url":     "https://example.com/login",
  "sitekey": "6LcABC...",

  "proxy":     "http://user:pass@host:port",
  "userAgent": "Mozilla/5.0 ..."
}

الاستجابة

200 OK

{
  "id":        "slv_3f9c0a7e1b2d4c6e8f0a1b2c",
  "status":    "ready",
  "type":      "recaptcha_v2",
  "solution":  {
    "token":     "03AGdBq25S...",
    "userAgent": "Mozilla/5.0 ..."
  },
  "cost":      "0.00598",
  "solveTime": 12.4,
  "createdAt": 1767225600000
}

المصادقة

أرسل مفتاحك على شكل Authorization: Bearer cn-… (أو في الترويسة X-API-Key). أنشئ المفاتيح وألغِها من لوحة التحكم. تُعرض المفاتيح مرة واحدة وتُخزَّن مشفّرة بدالة تجزئة (hash)، لذا احتفظ بنسخة في مكان آمن.

نقاط النهاية

POST /v1/solve — أرسل تحديًا. بدون wait تُعيد 202 مع id وstatus: "solving". ومع ?wait=N (حتى 120 ثانية) يبقى الطلب معلقًا حتى يجهز الحل ويُعيد 200، أو يُعيد 202 إذا كان الحل لا يزال جاريًا عند انتهاء مدة الانتظار.
GET /v1/task/{id} — استطلع حالة مهمة. استطلع كل خمس ثوانٍ؛ تنتقل الحالة من solving إلى ready أو failed. يبقى الحل المدفوع قابلًا للاسترجاع لمدة عشر دقائق.
GET /v1/balance — رصيدك المتبقي بالدولار الأمريكي.

أنواع التحديات

recaptcha_v2 — ⁦url وsitekey؛ واختياريًا invisible⁩. ⁦$0.00598⁩ لكل عملية حل ناجحة.
recaptcha_v3 — ⁦url وsitekey؛ واختياريًا action وminScore⁩. ⁦$0.00598⁩ لكل عملية حل ناجحة.
recaptcha_enterprise — ⁦url وsitekey؛ واختياريًا invisible — أدوات Enterprise بنمط مربع الاختيار (مفاتيح Enterprise القائمة على النقاط غير مدعومة)⁩. ⁦$0.00598⁩ لكل عملية حل ناجحة.
turnstile — ⁦url وsitekey؛ واختياريًا action وcData وpageData⁩. ⁦$0.00435⁩ لكل عملية حل ناجحة.
datadome — ⁦url وchallengeUrl وproxy (مطلوب) وuserAgent⁩. ⁦$0.00435⁩ لكل عملية حل ناجحة.
image — ⁦body (صورة بترميز base64)⁩. ⁦$0.003⁩ لكل عملية حل ناجحة.

الحقول التي تحدد القبول

يأخذ proxy سلسلة نصية مثل http://user:pass@host:port (تُقبل http وsocks4 وsocks5). وهو اختياري في التحديات القائمة على الرموز token ومطلوب في DataDome. تمرير البروكسي نفسه الذي سيُرسل الرمز token هو أكبر عامل منفرد يؤثر في القبول: فالرمز الذي يُنشأ خلف عنوان IP مختلف هو السبب الأكثر شيوعًا لرفض رمز يبدو صالحًا.

ينطبق action وminScore على reCAPTCHA القائمة على النقاط. أرسل الإجراء الذي تبلّغ عنه الصفحة نفسها، وإلا فستُخفَّض النقاط عند التحقق. وعندما يتضمن الحل userAgent، فأعد استخدامه كما هو تمامًا عند الإرسال.

الأخطاء

تحمل الأخطاء رمزًا ثابتًا code قابلًا للقراءة آليًا ورسالة مفهومة للبشر، إما على شكل { "error": { "code", "message" } } أو في مهمة بالحالة status: "failed". أي طلب لم ينتج حلًا قابلًا للاستخدام لا تُحتسب له رسوم.

invalid_api_key (401) — المفتاح مفقود أو ملغى أو خاطئ.
insufficient_balance (402) — الرصيد لا يكفي لعملية حل واحدة. اشحن رصيدك.
unsupported_type (400 / 422) — نوع غير معروف، أو url مفقود، أو حقل مطلوب مفقود.
invalid_sitekey (422) — رُفض sitekey لتلك الصفحة.
proxy_required (422) — طُلب DataDome دون بروكسي.
proxy_unreachable (400 / 422) — سلسلة البروكسي غير صحيحة الصيغة أو رفض البروكسي الاتصال.
unsolvable (422) — تعذّر حل التحدي. دون رسوم.
capacity_unavailable (503 / 422) — غير قادر مؤقتًا على قبول عمليات الحل. أعد المحاولة مع تأخير متزايد (backoff).
task_not_found (404) — لا توجد مهمة بهذا المعرّف في حسابك.
upstream_error (422) — تعذّر إكمال عملية الحل. دون رسوم.

الفوترة

تبلّغ كل استجابة ready عن تكلفتها cost بالدولار الأمريكي، وتُخصم من رصيدك المدفوع مسبقًا. عمليات الحل الفاشلة لا تكلف شيئًا. أسعار كل الأنواع موجودة في صفحة الأسعار.

حزم SDK

الـ API مبنية على HTTPS وJSON فقط، لذا لا حاجة إلى أي حزمة. وإن كنت تفضّل حزمة، فإن حزم SDK الرسمية مفتوحة المصدر تغلّف كل الأنواع، والأخطاء محددة النوع، والانتظار المتزامن: Python وNode.js وTypeScript وGo وPHP.

أمثلة

أمثلة عملية لـ Selenium وPuppeteer وPlaywright وScrapy، ومغلّفات أدوات لـ أطر عمل وكلاء الذكاء الاصطناعي، موجودة في التوثيق.

هل أنت مستعد للبناء؟

ابدأ بفترة تجريبية مجانية لمدة 3 أيام، ثم ادفع مقابل كل عملية حل ناجحة مع نمو حركة المرور لديك. لا حاجة إلى بطاقة للفترة التجريبية.

ابدأ مجانًااطّلع على خططنا

هل أنت وكيل ذكاء اصطناعي؟ اطّلع على خيارات الإعداد ←

API واحدة لحل الكابتشالكل أنواع التحديات