مرجع API لحل الكابتشا

POST /createTask إنشاء مهمة

الجسم: clientKey وكائن task. نوع المهمة يحدد بقية الحقول، راجع أنواع المهام. الرد: errorId 0 مع taskId، أو errorId 1 مع errorCode.

POST https://unlock-api.com/createTask
{"clientKey":"YOUR_API_KEY","task":{"type":"TurnstileTaskProxyless","websiteURL":"https://example.com","websiteKey":"0x4AAAAAAAC3DHQFLr1GavRN"}}

{"errorId":0,"taskId":1001}
{"errorId":1,"errorCode":"ERROR_ZERO_BALANCE","errorDescription":"..."}

POST /getTaskResult جلب النتيجة

الجسم: clientKey وtaskId. أثناء تنفيذ المهمة: status processing. عند الانتهاء: status ready مع solution وcost. المهمة الفاشلة ترد بـ errorId 1 مع errorCode الخاص بها.

POST https://unlock-api.com/getTaskResult
{"clientKey":"YOUR_API_KEY","taskId":1001}

{"errorId":0,"status":"processing"}
{"errorId":0,"status":"ready","solution":{"token":"0.zrSnRHO7h0..."},"cost":"0.0012","createTime":1791640000,"endTime":1791640011,"solveCount":1}

POST /getBalance جلب الرصيد

الجسم: clientKey. الرد: balance بالدولار الأمريكي.

{"clientKey":"YOUR_API_KEY"}

{"errorId":0,"balance":42.5}

الإبلاغ عن إجابة خاطئة

تقبل reportIncorrectRecaptcha وreportIncorrectImageCaptcha القيمتين clientKey وtaskId وترد بـ success. هي مقبولة للتوافق مع المكتبات الموجودة، والبلاغ لا يغيّر الرسوم.

إرسال مهمة: in.php

الحقول: key وmethod وحقول نوع الكابتشا. الرد: OK|ID، أو مع json=1 {"status":1,"request":"ID"}. تعود الأخطاء بأسمائها، مثل ERROR_ZERO_BALANCE.

POST https://unlock-api.com/in.php
key=YOUR_API_KEY&method=hcaptcha&sitekey=SITE_KEY&pageurl=https://example.com&json=1

OK|1001
{"status":1,"request":"1001"}

جلب الإجابة: res.php

يعيد action=get&id=ID القيمة OK|ANSWER عند الحل وCAPCHA_NOT_READY أثناء العمل. يضيف action=get2 التكلفة. يتحقق ids=ID1,ID2 من حتى 100 مهمة دفعة واحدة. يعيد action=getbalance الرصيد. الطريقتان action=reportbad وreportgood مقبولتان.

GET https://unlock-api.com/res.php?key=YOUR_API_KEY&action=get&id=1001
CAPCHA_NOT_READY
OK|P1_eyJ0eXAiOiJKV1Qi...

GET https://unlock-api.com/res.php?key=YOUR_API_KEY&action=getbalance
42.5

POST /getToken الإنشاء والانتظار: getToken

الجسم نفسه كما في createTask. ينتظر الاستدعاء حتى 50 ثانية ويعيد الرد نفسه كما في getTaskResult. إذا كانت المهمة ما زالت قيد التنفيذ، يكون الرد status processing مع taskId، فتابع التحقق عبر getTaskResult.

POST https://unlock-api.com/getToken
{"clientKey":"YOUR_API_KEY","task":{"type":"TurnstileTaskProxyless","websiteURL":"https://example.com","websiteKey":"0x4AAAA..."}}

{"errorId":0,"taskId":1001,"status":"ready","solution":{"token":"0.zrSnRHO7h0..."},"cost":"0.000725"}

إشعارات النتيجة (callback)

أضف callbackUrl إلى createTask (أو pingback إلى in.php) وستُرسل النتيجة إليه عند انتهاء المهمة: جسم JSON مثل getTaskResult مع taskId، أو في in.php جسم نموذج id=…&code=…. تُستدعى العناوين العامة فقط، مرة واحدة، بمهلة 5 ثوانٍ، وتبقى النتيجة متاحة أيضًا عبر التحقق الدوري.

{"clientKey":"YOUR_API_KEY","callbackUrl":"https://your.server/captcha-result","task":{...}}

POST https://your.server/captcha-result
{"errorId":0,"taskId":1001,"status":"ready","solution":{...},"cost":"0.0005"}

الإحصاءات

يعيد getQueueStats عدد المهام المنتظرة وقيد الحل الآن ومتوسط وقت الحل في الساعة الأخيرة. يعيد getSpendingStats حجم مهامك وإنفاقك لكل ساعة خلال يوم UTC واحد (date بتوقيت unix). يعيد test الجسم الذي يستلمه كما هو.

POST https://unlock-api.com/getQueueStats     {"clientKey":"..."}  ->  {"errorId":0,"waiting":3,"solving":12,"speed":6.4,"total":15}
POST https://unlock-api.com/getSpendingStats  {"clientKey":"...","date":1791590400}  ->  {"errorId":0,"data":[{"dateFrom":...,"volume":120,"money":0.06},...]}
POST https://unlock-api.com/test              {"anything":1}  ->  {"errorId":0,"received":{"anything":1}}

قائمة عناوين IP المسموحة

إذا حددت قائمة عناوين IP مسموحة في صفحة الحساب، تحصل الطلبات من عناوين أخرى على الخطأ ERROR_IP_NOT_ALLOWED.