كيفية حلّ reCAPTCHA v2 عبر الـ API بالكود العملي

حين يتوقّف سكربت الأتمتة عند مربّع «أنا لست روبوتاً»، لست مضطرّاً لمحاكاة النقرات ولا لتدريب نموذج رؤية حاسوبية. الحلّ عبر الـ API يختصر المسار كلّه إلى أربع خطوات واضحة: استخرج sitekey و pageurl من الصفحة، أرسلهما إلى حلّال reCAPTCHA v2 من CaptchaAI، استطلع النتيجة كل بضع ثوانٍ، ثم احقن التوكن الناتج في الحقل المحمي ليكمل النموذج مساره.

كُتب هذا الدليل للمطوّر الذي يريد تكاملاً يعمل الآن: أكواد جاهزة في Python وNode.js وPHP، وخطوات تنسخها وتشغّلها مباشرة دون نظريات زائدة.

غير متأكّد من إصدار reCAPTCHA الذي أمامك؟ ابدأ بـ كيف تحدّد إصدار reCAPTCHA قبل أن ترسل أول طلب، فمعاملات v2 تختلف عن v3 وEnterprise.

متى تحتاج إلى حلّ reCAPTCHA v2 عبر الـ API

ليس كل موقع يستدعي هذا المسار، لكن ثلاث حالات شائعة في السوق تجعله عملياً وموفّراً للوقت:

• اختبارات الجودة الليلية: فريق يشغّل اختبارات انحدار (regression) على صفحة تسجيل الدخول أو إتمام الشراء في متجر إلكتروني، ويحتاج إلى حلّ reCAPTCHA v2 آلياً حتى تكتمل الدورة كل ليلة دون تدخّل يدوي.
• مراقبة التوفّر: خدمة تتحقّق كل ساعة من أن بوّابة حجز أو نموذج تسجيل ما زالا يعملان، فتحتاج إلى حلّ التحدّي لتصل إلى الشاشة التالية وتقيس زمن الاستجابة.
• جمع بيانات معروضة للعموم بحجم كبير: سكربت يقرأ بيانات متاحة علناً خلف صفحة محمية بـ reCAPTCHA v2، فيوكل الحلّ إلى الـ API بدل التوقّف عند كل تحدٍّ.

النمط في هذه الحالات جميعاً واحد: أرسل بيانات التحدّي، استلم توكناً صالحاً، ثم أكمل الطلب كما يفعل مستخدم حقيقي.

ما تحتاجه قبل أن تبدأ

الخطوة 1: استخرج الـ sitekey و pageurl

الـ pageurl هو العنوان الكامل للصفحة التي يظهر فيها الويدجت، ويجب أن يبدأ بـ https://. أما الـ sitekey فهو مفتاح عام تسنده Google لكل نسخة ويدجت، وأمامك ثلاث طرق للعثور عليه.

الطريقة الأولى — من شيفرة الـ HTML: ابحث عن الحاوية واقرأ قيمة data-sitekey:

<div class="g-recaptcha" data-sitekey="6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"></div>

الطريقة الثانية — من رابط الـ iframe: افتح إطار reCAPTCHA وستجد رابطاً مثل https://www.google.com/recaptcha/api2/anchor?ar=1&k=6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-&...؛ قيمة البارامتر k= هي الـ sitekey.

الطريقة الثالثة — من حركة الشبكة: افتح DevTools ثم تبويب Network وفلتر بكلمة recaptcha، وسيظهر البارامتر k في أي طلب.

نصيحة: إذا حُمِّل الويدجت داخل iframe على نطاق فرعي مختلف، فاستخدم رابط ذلك الإطار قيمةً للـ pageurl بدل عنوان الصفحة الأم.

الخطوة 2: أرسل مهمة الحلّ

بعد أن جمعت القيمتين، أرسلهما بطلب POST إلى نقطة النهاية in.php مع تحديد method=userrecaptcha. تعيد الاستجابة معرّف المهمة الذي تستطلع به النتيجة لاحقاً:

import requests

API_KEY = "YOUR_API_KEY"
SITEKEY = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
PAGEURL = "https://example.com/login"

submit = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": API_KEY,
    "method": "userrecaptcha",
    "googlekey": SITEKEY,
    "pageurl": PAGEURL,
    "json": 1,
}).json()

assert submit["status"] == 1, submit
task_id = submit["request"]
print("task id:", task_id)

نسخة Node.js المكافئة تستخدم fetch المدمج دون أي مكتبة إضافية:

const r = await fetch("https://ocr.captchaai.com/in.php", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    key: API_KEY,
    method: "userrecaptcha",
    googlekey: SITEKEY,
    pageurl: PAGEURL,
    json: "1",
  }),
});
const { status, request: taskId } = await r.json();
if (status !== 1) throw new Error(taskId);

reCAPTCHA غير مرئية؟ أضف invisible=1 إلى بيانات الطلب. الآلية نفسها، لكن التفاصيل مشروحة في كيف تعمل reCAPTCHA غير المرئية.

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

الحلّ ليس فورياً؛ يستغرق reCAPTCHA v2 عادةً بين 15 و60 ثانية. لذلك انتظر نحو 20 ثانية قبل أول استعلام، ثم كرّر الاستطلاع كل 5 ثوانٍ حتى تصلك النتيجة، مع تجنّب الاستعلام المفرط الذي قد يصطدم بتحديد معدل الطلبات:

import time

time.sleep(20)
while True:
    res = requests.get("https://ocr.captchaai.com/res.php", params={
        "key": API_KEY,
        "action": "get",
        "id": task_id,
        "json": 1,
    }).json()

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

    if res.get("status") == 1:
        token = res["request"]
        print("token:", token[:60], "…")
        break

    raise RuntimeError(res)

التوكن المُعاد سلسلة طويلة تبدأ عادةً بـ 03AGdBq25...، وهو ما ستحقنه في الخطوة التالية.

الخطوة 4: احقن التوكن في النموذج

الحصول على التوكن ليس النهاية؛ عليه أن يصل إلى الصفحة بالطريقة التي تتوقّعها. أشيع مسار هو ملء حقل g-recaptcha-response المخفي ثم إرسال النموذج:

document.querySelector('textarea[name="g-recaptcha-response"]').value = token;
document.querySelector("form").submit();

الأسلوب نفسه في Selenium عبر تنفيذ JavaScript:

driver.execute_script(
    "document.querySelector('[name=\"g-recaptcha-response\"]').value = arguments[0];",
    token,
)
driver.find_element(By.CSS_SELECTOR, "form").submit()

وفي Playwright:

await page.evaluate((t) => {
  document.querySelector('[name="g-recaptcha-response"]').value = t;
}, token);
await page.click('button[type="submit"]');

إذا عرّف الويدجت دالة data-callback، فالحقن المباشر لا يكفي؛ نادِ تلك الدالة بالتوكن أيضاً حتى يعتمده الموقع:

const callback = document.querySelector(".g-recaptcha").dataset.callback;
if (callback && window[callback]) window[callback](token);

المثال الكامل لحلّ reCAPTCHA v2 في Python

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

import time
import requests

API_KEY = "YOUR_API_KEY"
SITEKEY = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
PAGEURL = "https://example.com/login"

def solve_recaptcha_v2():
    submit = requests.post("https://ocr.captchaai.com/in.php", data={
        "key": API_KEY, "method": "userrecaptcha",
        "googlekey": SITEKEY, "pageurl": PAGEURL, "json": 1,
    }).json()
    if submit["status"] != 1:
        raise RuntimeError(submit)
    task_id = submit["request"]

    time.sleep(20)
    for _ in range(40):
        res = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": API_KEY, "action": "get", "id": task_id, "json": 1,
        }).json()
        if res.get("request") == "CAPCHA_NOT_READY":
            time.sleep(5)
            continue
        if res.get("status") == 1:
            return res["request"]
        raise RuntimeError(res)
    raise TimeoutError("solve timed out")

if __name__ == "__main__":
    token = solve_recaptcha_v2()
    print("token:", token[:80])

أخطاء شائعة عند حلّ reCAPTCHA v2 وعلاجها

عندما يصل التوكن لكن الموقع يرفضه

هذه أكثر لحظة محيّرة في التكامل، وسببها في الغالب طريقة الحقن لا الـ API نفسه:

• التوكن جاهز والموقع يظل يحجب: للنموذج معالج خاص؛ ابحث عن دالة callback ونادِها بدل ملء الحقل مباشرة.
• يلزم ثبات البصمة: أرسل مع الطلب اللاحق نفس الكوكيز وUser-Agent اللذين كانا فعّالين لحظة طلب التوكن.
• الحلّ يعتمد على البروكسي: أضف proxy وproxytype ليمرّ الحلّ عبر مجموعة عناوين IP الخاصة بك حين يهمّ تطابق العنوان.

أسئلة شائعة

كم تكلفة حلّ reCAPTCHA v2 عبر CaptchaAI؟

يعتمد CaptchaAI على تسعير قائم على الـ threads لا على كل عملية حلّ: تدفع مقابل عدد الخيوط المتزامنة، وكل خطة تشمل حلولاً غير محدودة خلال الشهر. تبدأ خطة BASIC من 15 دولاراً شهرياً مع 5 threads، وترتفع الخطط بزيادة عدد الخيوط لمن يحتاج معالجة متوازية أكبر. لا توجد رسوم لكل كابتشا ولا سقوف يومية داخل الخطة.

هل ينفع النمط نفسه مع reCAPTCHA v3 وCloudflare Turnstile؟

نعم، وهذه أكبر ميزة عملية. المسار «أرسل إلى in.php ثم استطلع res.php» واحد عبر الأنواع المدعومة؛ يتغيّر method وبعض البارامترات فقط. تعلّمه مرة واحدة مع reCAPTCHA v2، ثم أعد استخدام الهيكل نفسه مع reCAPTCHA v3 وCloudflare Turnstile وCloudflare Challenge وGeeTest v3 والصور النصية.

ماذا أفعل إذا انتهت صلاحية التوكن قبل استخدامه؟

توكن reCAPTCHA v2 قصير العمر؛ تنتهي صلاحيته بعد دقيقتين تقريباً. استخدمه فور استلامه ولا تخزّنه لطلبات لاحقة. وإذا كان مسار عملك بطيئاً بين الحلّ والإرسال، فأعد ترتيبه بحيث يكون الحصول على التوكن آخر خطوة قبل إرسال النموذج مباشرة.

هل يناسب هذا المسار اختبارات الجودة والأتمتة المشروعة؟

نعم. حلّ reCAPTCHA v2 عبر الـ API أداة معتادة في اختبارات الجودة، ومراقبة التوفّر، وجمع البيانات المتاحة للعموم على أنظمة تملك صلاحية الوصول إليها. اجعل استخدامك ضمن نطاق مصرّح به ووفق شروط الخدمة المعمول بها في كل موقع تتعامل معه.

الخطوات التالية والمراجع

• البدء السريع مع CaptchaAI: حلّ أول كابتشا في خمس دقائق
• كيف تحدّد إصدار reCAPTCHA قبل الحلّ
• حلّ Cloudflare Turnstile عبر الـ API بالنمط نفسه
• أخطاء حلّ reCAPTCHA v2 الشائعة وإصلاحها