مرجع API Endpoints

مرجع لجميع API endpoints الخاصة بـ FourA مع request parameters وتنسيقات الـ response.

الـ URL الأساسي

https://eu.api.foura.ai/api

المصادقة

يتطلب كل request مفتاح API الخاص بك في header X-API-Key:

curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method": "GET", "url": "https://example.com"}'

أنشئ وأدر مفاتيح API في لوحة التحكم. تستخدم المفاتيح البادئة pk_live_.

ترويسات الـ response

كل response من /api/* يحمل اثنين من الـ headers الخاصة بالارتباط:

الـ header	القيمة	الوصف
`X-FourA-Request-Id`	UUID	معرف فريد (ID) مخصص للـ request. يتم إرجاعه في كل response، بما في ذلك 4xx و 5xx. قم بتسجيله في السجلات الخاصة بك.
`X-FourA-Credits`	integer	الأرصدة المستهلكة في هذا الـ request. يتم إرجاعها عند النجاح وعند الفشل (تم إنجاز العمل في كلتا الحالتين). راجع نتائج الـ request لمعرفة النتائج التي يتم احتساب رسوم عليها.

يربط نفس الـ ID الخاص بالـ request المعاينة الخاصة ببيانات الـ request والـ response في سجل النشاط الخاص بلوحة التحكم (يتم الاحتفاظ به لمدة 24 ساعة، آخر 200 لكل مفتاح)، بحيث يمكنك البحث عن الـ request الدقيق لاحقا وإعادة تشغيله من النشاط مباشرة في Playground. قم بتضمينه عند الاتصال بالدعم الفني، وسيحدد الـ request في ثوان.

$ curl -i -X POST https://eu.api.foura.ai/api/single/ \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"method": "GET", "url": "https://example.com"}'

HTTP/2 200
content-type: application/json
x-foura-request-id: 8f3e2a14-7b6c-4d1a-9e2f-5a3b8c1d4e7f
x-foura-credits: 2
...

راجع Response Headers للحصول على القائمة الكاملة ونصائح الاستخدام.

Endpoints

هل تستخدم هذه الـ endpoints عبر MCP؟ يغلف الخادم @fouradata/mcp server جميع الـ endpoints الأربعة كأدوات MCP أصلية (foura_auto، foura_single، foura_proxy، foura_browser) بنفس أشكال الإدخال بالإضافة إلى خيار offload_large للتعامل مع الـ response الكبيرة بطريقة مناسبة للـ token.

يوفر FourA أربعة endpoints للـ request، كل منها مُحسّن لسيناريو مختلف:

Endpoint	الأفضل لـ
`POST /auto/`	الجلب الذكي (Smart fetch). تمرر URL، ويختار FourA المسار الأرخص الذي يعمل (مباشر، أو proxy متناوب، أو متصفح) ويتذكر ما يعمل لكل مضيف.
`POST /single/`	طلبات HTTP السريعة، الصفحات الثابتة، والـ APIs
`POST /proxy/`	المواقع المحمية مع تناوب proxy تلقائي، وتحديد نطاق البلد المرئي للهدف اختياريا
`POST /browser/`	الصفحات المعروضة بواسطة JavaScript، وتطبيقات الصفحة الواحدة (SPAs)
`GET /profiles`	دليل ملفات تعريف المتصفح لـ `single` و `proxy`. عام، بدون مفتاح API.

للحصول على شرح أعمق حول متى تختار كل منها، راجع Choosing the Right Endpoint و Smart Fetch guide.

قيود الـ URL الهدف

يتم رفض الأهداف التي تُحل إلى نطاقات IP خاصة أو loopback أو محجوزة (RFC 5735، RFC 6598، الكتل المحجوزة في IPv6) برمز 400 قبل أن يغادر الـ request منصة FourA. يتم توجيه أسماء المضيفين و IPs العامة فقط.

{ "error": "Target <ip> resolves to a private/reserved IP" }

الجلب الذكي (Auto)

POST /api/auto/

أنت تمرر عنوان URL وقواعد validate اختيارية. يتنقل FourA عبر سلم مدرك للتكلفة (فحص مباشر رخيص، proxy متناوب، متصفح كامل) ويتوقف عند الدرجة الأولى التي تُرجع response تقبله قواعدك. في الاستدعاءات المتكررة للمضيف نفسه، يتم إعادة تشغيل جلسة جاهزة بدلاً من ذلك، لذا تكون الضربة الثانية رخيصة.

أنت لا تضبط عمليات إعادة المحاولة، أو أحجام التجمعات، أو أعداد proxy. يتعلمها FourA لكل مضيف.

جسم الطلب (Request Body)

المعلمة	النوع	مطلوب	الافتراضي	الوصف
`url`	string	نعم	-	عنوان URL المستهدف
`method`	string	لا	`"GET"`	طريقة HTTP
`headers`	[string, string][]	لا	-	headers مخصصة كأزواج [name, value]
`data`	any	لا	-	جسم الطلب للطلبات غير GET
`validate`	object	لا	-	معايير النجاح، بنفس شكل `validate` الخاص بالطلب الفردي (انظر أدناه). أخبر auto بما تبدو عليه الصفحة الحقيقية حتى يتمكن من تمييز المحتوى من صفحة التحدي.
`returnSession`	boolean	لا	`true`	تضمين الجلسة الفائزة (`proxy`، `cookies`، `userAgent`) في response حتى تتمكن من إعادة تشغيلها عبر `/api/single/` أو `/api/browser/`.
`forceProxy`	boolean	لا	`true`	التوجيه دائماً عبر proxy متناوب. قم بتعيين `false` للسماح بالمسار المباشر الأرخص عندما يسمح الهدف بذلك (بعض الدفاعات تكون أكثر صرامة مع حركة مرور proxy).
`timeout_ms`	integer	لا	`120000`	إجمالي ميزانية الوقت للاستدعاء بأكمله، بالمللي ثانية. تعمل جميع المحاولات الفرعية داخل هذه الميزانية. الحد الأدنى `5000`، الحد الأقصى `180000`.
`ignoreProxies`	string[]	لا	-	معرفات Proxy التي يجب تجنبها في كل محاولة فرعية. استخدم المعرفات المرجعة بواسطة responses `/api/auto/` أو `/api/proxy/` السابقة.
`followRedirects`	integer	لا	`5`	الحد الأقصى لإعادات التوجيه التي يجب اتباعها على درجات السلم الرخيصة. `0` للتعطيل. الحد الأقصى `20`.

الاستجابة (Response)

{
  "status": 200,
  "data": "<!doctype html>...",
  "headers": [{"content-type": "text/html"}],
  "meta": {
    "rung": "cache",
    "solved": false,
    "attempts": 1,
    "credits": 2
  },
  "session": {
    "proxy": "A1B2C3",
    "cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
    "userAgent": "Mozilla/5.0..."
  }
}

الحقل	النوع	الوصف
`status`	number	حالة HTTP من الهدف.
`data`	string أو object	جسم الاستجابة.
`headers`	array أو object	ترويسات الاستجابة الهدف. ترجع مسارات single و proxy مصفوفة من كائنات الترويسة لكل قفزة؛ بينما ترجع مسارات browser كائنا مسطحا.
`meta.rung`	string	أي درجة من السلم قدمت الاستجابة. أحد القيم التالية: `probe` (طلب مباشر رخيص)، `proxy` (بروكسي متناوب)، `browser` (تصيير كامل للمتصفح)، `cache` (إعادة تشغيل جلسة دافئة)، أو `fail` (لم تنتج أي درجة استجابة مقبولة).
`meta.solved`	boolean	ما إذا تم حل تحدي الروبوت خلال هذا الاستدعاء.
`meta.attempts`	number	المحاولات الفرعية التي تم إجراؤها قبل النجاح.
`meta.credits`	number	إجمالي الأرصدة المستهلكة في هذا الاستدعاء. يطابق `X-FourA-Credits`.
`session.proxy`	string	المعرف المشفر للبروكسي الذي قدم الاستجابة. أعد استخدامه في طلب Single أو Browser. يكون موجودا عندما يكون `returnSession` هو `true`.
`session.cookies`	array	ملفات تعريف الارتباط (cookies) من المحاولة الناجحة. تكون موجودة عندما يكون `returnSession` هو `true`.
`session.userAgent`	string	User-Agent المستخدم في المحاولة الناجحة. يكون موجودا عندما يكون `returnSession` هو `true`.
`error`	string	رسالة الخطأ في حال فشل الاستدعاء.

مثال

curl -X POST https://eu.api.foura.ai/api/auto/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}}
  }'

ملاحظات

Auto هو منسق. يستدعي Single أو Proxy أو Browser داخليا ويمرر مفتاح API الخاص بك إلى كل استدعاء فرعي. يظهر كل استدعاء فرعي في سجل النشاط الخاص بك؛ لا يضيف الاستدعاء الخارجي /api/auto/ صفا منفصلا قابلا للفوترة.
قم بتمرير validate.data.accept مع سلسلة فرعية تحتوي عليها الصفحة الحقيقية فقط. بدونها، لا يمكن لـ auto التمييز بين استجابة 200 الحقيقية وصفحة تحدي بينية يتم إرجاعها بالحالة 200.
timeout_ms يضع حدا للاستدعاء بأكمله. قد يستغرق الاتصال الأول البارد بموقع محمي عشرات الثواني، وعادة ما تنتهي الجلسات الدافئة المعاد استخدامها في أقل من ثانية.

Single Request

POST /api/single/

يرسل طلب HTTP بخصائص شبكة واقعية تشبه المتصفح، دون تشغيل متصفح حقيقي. هذا هو أسرع endpoint.

Request Body

المعلمة	النوع	مطلوب	الافتراضي	الوصف
`method`	سلسلة	نعم	-	طريقة HTTP: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
`url`	سلسلة	نعم	-	عنوان URL الهدف. استخدم `{ts}` في أي مكان في عنوان URL لإدراج الطابع الزمني الحالي لكسر ذاكرة التخزين المؤقت.
`headers`	[سلسلة, سلسلة][]	لا	-	ترويسات مخصصة كأزواج [اسم, قيمة]
`unblocker`	منطقي	لا	`true`	أرسل ترويسات متصفح واقعية (User-Agent, Sec-Ch-Ua, Sec-Fetch-*, Accept-Encoding). قيد التشغيل افتراضيًا. عيّن `false` لإرسال توقيع عميل عادي.
`timeout_ms`	رقم	لا	15000	المهلة الإجمالية بالمللي ثانية (الحد الأقصى: 120000)
`connect_timeout_ms`	رقم	لا	5000	مهلة الاتصال بالمللي ثانية
`accept_timeout_ms`	رقم	لا	5000	مهلة القبول بالمللي ثانية (وقت الانتظار لقبول الاتصال)
`server_response_timeout_ms`	رقم	لا	15000	مهلة استجابة الخادم بالمللي ثانية (وقت الانتظار لأول بايت)
`dns_cache_timeout_sec`	رقم	لا	120	مدة بقاء (TTL) لذاكرة التخزين المؤقت لنظام أسماء النطاقات (DNS) بالثواني (الحد الأقصى: 240)
`followRedirects`	رقم	لا	معطل	الحد الأقصى لعمليات إعادة التوجيه التي يجب اتباعها (0-20). اتركه لتعطيل.
`tryJsonData`	منطقي	لا	false	تحليل جسم الاستجابة كـ JSON إذا كان ذلك ممكنًا
`returnBuffer`	منطقي	لا	false	إرجاع مخزن مؤقت خام بدلاً من سلسلة تم فك تشفيرها
`data`	أي	لا	-	جسم الطلب (سلسلة أو كائن, متسلسل تلقائيًا إلى JSON)
`proxy`	سلسلة	لا	-	معرف الوكيل (proxy) من استجابة سابقة, لتثبيت نفس المخرج. مرر السلسلة المبهمة كما هي. يُرفض عنوان الوكيل الخام بـ `400 Invalid proxy format`.
`browser`	سلسلة	لا	Chrome	المتصفح المطلوب تقديمه: Chrome أو Edge أو Safari أو Firefox أو Tor. انظر ملفات تعريف المتصفح.
`os`	سلسلة	لا	-	نظام التشغيل المطلوب تقديمه: Windows أو macOS أو Android أو iOS. يقبل اسم العائلة أيًا من إصداراته.
`version`	سلسلة	لا	الأحدث	إصدار المتصفح المطلوب تقديمه, كما هو مدرج في الكتالوج. يفوز أحدث تطابق عندما يتناسب عدة خيارات.
`profile`	سلسلة	لا	-	معرف الملف الشخصي الدقيق من `GET /api/profiles`, بدلاً من الحقول الثلاثة أعلاه.
`validate`	كائن	لا	-	قواعد التحقق من الاستجابة (انظر أدناه)

ملفات تعريف المتصفح

يقدم الطلب افتراضيًا أحدث إصدار من متصفح Google Chrome. تقبل بعض الأهداف متصفحًا واحدًا وترفض آخر, لذا تضيق browser و os و version كتالوجًا للملفات الشخصية المقاسة, وتختار profile واحدًا بالمعرف.

{
  "method": "GET",
  "url": "https://example.com",
  "browser": "Firefox",
  "os": "Windows"
}

القواعد:

يتطلب التحديد unblocker (مفعل افتراضيا). عند إيقاف تشغيل أداة إلغاء الحظر، لا يتم إرسال ترويسات المتصفح، لذا يتم رفض الطلب بدلا من تطبيقه جزئيا.
عندما تتطابق عدة ملفات تعريف، يفوز الإصدار الأحدث.
المجموعة التي لا يمكن للكتالوج تقديمها تُرجع خطأ يحدد ما هو متاح. لا يتم إرسال الطلب أبدا كمتصفح مختلف.
تتوفر الحقول الأربعة نفسها داخل كائن request الخاص بـ POST /proxy/.

يُرجع GET /api/profiles الكتالوج الكامل ولا يحتاج إلى مفتاح API:

{
  "profiles": [
    { "id": "...", "browser": "Chrome", "version": "...", "os": "...", "osFamily": "macOS" }
  ],
  "default": "..."
}

osFamily هو القيمة التي يجب التصفية بناءً عليها عند بناء منتقي؛ يحتفظ os باسم الإصدار للعرض.

قواعد التحقق

يتيح لك الكائن validate تحديد شروط النجاح والفشل. إذا تطابق شرط fail، يتم التعامل مع الطلب على أنه فاشل. إذا تم تعيين شروط accept، يتم اعتبار الاستجابات المطابقة فقط ناجحة.

{
  "validate": {
    "status": { "accept": [200, 201], "fail": [403, 503] },
    "headers": { "accept": {"content-type": "application/json"} },
    "data": { "accept": ["product"], "fail": ["captcha", "blocked"] }
  }
}

الحقل	النوع	الوصف
`validate.status.accept`	number[]	رموز حالة HTTP للقبول
`validate.status.fail`	number[]	رموز حالة HTTP للرفض
`validate.headers.accept`	object	أزواج مفتاح-قيمة في header التي يجب أن تكون موجودة
`validate.headers.fail`	object	أزواج مفتاح-قيمة في header التي تؤدي إلى الفشل
`validate.data.accept`	string[]	السلاسل النصية التي يجب أن تظهر في response body
`validate.data.fail`	string[]	السلاسل النصية في response body التي تؤدي إلى الفشل

مثال

curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://example.com/products",
    "timeout_ms": 10000
  }'

Response:

{
  "status": 200,
  "headers": [{"result": {"version": "HTTP/2", "code": 200, "reason": ""}, "content-type": "text/html", "server": "nginx", "set-cookie": ["session=abc", "tracker=xyz"]}],
  "data": "<!doctype html>...",
  "total_time": 0.342,
  "proxy": "A1B2C3"
}

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

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

الحقل	النوع	الوصف
`status`	number	رمز حالة HTTP من الهدف
`headers`	array	كائن واحد لكل قفزة إعادة توجيه. يحتوي كل منها على حقل `result` مع سطر الحالة بالإضافة إلى كل response header. تعود الـ headers متعددة القيم (`Set-Cookie`، `Link`، `WWW-Authenticate`) كمصفوفات من السلاسل النصية.
`data`	string/object	جسم الـ response (JSON إذا كان `tryJsonData` true)
`total_time`	number	إجمالي وقت الـ request بالثواني
`proxy`	string	المعرف المشفر للـ proxy الذي مر من خلاله الـ request (فقط عند توفير `proxy` في الـ request). أعد استخدامه في استدعاء لاحق لتثبيت نفس المخرج.
`defense`	object	متواجد فقط عندما قام الهدف بتشغيل فحص روبوت على هذا الـ request. يوضح `defense.solved` ما إذا كان الفحص قد تم اجتيازه. راجع دفاعات مكافحة الروبوتات لكل حقل والقائمة الكاملة للمزودين.
`error`	string	رسالة الخطأ إذا فشل الـ request

Proxy Request

POST /api/proxy/

يوجه الـ request الخاص بك عبر proxies متناوبة مع إعادة محاولة تلقائية عند الفشل. يمكنك اختياريًا تحديد نطاق الاختيار لمجموعة من بلدان الخروج المرئية للهدف.

جسم الـ Request

المعلمة	النوع	مطلوب	الافتراضي	الوصف
`request`	object	نعم	-	جسم request واحد (نفس الحقول كما في Single Request أعلاه)
`timeout_ms`	number	لا	45000	المهلة الإجمالية لجميع المحاولات بالمللي ثانية (الحد الأقصى: 120000)
`maxTries`	number	لا	5	الحد الأقصى لمحاولات تناوب الـ proxy (الحد الأقصى: 90)
`ignoreProxies`	string[]	لا	-	معرفات الـ proxies المراد استبعادها من التناوب (استخدم المعرفات التي تم إرجاعها بواسطة الـ responses السابقة)
`exitCountries`	string[]	لا	-	قائمة السماح الصارمة المكونة من رموز البلدان المكونة من حرفين المرئية للهدف (مثل `["CZ", "GB"]`). يتم تقليم القيم وتحويلها إلى أحرف كبيرة وإزالة التكرارات. يتم استبعاد الـ proxies ذات المخارج غير المعروفة ولا يتراجع الـ request أبدًا إلى بلد غير مطلوب.

تحديد نطاق exitCountries

يستخدم الاختيار أحدث البيانات الوصفية لبلد مرئي للهدف المتاحة، وعادة ما يتم تحديثها في غضون حوالي عشر دقائق. ليس بحثًا مباشرًا عن الموقع الجغرافي أثناء الـ request. لا تستنتج بلد التقديم من عنوان مضيف الـ proxy.

إذا لم يكن لدى المجمع الحالي تطابق للبلدان المطلوبة، فإن الـ response يعيد HTTP 200 بغلاف خطأ:

{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}

احتفظ بالنطاق المطلوب وأعد المحاولة لاحقا. قم بتغييره أو توسيعه فقط عندما تتغير متطلبات البلد الخاصة بسير عملك بشكل صريح.

مثال

curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 3,
    "exitCountries": ["CZ", "GB"],
    "request": {
      "method": "GET",
      "url": "https://example.com/prices"
    }
  }'

الاستجابة:

{
  "status": 200,
  "headers": [{"result": {"code": 200}, "content-type": "text/html", "set-cookie": ["a=1", "b=2"]}],
  "data": "<!doctype html>...",
  "total_time": 1.204,
  "proxy": "A1B2C3",
  "exitCountry": "CZ",
  "total": 2.341
}

الحقل	النوع	الوصف
`proxy`	string	معرف مشفر للـ proxy المستخدم. أعد استخدامه في طلب Single أو Browser بتمريره كحقل `proxy`، أو تخطاه في طلب الـ Proxy التالي عبر `ignoreProxies`.
`exitCountry`	string	رمز البلد المكون من حرفين والمرئي للهدف والخاص بالـ proxy الذي قدم الطلب. يتواجد فقط عندما يحدد الطلب `exitCountries`. تحقق دائمًا من أنه أحد الرموز التي طلبتها قبل الوثوق في الاستجابة.
`total`	number	مدة وقت الجدار الخارجي بالثواني (float). يتضمن ذلك اختيار الـ proxy والمحاولات المتكررة والمحاولة الناجحة. `total_time` هو الطلب الداخلي فقط; `total` دائمًا >= `total_time`.
`error`	string	رسالة خطأ إذا فشل الطلب. عند عدم وجود نطاق (scope miss)، يكون `code` هو `no_eligible_proxy` و`details.exitCountries` يعكس النطاق الموحد (normalized scope).

جميع حقول استجابة طلب Single مدرجة أيضًا، ومن بينها defense: محاولة proxy واجهت فحص روبوت ستبلغ عنه بنفس الطريقة التي يفعلها طلب Single.

طلب Browser (Browser Request)

POST /api/browser/

يفتح الرابط (URL) الخاص بك في نسخة متصفح Chrome. يتم تحميل الصفحة، وتُنفذ ملفات JavaScript، وتحصل على كود HTML المصير بالكامل (fully rendered HTML) بالإضافة إلى وعاء الـ cookie (cookie jar).

جسم الطلب (Request Body)

المعلمة	النوع	مطلوب	الافتراضي	الوصف
`url`	string	نعم	-	رابط (URL) الهدف
`headers`	object	لا	-	ترويسات (headers) مخصصة كأزواج من المفاتيح والقيم (key-value pairs)
`cookies`	array	لا	-	ملفات تعريف الارتباط (Cookies) التي يجب تعيينها: `[{name, value, domain?}]`
`userAgent`	string	لا	-	سلسلة User-Agent مخصصة
`unblocker`	boolean	لا	`true`	حل تحديات الروبوتات الشائعة تلقائيًا (مثل Cloudflare clearance وغيرها) أثناء تحميل الصفحة. مفعل افتراضيًا. قم بتعيينه إلى `false` لتصيير ما تعيده الصفحة، بما في ذلك صفحة التحدي، دون حلها.
`proxy`	string	لا	-	معرف הـ Proxy (Proxy ID) من استجابة سابقة، لتثبيت نفس مسار الخروج (exit). قم بتمرير السلسلة غير الشفافة (opaque string) كما هي. سيتم رفض أي عنوان proxy خام مع الخطأ `400 Invalid proxy format`.
`timeout_ms`	number	لا	30000	مهلة تحميل الصفحة بالمللي ثانية (الحد الأقصى: 120000)
`checkStatus`	number	لا	-	حالة HTTP المتوقعة (يفشل الطلب إذا كانت مختلفة)
`checkText`	string	لا	-	نص يجب أن يظهر في الصفحة المصيرة

مثال

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/spa-app",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'

الاستجابة:

{
  "status": 200,
  "headers": {"content-type": "text/html"},
  "body": "<!doctype html>...",
  "cookies": [{"name": "session", "value": "abc123", "domain": "example.com", "path": "/", "expires": 1735689600, "httpOnly": true, "secure": true, "sameSite": "Lax"}],
  "userAgent": "Mozilla/5.0...",
  "defenseSolved": true,
  "defenses": {"present": ["cloudflare"], "cleared": ["cloudflare"]},
  "proxy": "A1B2C3"
}

الحقل	النوع	الوصف
`status`	number	كود حالة HTTP من الهدف
`headers`	object	Response headers
`body`	string أو object	محتوى الصفحة معروضاً بالكامل. يكون سلسلة نصية (String HTML) عندما يكون نوع المحتوى (content-type) هو HTML؛ وكائن (object) عندما ترجع الصفحة JSON ويتم تحليلها تلقائياً.
`cookies`	array	كائنات ملفات تعريف الارتباط (cookies) كاملة من الصفحة. يتضمن كل ملف تعريف ارتباط `name` و `value` و `domain` و `path` و `expires` و `httpOnly` و `secure` و `sameSite` وخصائص أخرى.
`userAgent`	string	الـ User-Agent المستخدم في المتصفح
`defenseSolved`	boolean	`true` إذا تم مواجهة حماية ضد الروبوتات وتم تخطيها فعلياً في هذا الاستدعاء. يكون غير موجود بخلاف ذلك. يحدد تكلفة 15 مقابل 30 رصيداً.
`defenses`	object	`present` يدرج كل مزود تم التعرف عليه أثناء تحميل الصفحة، و `cleared` يدرج المزودين الذين تحتفظ الصفحة النهائية بتخطي حمايتهم. يمكن أن يظهر مزود في `present` ولا يظهر أبداً في `cleared`. راجع Anti-Bot Defenses.
`proxy`	string	المعرف المشفر للـ proxy الذي مر الطلب من خلاله (فقط عندما يتم توفير `proxy` في الطلب). أعد استخدامه في الاستدعاءات اللاحقة للحفاظ على نفس المخرج.
`error`	string	رسالة الخطأ في حال فشل الطلب

أكواد حالة HTTP

الكود	المعنى
200	اكتمل الطلب (تحقق من `status` الداخلي لمعرفة استجابة الهدف)
400	نص الطلب، أو المعلمات غير صالحة، أو IP الهدف في نطاق خاص/محجوز
401	مفتاح API مفقود أو غير صالح
429	تم تجاوز الـ Rate limit
500	خطأ داخلي في الخادم
502	`Upstream unavailable`. وصل FourA إلى محركه لكن الرد كان غير قابل للاستخدام. أعد المحاولة.
503	الخدمة معطلة مؤقتاً أو بكامل طاقتها، أو `Backend service unavailable` أثناء إعادة تشغيل المحرك
504	`Upstream timeout`. لم ينهِ المحرك عمله ضمن الميزانية الزمنية المحددة لهذا الطلب. ارفع `timeout_ms` أو أعد المحاولة.

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

Smart Fetch (Auto): متى تدع FourA يختار المسار لك
Choosing the Right Endpoint: متى تختار Single أو Proxy أو Browser يدوياً
Authentication: إدارة مفاتيح API الخاصة بك
Error Handling: التعامل مع الأخطاء بسلاسة
Anti-Bot Defenses: اقرأ حقل defense وأعد تطبيق التخطي
Rate Limits: فهم حدود الطلبات
Quick Start: طلبك الأول في 30 ثانية

آخر تحديث: 12 أغسطس 2026