Retool + CaptchaAI: التعامل مع نموذج CAPTCHA للأداة الداخلية

لا يوجد في Retool مكوّن جاهز لحل اختبار CAPTCHA، ولا حاجة إليه: موردٌ واحد من نوع REST API واستعلام JavaScript واحد يكفيان لتحويل الأداة الداخلية إلى تطبيق يرسل الاختبار إلى CaptchaAI، ينتظر النتيجة، ثم يمرّر الرمز إلى الطلب النهائي.

الترتيب عمليًا: مورد يشير إلى https://ocr.captchaai.com، استعلام submitCaptcha على /in.php، استعلام pollResult على /res.php، واستعلام JavaScript ينسّق بينهما.

ما تحتاجه قبل الخطوة الأولى

• مفتاح الـ API من لوحة تحكم CaptchaAI — إن كانت تجربتك الأولى فابدأ من دليل البدء السريع.
• صلاحية إنشاء الموارد في مساحة عمل Retool؛ المورد يُنشأ على مستوى المؤسسة لا داخل التطبيق.
• مفتاح الموقع وعنوان URL للصفحة المستهدفة.
• خطة تتناسب مع عدد المستخدمين المتزامنين: الحساب يقوم على الـ Threads لا على عدد عمليات الحل، وتبدأ خطة BASIC من $15 شهريًا مع 5 threads وعمليات حل غير محدودة لكل thread.

سيناريو من السوق: بوابة مورّد تطلب reCAPTCHA v2

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

1. يدخل مفتاح الموقع وعنوان الصفحة إلى حقلي الإدخال.
2. يرسل التطبيق المهمة إلى CaptchaAI ويحتفظ بمعرّفها.
3. يستطلع النتيجة دوريًا حتى تجهز.
4. يعرض الرمز المحلول جاهزًا لإرسال النموذج.

هكذا يصبح زمن الدورة محكومًا بسقف حل reCAPTCHA v2 — أقل من 60 ثانية.

شغّل هذا المسار على البوابات التي تملك صلاحية الوصول إليها وحساباً نظامياً عليها فقط.

الخطوة 1: أضف CaptchaAI كمورد REST API

من Retool افتح Resources ← Create New ← REST API واضبط:

• الاسم — CaptchaAI
• عنوان URL الأساسي — https://ocr.captchaai.com
• المصادقة — لا شيء؛ مفتاح الـ API يُرسل كمعامل استعلام

احفظ المورد؛ ستشير إليه الاستعلامات اللاحقة.

الخطوة 2: استعلام الإرسال submitCaptcha

أنشئ استعلامًا باسم submitCaptcha فوق المورد CaptchaAI، نوع الإجراء GET، ومسار URL هو /in.php. معاملات الاستعلام:

• key — {{secretsStore.CAPTCHAAI_API_KEY}}
• method — userrecaptcha
• googlekey — {{sitekeyInput.value}}
• pageurl — {{pageurlInput.value}}
• json — 1

احفظ مفتاح الـ API في Secrets Store داخل Retool — الإعدادات ← Secrets — لا داخل تعريف الاستعلام. شرح المعاملات نفسها في دليل حل reCAPTCHA v2 عبر الـ API.

محوّل اختياري ينظّف الاستجابة قبل استخدامها:

// Parse the response
const data = {{ submitCaptcha.data }};
if (data.status === 1) {
  return { taskId: data.request, status: 'submitted' };
}
return { error: data.request, status: 'failed' };

الخطوة 3: استعلام استطلاع النتيجة pollResult

أنشئ استعلامًا ثانيًا باسم pollResult فوق المورد نفسه، نوع الإجراء GET، ومسار URL /res.php، بالمعاملات:

• key — {{secretsStore.CAPTCHAAI_API_KEY}}
• action — get
• id — {{submitCaptcha.data.request}}
• json — 1

المحوّل هنا ليس اختياريًا: هو ما يفرّق بين «لم تجهز بعد» وبين خطأ يستحق إيقاف الحلقة.

const data = {{ pollResult.data }};
if (data.status === 1) {
  return { token: data.request, status: 'solved' };
}
if (data.request === 'CAPCHA_NOT_READY') {
  return { status: 'pending' };
}
return { error: data.request, status: 'error' };

الخطوة 4: حلقة الاستطلاع في استعلام JavaScript

أنشئ استعلام JavaScript باسم solveCaptcha ينسّق الدورة كاملة: يرسل المهمة، ينتظر 15 ثانية قبل أول استفسار، ثم يستطلع كل 5 ثوانٍ حتى 20 محاولة. التوقيت مقصود؛ الاستفسار الفوري يستهلك محاولات بلا فائدة، والسقف الناتج يبقى داخل مهلة استعلامات JavaScript في Retool البالغة 120 ثانية.

// solveCaptcha — JavaScript Query
async function solve() {
  // Submit the CAPTCHA task
  await submitCaptcha.trigger();
  const submitResult = submitCaptcha.data;

  if (submitResult.status !== 1) {
    return { error: submitResult.request, status: 'submit_failed' };
  }

  const taskId = submitResult.request;

  // Wait 15 seconds before first poll
  await new Promise(r => setTimeout(r, 15000));

  // Poll up to 20 times (100 seconds max)
  for (let i = 0; i < 20; i++) {
    await pollResult.trigger({
      additionalScope: { taskId: taskId }
    });

    const result = pollResult.data;

    if (result.status === 1) {
      return { token: result.request, status: 'solved' };
    }

    if (result.request !== 'CAPCHA_NOT_READY') {
      return { error: result.request, status: 'error' };
    }

    // Wait 5 seconds before next poll
    await new Promise(r => setTimeout(r, 5000));
  }

  return { error: 'Polling timeout', status: 'timeout' };
}

return solve();

الخطوة 5: واجهة المستخدم داخل التطبيق

• Text Input باسم sitekeyInput وعنوانه «مفتاح موقع reCAPTCHA».
• Text Input باسم pageurlInput وعنوانه «عنوان الصفحة المستهدفة».
• Button باسم solveButton وعنوانه «حلّ الاختبار»، ينفّذ solveCaptcha.trigger() عند النقر.
• مكوّن Text بالقيمة {{ solveCaptcha.isFetching ? "Solving..." : "" }}.
• Loading Indicator يظهر مع {{ solveCaptcha.isFetching }}.
• Text Area باسم tokenOutput قيمته {{ solveCaptcha.data?.token || '' }} للقراءة فقط، بجانبه زر نسخ ينقل الرمز إلى الحافظة.
• شارة حالة تقرأ {{ solveCaptcha.data?.status }} فتظهر النجاح أو الخطأ.

الخطوة 6: مرّر الرمز إلى الطلب النهائي

الرمز بلا قيمة ما لم يصل إلى الطلب الذي ينتظره الموقع المستهدف. أنشئ استعلامًا باسم submitForm فوق مورد الجهة المستهدفة، نوع الإجراء POST، وضع في جسم الطلب بيانات النموذج مع الحقل g-recaptcha-response: {{solveCaptcha.data.token}}.

اربط الاستعلام بزر «إرسال النموذج» ولا تفعّله إلا حين تتحقق {{ solveCaptcha.data?.status === 'solved' }}، فلا يُرسل نموذج بحقل رمز فارغ.

الأخطاء الشائعة ومعالجتها

أسئلة شائعة

كم تستغرق دورة الحل داخل تطبيق Retool؟

سقف حل reCAPTCHA v2 أقل من 60 ثانية، وتكفي معه دورة من 20 محاولة بفاصل 5 ثوانٍ بعد انتظار أولي مدته 15 ثانية — أي داخل مهلة الـ 120 ثانية في Retool.

لماذا ترفض الجهة المستهدفة رمزًا حُلّ بنجاح؟

الرمز مرتبط بمفتاح الموقع وعنوان الصفحة المرسلين مع المهمة؛ أي اختلاف بينهما وبين النموذج الفعلي — أو استخدام الرمز بعد فوات صلاحيته — يجعل الموقع يرفضه.

ماذا يحدث إذا شغّل عدة موظفين الأداة في الوقت نفسه؟

كل عملية حل جارية تشغل thread واحدًا، وعدد الـ Threads في خطتك هو سقف التوازي. خمسة موظفين يضغطون الزر معًا يحتاجون خمسة threads متاحة، وإلا انتظرت الطلبات دورها.

هل يصلح المسار نفسه لأنواع CAPTCHA أخرى؟

نعم، مع تغيير قيمة method والمعاملات المرافقة لها؛ بنية الإرسال ثم الاستطلاع لا تتغير. راجع دليل Cloudflare Turnstile أو دليل GeeTest v3.

أدلة ذات صلة

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