طلب رمز reCAPTCHA Enterprise باستخدام cURL

• تأكد من توفر cURL وjq في الصدفة لديك.
• عيّن SOLVETHREE_API_KEY إلى مفتاح API لمساحة عملك. شغّل هذه الأوامر على الخادم؛ ولا تضع المفتاح في كود المتصفح.
• عيّن SOLVETHREE_PROXY إلى عنوان URL للوكيل الذي تنوي استخدامه للحل وإرسال الرمز.
• أعدّ ملف تعريف موقع reCAPTCHA نشطًا في لوحة التحكم لمساحة عملك. استبدل accounts.example.com وlogin في المثال باسم المضيف والإجراء الخاصين بك.

إرسال اسم مضيف وإجراء لا ينشئ ملف تعريف موقع. يجب أن يكون ملف التعريف نشطًا بالفعل قبل أن تطلب حلًا.

# Set SOLVETHREE_API_KEY and SOLVETHREE_PROXY in your environment first.
# Replace the hostname and action with your active site profile.
jq -n \
  --arg proxy "$SOLVETHREE_PROXY" \
  --arg requestId "login-$(date +%s)-$$" \
  '{site:"accounts.example.com", action:"login", proxy:$proxy, requestId:$requestId}' \
| curl --fail-with-body --max-time 30 \
  'https://api.solvethree.com/v1/tasks?waitMs=15000' \
  -H "Authorization: Bearer $SOLVETHREE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @-

يقدّم متن JSON الحقول site وaction وproxy واحدًا. يلزم تحديد واحد فقط من proxy أو proxyCandidates. لا تضف type أو url؛ فإغفال recaptchaType يختار enterprise-v3.

يطلب معامل الاستعلام waitMs=15000 من طلب الإنشاء الانتظار حتى 15 ثانية. مكانه في عنوان URL، وليس في متن JSON. تبلغ مهلة cURL مدة 30 ثانية، ما يترك وقتًا إضافيًا لتأخير الشبكة بعد مدة الانتظار على الخادم. قد تظل المهمة في حالة غير نهائية عند وصول الاستجابة.

تحقّق من وجود خطأ HTTP قبل تفسير المتن على أنه استجابة مهمة. يستخدم كلا الأمرين --fail-with-body؛ تعامل مع طلب HTTP الفاشل بشكل منفصل عن مهمة حالتها failed.

تأتي استجابة المهمة الجاهزة بهذا الشكل. القيم أدناه عناصر نائبة، وليست رمزًا يمكنك إرساله.

{
  "id": "example-task",
  "status": "ready",
  "solution": {
    "token": "EXAMPLE_TOKEN",
    "userAgent": "EXAMPLE_USER_AGENT",
    "secChUa": "EXAMPLE_CLIENT_HINTS"
  }
}

إذا كانت الاستجابة غير نهائية، فعيّن TASK_ID في بيئتك إلى قيمة id المُعادة، ثم استرجع المهمة:

curl --fail-with-body --max-time 30 \
  "https://api.solvethree.com/v1/tasks/$TASK_ID?waitMs=15000" \
  -H "Authorization: Bearer $SOLVETHREE_API_KEY"

ينتظر طلب GET هذا حتى 15 ثانية للحصول على نتيجة، مع مهلة HTTP قدرها 30 ثانية. بدون waitMs، يعيد GET الاستجابة دون انتظار. كرّر GET فقط ما دامت الحالة pending أو solving، وضع مهلة نهائية إجمالية في الجهة المستدعية حتى لا تستمر حلقة الاستعلام الدوري إلى أجل غير مسمى.

إذا فشلت المهمة، فاستخدم تفاصيل الخطأ بدلًا من افتراض وجود مشكلة في الرصيد. على سبيل المثال، يستدعي site-unreachable التحقق من إمكانية الوصول إلى الجهة المستهدفة، وليس إعادة إرسال المدخلات نفسها دون تحقّق.

استخدم solution.token في طلب التطبيق المستهدف. يُستخدم id الخاص بالمهمة لاسترجاعها فقط؛ وليس رمز CAPTCHA. يعتمد موضع الرمز على نموذج الجهة المستهدفة أو واجهة API لديها، لذا لا يوجد أمر موحّد لإرسال الرمز إليها.

استخدم solution.userAgent وsolution.secChUa المُعادَين، إلى جانب الوكيل الذي نجح في الحل، عند إرسال الرمز. في مثال الوكيل الواحد أعلاه، استخدم SOLVETHREE_PROXY نفسه. لا تستخدم هوية متصفح أو عنوان URL مستهدفًا لا صلة لهما بالحل.

تعني ready أن solvethree أنشأ حلًا. تحقّق من استجابة التطبيق المستهدف بشكل منفصل لمعرفة ما إذا كان قد قبل طلبك.