البدء السريع مع CaptchaAI: حلّ أول كابتشا في 5 دقائق

تمرّ كل عملية حل في CaptchaAI بأربع خطوات ثابتة لا تتغيّر: تُرسل تفاصيل التحدّي إلى in.php، تحفظ معرّف المهمة، تستطلع res.php حتى تجهز النتيجة، ثم تحقن التوكن في الصفحة المستهدفة. الدورة نفسها تعمل مع reCAPTCHA وCloudflare Turnstile وGeeTest v3 وصور الـ OCR — لا يتغيّر بينها سوى بارامتر method. في هذا الدليل ستطبّق الدورة كاملةً على تحدّي Cloudflare Turnstile حقيقي، ومن مفتاح الـ API حتى أول توكن محلول لن تحتاج أكثر من خمس دقائق.

وهذه الخطوات الأربع باختصار:

1. الإرسال — ادفع بيانات الكابتشا إلى in.php عبر طلب POST.
2. حفظ المعرّف — التقط معرّف المهمة من حقل request في الاستجابة.
3. الاستطلاع — اسأل res.php كل 5 ثوانٍ حتى تعود النتيجة جاهزة.
4. استخدام التوكن — احقن التوكن المحلول في الصفحة أو الطلب المستهدف.

الخطوة 0: جهّز مفتاح الـ API

قبل أي طلب تحتاج مفتاح API صالحاً مرتبطاً بحساب فيه Threads فعّالة:

1. أنشئ حساباً على captchaai.com.
2. افتح لوحة التحكم.
3. انسخ مفتاح الـ API المكوّن من 32 حرفاً.

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

الخطوة 1: أرسل الكابتشا

المثال التالي يحل تحدّي Cloudflare Turnstile، وهو من أكثر الأنواع انتشاراً اليوم. تحتاج قيمتين تستخرجهما من الصفحة المستهدفة:

• sitekey — المفتاح العام لويدجت Turnstile؛ تجده في الخاصية data-sitekey أو ضمن بارامترات سكربت Turnstile، ويبدأ دائماً بـ 0x.
• pageurl — العنوان الكامل للصفحة التي يظهر فيها الويدجت.

اختر لغتك ونفّذ الطلب:

cURL

curl -X POST "https://ocr.captchaai.com/in.php" \
  -d "key=YOUR_API_KEY" \
  -d "method=turnstile" \
  -d "sitekey=0x4AAAAAAAC3DHQFLr1GavNl" \
  -d "pageurl=https://example.com/login" \
  -d "json=1"

Python

import requests

response = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": "YOUR_API_KEY",
    "method": "turnstile",
    "sitekey": "0x4AAAAAAAC3DHQFLr1GavNl",
    "pageurl": "https://example.com/login",
    "json": 1,
})
print(response.json())

Node.js

const response = await fetch("https://ocr.captchaai.com/in.php", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    key: "YOUR_API_KEY",
    method: "turnstile",
    sitekey: "0x4AAAAAAAC3DHQFLr1GavNl",
    pageurl: "https://example.com/login",
    json: "1",
  }),
});
console.log(await response.json());

PHP

<?php
$response = file_get_contents("https://ocr.captchaai.com/in.php?" . http_build_query([
    "key"       => "YOUR_API_KEY",
    "method"    => "turnstile",
    "sitekey"   => "0x4AAAAAAAC3DHQFLr1GavNl",
    "pageurl"   => "https://example.com/login",
    "json"      => 1,
]));
echo $response;

الخطوة 2: احفظ معرّف المهمة

عند نجاح الإرسال تعود استجابة مختصرة كهذه:

{
  "status": 1,
  "request": "71823469"
}

الحقل request هو معرّف مهمتك، وستستخدمه في الخطوة التالية لجلب النتيجة. أما إذا عادت status بقيمة 0 فقد وقع خطأ، ويحمل الحقل request رمزه. إليك أكثر الأخطاء حدوثاً عند أول طلب وطريقة معالجتها:

الخطوة 3: استفسر عن النتيجة

لا تستعجل الاستطلاع. انتظر 15 ثانية أولاً حتى يبدأ الحل، ثم اسأل عن النتيجة كل 5 ثوانٍ حتى تصل. الاستطلاع المبكر لا يعجّل النتيجة؛ كل ما يفعله أنه يعيد CAPCHA_NOT_READY ويستهلك محاولاتك.

Python

import time

time.sleep(15)

while True:
    result = requests.get("https://ocr.captchaai.com/res.php", params={
        "key": "YOUR_API_KEY",
        "action": "get",
        "id": "71823469",
        "json": 1,
    }).json()

    if result.get("request") == "CAPCHA_NOT_READY":
        time.sleep(5)
        continue

    if result.get("status") == 1:
        token = result["request"]
        print(f"Solved! Token: {token[:60]}...")
        break

    raise RuntimeError(result)

Node.js

await new Promise((r) => setTimeout(r, 15000));

while (true) {
  const r = await fetch(
    `https://ocr.captchaai.com/res.php?key=YOUR_API_KEY&action=get&id=71823469&json=1`,
  );
  const data = await r.json();
  if (data.request === "CAPCHA_NOT_READY") {
    await new Promise((r) => setTimeout(r, 5000));
    continue;
  }
  if (data.status === 1) {
    console.log("Solved:", data.request.slice(0, 60));
    break;
  }
  throw new Error(JSON.stringify(data));
}

ما إن تعود status بقيمة 1 حتى يصبح الحقل request هو التوكن المحلول الجاهز للاستخدام.

الخطوة 4: استخدم التوكن

يختلف مكان حقن التوكن باختلاف نوع الكابتشا:

• Turnstile / reCAPTCHA — اكتب القيمة في الحقل cf-turnstile-response أو g-recaptcha-response، أو نادِ دالة الـ callback الخاصة بالويدجت.
• صور الـ OCR — ضع النص المتعرَّف عليه مباشرةً في حقل الإجابة.
• GeeTest v3 — ركّب الحقول المتعدّدة التي تعيدها الخدمة وفق ما ينتظره الموقع.

وأبسط حقن داخل المتصفّح لتحدّي Turnstile:

document.querySelector('[name="cf-turnstile-response"]').value = token;
document.querySelector("form").submit();

سيناريو عملي: اختبار تدفّق تسجيل الدخول

لنضع الدورة في سياق واقعي. افترض أنك في فريق QA لمنصّة SaaS إقليمية تخدم عملاء في الرياض والقاهرة، وصفحة تسجيل الدخول لديها محمية بـ Cloudflare Turnstile، وتريد اختباراً آلياً يتحقق بعد كل عملية نشر من أن مسار الدخول ما زال يعمل. بدل أن يتوقّف الاختبار عند الويدجت، تُدرج الخطوات الأربع أعلاه داخل سكربت الأتمتة: يرسل السكربت الـ sitekey وعنوان الصفحة إلى CaptchaAI، ينتظر التوكن، يحقنه في الحقل cf-turnstile-response، ثم يكمل تسجيل الدخول ويؤكّد وصول المستخدم إلى لوحة التحكم. النتيجة اختبار موثوق يعمل ضمن خط الـ CI من دون تدخّل بشري، مع بقاء التحقق المطلوب في مكانه على الصفحة الحيّة.

أخطاء شائعة في أول طلب

معظم مشاكل اليوم الأول تتكرّر، وهذه أكثرها حدوثاً:

• مسافة زائدة عند نسخ المفتاح — احذف أي فراغ في بداية مفتاح الـ API أو نهايته.
• بروتوكول ناقص في pageurl — يجب أن يبدأ العنوان بـ https:// كاملاً.
• الاستطلاع قبل الأوان — أول استفسار يجب أن ينتظر نحو 15 ثانية؛ الاستفسار عند اللحظة صفر يعيد CAPCHA_NOT_READY في كل مرة ويهدر محاولاتك.
• sitekey لا يخصّ الصفحة — الـ sitekey مرتبط بنطاق محدّد؛ نسخه من موقع واستخدامه على آخر يعيد ERROR_CAPTCHA_UNSOLVABLE أو توكناً يرفضه الموقع بردّ HTTP 403.
• نسيان json=1 — بدونه تعود الاستجابة نصاً عادياً مثل OK|71823469، فيفشل تحليلها كـ JSON.
• إعادة استخدام توكن محلول — توكنات Turnstile وreCAPTCHA أحادية الاستخدام وتنتهي صلاحيتها خلال دقيقتين تقريباً؛ أرسل، استخدم، ثم تجاهل من دون تخزين.
• نفاد الـ Threads — راجع خطّتك ومرجع أكواد أخطاء الـ API عند ظهور أخطاء الرصيد أو الازدحام.

الأسئلة الشائعة

كم يستغرق حلّ Turnstile فعلياً؟

يُحلّ Cloudflare Turnstile عادةً في أقل من 10 ثوانٍ بمعدّل نجاح مرتفع على الأنواع المدعومة. أما انتظار 15 ثانية قبل أول استطلاع فهو مجرّد هامش أمان يمنع الاستفسارات الفارغة، وليس مؤشراً على بطء الحل.

هل أحتاج متصفّحاً أو بروكسي لإرسال المهمة؟

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

ماذا يعني CAPCHA_NOT_READY؟

ليست رسالة خطأ، بل تعني أن المهمة ما زالت قيد الحل. استمر في الاستطلاع كل 5 ثوانٍ حتى تعود status بقيمة 1، أو حتى يظهر رمز خطأ صريح يبدأ بـ ERROR_.

هل يمكنني إعادة استخدام التوكن المحلول؟

لا. التوكن أحادي الاستخدام وقصير الصلاحية (نحو دقيقتين في Turnstile وreCAPTCHA). احصل عليه، استخدمه فوراً في الطلب المستهدف، ثم اطلب توكناً جديداً للمحاولة التالية.

كيف أنتقل من Turnstile إلى نوع كابتشا آخر؟

غيّر قيمة البارامتر method وحقل التوكن المقابل في الصفحة، وتبقى دورة الإرسال والاستطلاع والاستخدام كما هي. تدعم الخدمة reCAPTCHA v2 وv3، وCloudflare Turnstile وChallenge، وGeeTest v3، وصور الـ OCR والشبكة، إضافةً إلى BLS.

الخطوات التالية

• حلّ reCAPTCHA v2 عبر الـ API خطوة بخطوة
• حل Cloudflare Turnstile برمجياً عبر الـ API
• حل GeeTest v3 باستخدام الـ API
• حل كابتشا الصور (OCR) عبر الـ API

أدلة ذات صلة

• بناء عميل CaptchaAI في Python مع تحقّق Pydantic
• تشغيل CaptchaAI في الإنتاج: إدارة التكوين