فحوصات الموقع

عندما يُجري الهدف فحص bot في طريقك إلى الصفحة المطلوبة، تُعلمك FourA بذلك. كل request يواجه فحصًا يعود مع حقل يحدد اسم النظام، وما إذا تم تجاوز الفحص، و(عند التجاوز) بيانات الـ clearance التي يمكنك إعادة استخدامها لتخطي الفحص في الاستدعاء التالي.

هذه الصفحة هي المرجع لتلك الحقول. لمعرفة الاستراتيجية، راجع المواقع المحمية.

مكان وجود الحقل

Endpoint	الحقل	متى يظهر
`POST /api/single/`	`defense` (object)	عند التعرف على فحص bot في الـ response
`POST /api/proxy/`	`defense` (object)	الأمر نفسه، مسجلاً بواسطة المحاولة التي استجابت
`POST /api/browser/`	`defenseSolved` (boolean) و `defenses` (object)	دائمًا، في أي صفحة تم تحميلها. يكون `defenseSolved` بقيمة `false` ويكون `defenses` فارغًا عند عدم التعرف على أي شيء.
`POST /api/auto/`	`meta.solved` (boolean)	في كل إجابة بمجرد بدء الـ ladder. تكون القيمة `true` عند تجاوز فحص في مرحلة ما من الـ ladder. يتم الرد على الـ body الذي يفشل في التحقق أو المضيف الذي يتعذر حله قبل بدء الـ ladder، بدون `meta`.

الغياب يعني أنه لم يتم التعرف على أي شيء. لا تعتبر غياب defense دليلاً على الفشل.

في Single و Proxy، يتطلب إعداد التقارير تفعيل unblocker، وهو مفعل افتراضيًا. عند استخدام unblocker: false فأنت تطلب الصفحة تمامًا كما وردت، لذا يرجع Single التحدي دون تعديل ويعرضه Browser دون حله.

`defense` في Single و Proxy

{
  "status": 200,
  "data": "<!doctype html>...",
  "total_time": 3.61,
  "defense": {
    "vendor": "sgcaptcha",
    "solved": true,
    "present": ["sgcaptcha"],
    "ms": 3412,
    "hashes": 1048576,
    "complexity": 20,
    "cookie": "_I_=<clearance>"
  }
}

الحقل	النوع	الوصف
`vendor`	string	النظام الذي يتعلق به هذا السجل: النظام الذي تم تجاوزه، أو النظام الرئيسي الذي تمت مواجهته. راجع قائمة المزودين أدناه.
`solved`	boolean	القيمة `true` تعني أنه تم تجاوز الفحص وأن `data` هي الصفحة الحقيقية. القيمة `false` تعني أن `data` قد تكون صفحة التحدي.
`present`	string[]	كل نظام تم التعرف عليه في هذا الـ response. يمكن أن يحتوي على أسماء أكثر من `vendor`، ويمكن أن يتضمن أسماء لا يتجاوزها أحد بعد.
`ms`	number	عدد الأجزاء من الثانية المستغرقة لتجاوز الفحص. يظهر فقط عند التجاوز الناجح.
`hashes`	number	حجم العمل الحسابي الذي طلبه التحدي. يظهر فقط عند التجاوز الناجح.
`complexity`	number	مستوى الصعوبة الذي أعلنه التحدي. يظهر فقط عند التجاوز الناجح، وفقط عندما يبلغ التحدي عن ذلك.
`answers`	number	عدد الإجابات المقبولة التي تم تقديمها، للتحديات التي تتطلب إجابات متعددة بدلا من إجابة واحدة. يظهر فقط عند التجاوز الناجح.
`retry`	string	يتوفر عندما تأتي الـ body من إعادة محاولة بدلا من تجاوز مباشر. القيمة الوحيدة المتاحة اليوم هي `refusal-cookies`. انظر أدناه.
`cookie`	string	ملف الـ jar المراد إعادة تشغيله: التصريح الذي تم الحصول عليه عبر التجاوز، أو الجلسة التي تم تسليمها عند الرفض.

تعد solved: false الحالة التي تستدعي التفريع الشرطي. لا تقدم FourA أبدا صفحة التحدي كمحتوى، لذا فإن هذا الـ flag هو إشارتك إلى أن الـ body تحتاج إلى تصعيد بدلا من التحليل.

`retry: "refusal-cookies"`

بعض المواقع لا تشغل لغزا. بل ترفض الـ request الأول، وتعين cookies مع الرفض، ثم تقدم الصفحة الحقيقية لأي طرف يعيد إرسال هذه الـ cookies. صفحات عناصر eBay هي الحالة المرجعية لذلك.

عندما يحدث ذلك، تقوم FourA بإعادة إرسالها نيابة عنك وتسليمك الصفحة. يحتوي الـ response بعد ذلك على retry: "refusal-cookies":

{
  "status": 200,
  "data": "<!doctype html>...",
  "defense": {
    "vendor": "akamai",
    "solved": false,
    "present": ["akamai"],
    "retry": "refusal-cookies",
    "cookie": "bm_sv=...; dp1=..."
  }
}

اقرأها على هذا النحو:

solved يظل false. الرد على المصافحة ليس تجاوزا لاختبار التحدي (challenge)، ولا يغير أبدا تكلفة الاستدعاء. تتم محاسبتك على الـ request الذي أجريته.
data هو محتوى حقيقي، وليس صفحة challenge. هذه هي الحالة الوحيدة التي لا يعني فيها solved: false أن الـ body يحتاج إلى تصعيد، ولهذا السبب يوجد هذا الحقل.
cookie هو الـ session الذي قدمه الموقع. أعد إرساله بنفس الطريقة التي تعيد بها إرسال الـ clearance وستتخطى الصفحات اللاحقة حالة الرفض.
يمكن أن تحدث كل من إعادة المحاولة (retry) والتجاوز (clear) في request واحد. إذا تبين أن إجابة الـ retry عبارة عن challenge يمكن لـ FourA تجاوزه، فستتلقى solved: true مع حقول المزود الخاصة و retry: "refusal-cookies" بجانبها.

تكون قيمة vendor هي unknown عندما تنتج الـ retry المحتوى دون التعرف على أي نظام في المسار. حينها يكون present مصفوفة فارغة.

`defenses` على Browser

{
  "status": 200,
  "body": "<!doctype html>...",
  "userAgent": "Mozilla/5.0...",
  "defenseSolved": true,
  "defenses": {
    "present": ["cloudflare"],
    "cleared": ["cloudflare"]
  }
}

الحقل	النوع	الوصف
`defenseSolved`	boolean	تكون القيمة `true` عند مصادفة نظام أثناء التحميل والاحتفاظ بإذن تجاوزه (clearance) في الصفحة النهائية. هذه هي العلامة التي تحدد ما إذا كان الاستدعاء يكلف 5 أو 10 أرصدة.
`defenses.present`	string[]	كل نظام تم التعرف عليه في أي مرحلة أثناء تحميل الصفحة، وليس فقط في الاستجابة النهائية. الفحص هو إجراء قد حدث بالفعل، وبحلول وقت وصول الصفحة الحقيقية تكون استجابة التحدي قد انتهت منذ فترة.
`defenses.cleared`	string[]	الأنظمة التي تحتفظ الصفحة النهائية بإذن تجاوزها (clearance).

أي اسم يظهر في present ولا يصل أبدا إلى cleared يشير إلى نظام يمكن لـ FourA التعرف عليه ولكن لا يمكنه إكماله بعد. هذه الحالات لا ترفع تكلفة الاستدعاء أبدا.

المزودون (Vendors)

قيمة `vendor`	النظام
`cloudflare`	تحديات Cloudflare وإدارة البوتات
`sgcaptcha`	فحص الموقع الخاص بـ SiteGround
`datadome`	DataDome
`perimeterx`	PerimeterX
`akamai`	Akamai Bot Manager
`incapsula`	Imperva Incapsula
`awswaf`	تحدي AWS WAF
`ebay-splashui`	التحدي الخاص بـ eBay
`reddit`	صفحات الفحص والرفض الخاصة بـ Reddit
`amazon`	فحص الروبوت الخاص بـ Amazon
`google`	فحص JavaScript الخاص بـ Google Search
`hcaptcha`	hCaptcha
`recaptcha`	reCAPTCHA
`unknown`	لم يتم التعرف على أي نظام. لا تظهر إلا بجانب `retry`، حيث يوجد السجل للإبلاغ عن إعادة المحاولة بدلا من مزود معين.

ما يتم تجاوزه حاليا

Endpoint	التجاوزات (Clears)
Single, Proxy	`sgcaptcha`، `ebay-splashui`. كلاهما حسابي وليس مرئيا، لذا لا يتطلب الأمر استخدام متصفح.
Browser	`cloudflare`، `sgcaptcha`

كل ما عدا ذلك في القائمة يتم التعرف عليه والإبلاغ عنه فقط دون اتخاذ إجراء إضافي. يتغير هذا التوزيع مع تطوير FourA لإمكانية تجاوز المزيد منها، لذا اقرأ solved بدلا من الاعتماد على هذا الجدول.

ملاحظتان على الحالات الخاصة:

hcaptcha و recaptcha هما أيضا أدوات نماذج عادية (form widgets). يتم الإبلاغ عنهما فقط عندما تحظرك الاستجابة بالفعل (403، 429، أو 503)، وبالتالي فإن صفحة الدفع التي تحتوي على أداة تحقق داخل نموذج لا تسجل وجود نظام حماية.
وجود الموقع خلف Cloudflare لا يعد بحد ذاته نظام حماية. يظهر cloudflare عند وجود تحد حقيقي أو عنصر لإدارة البوتات في الاستجابة، وليس لمجرد استخدام الموقع لـ Cloudflare.

إعادة استخدام إذن التجاوز (Replaying a Clearance)

defense.cookie هو الغرض الأساسي من هذا الحقل. يرتبط إذن التجاوز (clearance) بنقطة الخروج التي حصلت عليه وقيمة User-Agent نفسها، لذا أعد إرساله عبر نفس الزوج ولن يتم تشغيل الفحص مرة أخرى.

import requests

API = "https://eu.api.foura.ai"
H = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

# 1) First call pays for the clear.
first = requests.post(f"{API}/api/proxy/", headers=H, json={
    "maxTries": 5,
    "request": {"method": "GET", "url": "https://example.com/catalog"},
}).json()

defense = first.get("defense", {})
if defense.get("solved"):
    clearance = defense["cookie"]
    exit_id = first["proxy"]

    # 2) Follow-up pages skip the check: same exit, same clearance.
    for page in range(2, 6):
        r = requests.post(f"{API}/api/single/", headers=H, json={
            "method": "GET",
            "url": f"https://example.com/catalog?page={page}",
            "proxy": exit_id,
            "headers": [["Cookie", clearance]],
        }).json()
        print(page, r["status"])

يحمل الاستدعاء الأول تكلفة التجاوز. وتُعد كل إعادة تشغيل بمثابة request عادي بالسعر العادي.

ثلاثة أمور تُبطل إعادة التشغيل:

مخرج مختلف. ثبّت proxy ID الذي أرجعه response التجاوز. راجع Reuse a Proxy Across Requests.
User-Agent مختلف. تُرجع responses المتصفح قيمة userAgent المُستخدمة. أعد إرسالها مع cookie.
انتهاء الصلاحية. تمتلك عمليات التجاوز فترات صلاحية خاصة بها يحددها الهدف. تستمر صلاحية SiteGround لنحو 30 يوما للموقع بأكمله، بينما تكون صلاحية Cloudflare أقصر عادة. تعامل مع التجاوز كأنه cache: عندما تبدأ عمليات إعادة التشغيل في إرجاع تحديات مجددا، نفّذ استدعاء جديدا واحدا واستخدم التجاوز الجديد.

التكلفة

يغيّر الفحص الذي تم تجاوزه السعر على Browser فقط:

Engine	Base	Cleared defense
Single	1 (2 with `unblocker`)	No change
Proxy	2 (4 with `unblocker`)	No change
Browser	5	10

يحتسب Browser تكلفة 10 فقط عندما يكون أداة الحل نشطة ويتم تجاوز النظام بنجاح. أما النظام الذي تم التعرف عليه ولم يتم تجاوزه فيكلف 5، وهو نفس سعر الصفحة التي لا تحتوي على أي فحص على الإطلاق.

صفحة الفحص التي يتعرف عليها FourA والمُقدمة برمز HTTP 200 (مثل فحص الروبوت في Amazon، أو صفحة التحقق في Reddit، أو فحص JavaScript في Google Search) لا تُحسب تكلفتها على أي endpoint، ويذكر الـ response اسمها في X-FourA-Check-Page.

الاستخدام مع `validate`

يوضح defense أنه تمت مواجهة فحص ما. بينما يوضح validate لـ FourA كيف تبدو الصفحة الحقيقية، وهو ما يسمح للـ request بالفشل بدلا من تسليمك صفحة بينية تحمل بالصدفة رمز HTTP 200.

{
  "method": "GET",
  "url": "https://example.com/product/42",
  "validate": {
    "data": {"accept": ["Add to cart"], "fail": ["Just a moment"]}
  }
}

في POST /api/auto/، يُعد validate هو ما يمنع مسار الترقية من قبول صفحة التحدي واحتسابها كمكتملة.

فحوصات الموقع

مكان وجود الحقل

defense في Single و Proxy

retry: "refusal-cookies"

defenses على Browser