مرجع API Endpoints

مرجع لجميع endpoints الخاصة بـ FourA API مع معلمات request وتنسيقات 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 وأدرها في Dashboard. تستخدم المفاتيح البادئة pk_live_.

ترويسات Response

تحمل الـ responses الواردة من /api/* ترويستي ربط:

Header Value Description
X-FourA-Request-Id UUID معرف فريد مخصص للـ request. يتم إرجاعه مع كل response، بما في ذلك 4xx و5xx، باستثناء الـ body الذي لا يستطيع FourA قراءته إطلاقا: يتم رفض 400 Invalid JSON in request body و413 قبل تعيين معرف. سجله في سجلاتك.
X-FourA-Credits integer الرصيد المستهلك في هذا الـ request. يتم إرجاعه مع كل response وصل إلى محرك، سواء كان ناجحا أو فاشلا (تم تنفيذ العمل في الحالتين). أي استدعاء يرفضه FourA قبل تشغيله بواسطة أي محرك (مفتاح مفقود أو غير صالح، حد الخطة أو المنصة، هدف مرفوض أو معرف proxy مرفوض) لا يحمل أي رصيد. راجع Request Outcomes لمعرفة النتائج الخاضعة لاحتساب التكلفة.

يربط معرف الـ request نفسه معاينة حمولة الـ request والـ response في Activity Log في Dashboard (يتم الاحتفاظ بها لمدة 24 ساعة، لآخر 200 لكل مفتاح)، بحيث يمكنك البحث عن الـ request بدقة لاحقا وإعادة تشغيله من Activity مباشرة إلى 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)

هل تستخدم نقاط النهاية هذه عبر MCP؟ يوفّر خادم @fouradata/mcp نقاط النهاية الأربع كأدوات MCP أصلية (foura_auto و foura_single و foura_proxy و foura_browser) بنفس هياكل الإدخال، بالإضافة إلى خيار offload_large لمعالجة الاستجابات الكبيرة بكفاءة من حيث استهلاك الـ tokens. الفروقات: لا يحتوي foura_browser على حقل lean، كما أن foura_proxy لا يدعم حقول موقع الخروج (exit location) حتى الآن.

توفّر FourA أربع نقاط نهاية للطلبات، كل منها محسّن لسيناريو مختلف:

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

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

قيود عنوان URL المستهدف

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

{ "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts." }

يتم رفض أي هدف يقع على مضيف API التابع لـ FourA نفسه (eu.api.foura.ai أو api.foura.ai) برمز 400 أيضا، على جميع endpoints الأربعة، قبل جلب أي شيء أو احتساب أي تكلفة. كما يتم رفض أي URL يحتوي على مسافة أو حرف تحكم برمز 400 في كل من Single وProxy وAuto بالطريقة نفسها؛ قم بترميز المسافة كـ %20 (يجلب Browser الطلب بالطريقة التي يتبعها Chrome). الصفحة الوحيدة هناك التي يجلبها FourA هي /inspect.

{ "error": "Refusing to fetch <url>: that is the FourA API itself, not a page. A link taken from a page was probably resolved against the API URL; resolve it against the page's own URL." }

Smart Fetch (Auto)

POST /api/auto/

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

لا تحتاج إلى ضبط عمليات إعادة المحاولة أو أحجام المجموعات أو أعداد الـ proxy. يتعلم FourA هذه الإعدادات تلقائياً لكل مضيف.

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

المعامل النوع مطلوب القيمة الافتراضية الوصف
url string نعم - الـ URL المستهدف
method string لا "GET" طريقة HTTP
headers [string, string][] لا - ترويسات لإرسالها إلى الهدف، كأزواج [name, value]. يرسلها كل مستوى باستثناء مستوى المتصفح. أي Cookie ترسله يصل إلى الموقع دون تغيير، وتُضاف ملفات تعريف الارتباط الخاصة بالجلسة المخزنة بجانبه فقط تحت أسماء لم ترسلها أنت. يستبدل الـ userAgent الخاص بالجلسة المخزنة الـ User-Agent الخاص بك. يستبعد مستوى الـ proxy الترويسات الشرطية مثل If-None-Match ما لم يحدد validate.status.accept الخاص بك القيمة 304.
data any لا - جسم الطلب لطلبات غير GET
validate object لا - معايير النجاح، بنفس هيكل validate الخاص بـ Single Request (انظر أدناه). حدد للوضع التلقائي شكل الصفحة الحقيقية حتى يتمكن من التمييز بين المحتوى وصفحة التحدي (challenge page).
returnSession boolean لا true تضمين الجلسة الناجحة (proxy، cookies، userAgent) في الاستجابة لتتمكن من إعادة استخدامها عبر /api/single/ أو /api/browser/.
forceProxy boolean لا true التوجيه دائماً عبر proxy دوار. عيّن false للسماح بالمسار المباشر الأقل تكلفة عندما يسمح الهدف بذلك (بعض وسائل الحماية تكون أكثر صرامة على حركة مرور الـ proxy).
timeout_ms integer لا 120000 إجمالي الوقت المخصص للطلب بأكمله، بالمللي ثانية. تعمل جميع المحاولات الفرعية ضمن هذا الوقت. الحد الأدنى 5000، والحد الأقصى 180000.
ignoreProxies string[] لا - معرفات الـ proxy التي يجب تجنبها في كل محاولة فرعية. استخدم المعرفات التي أرجعتها استجابات /api/auto/ أو /api/proxy/ السابقة.
followRedirects integer لا 5 الحد الأقصى لإعادة التوجيه التي يجب تتبعها في المستويات منخفضة التكلفة. 0 للتعطيل. الحد الأقصى 20.
exitClass string لا - standard أو premium، كما في Proxy Request. يتيح premium تصعيد الطلب إلى مخرج مميز (premium exit) بمجرد عجز المجموعة القياسية عن الوصول إلى الصفحة. يتطلب خطة تتضمن مخارج مميزة. راجع exitClass on Smart Fetch.

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

{
  "status": 200,
  "data": "<!doctype html>...",
  "headers": [{"content-type": "text/html"}],
  "meta": {
    "rung": "cache",
    "solved": false,
    "attempts": 1,
    "credits": 2,
    "attemptsByEngine": {"single": 1, "proxy": 0, "browser": 0},
    "browserRequests": 0
  },
  "session": {
    "proxy": "A1B2C3",
    "cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
    "userAgent": "Mozilla/5.0..."
  }
}
الحقل النوع الوصف
status number حالة HTTP من الهدف.
data string نص جسم الاستجابة، أيا كان المستوى الذي قدمه. صفحة JSON تعود كنص JSON، لذلك تقوم بتحليلها بنفسك.
headers array or object ترويسات استجابة الهدف. تعيد مستويات Single و proxy مصفوفة من كائنات الترويسة لكل وثبة، بينما تعيد مستويات المتصفح كائنا مسطحا.
meta.rung string مستوى السلم الذي سلم الاستجابة. واحد من: probe (طلب مباشر منخفض التكلفة، فقط مع forceProxy: false)، أو proxy (بروكسي دوار)، أو browser (تصيير كامل عبر المتصفح)، أو cache (إعادة تشغيل جلسة نشطة)، أو warmup (تم جلب صفحة الدخول للموقع أولا وفتحت ملفات تعريف الارتباط الخاصة بها الرابط العميق)، أو fail (لم ينتج أي مستوى استجابة مقبولة).
meta.solved boolean ما إذا كانت الصفحة تتطلب خطوة إضافية (صفحة تحد) وتم إكمالها أثناء هذا الاستدعاء.
meta.attempts number المحاولات الفرعية التي تمت قبل النجاح.
meta.credits number إجمالي الرصيد المستهلك في هذا الاستدعاء. يطابق X-FourA-Credits.
meta.attemptsByEngine object الطلبات المرسلة إلى single وproxy وbrowser. يحتسب طلب المتصفح الذي رفضته خطتك، لأنه قد تم إرساله بالفعل.
meta.browserRequests number طلبات المتصفح التي شغلت حصة من مخصصاتك اليومية. طلب المتصفح الذي ترفضه خطتك لا يستهلك شيئا.
meta.exitClass string فئة الخروج التي سلمت الاستجابة، وتكون موجودة عندما يحدد الطلب exitClass: إما premium أو standard. تنتقل القيمة نفسها في ترويسة الاستجابة X-FourA-Exit-Class.
session.proxy string المعرف المشفر للبروكسي الذي سلم الاستجابة. أعد استخدامه في طلب Single أو Browser. يكون موجودا عندما تكون قيمة returnSession هي true.
session.cookies array ملفات تعريف الارتباط لإعادة تشغيلها، يحتوي كل منها كحد أدنى على name وvalue. يعيد مستوى المتصفح حاوية ملفات تعريف الارتباط الخاصة بالمتصفح. بينما يعيد مستوى البروكسي، أو الفحص المباشر، فقط ملفات تعريف الارتباط التي فتحت الصفحة (مثل تلك التي عينتها صفحة التحقق الخاصة بالموقع)، ولا يعيد أبدا كل ملف تعريف ارتباط عينته الصفحة، لذلك قد تكون القائمة فارغة. يكون موجودا عندما تكون قيمة returnSession هي true.
session.userAgent string ترويسة User-Agent المستخدمة في المحاولة الناجحة. تكون موجودة عندما تكون قيمة returnSession هي true.
error string رسالة الخطأ إذا فشل الاستدعاء.
attemptReport object عند فشل الاستدعاء: طلبات المحرك التي عادت دون الصفحة، مصنفة حسب السبب. راجع Smart Fetch.

مثال

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 الخاص بك إلى كل استدعاء فرعي. يُحسب استدعاء Auto كطلب واحد فقط في سجل النشاط (Activity Log) وفي نظرتك العامة، مع إجمالي أرصدة استدعاءاته الفرعية؛ وتُدرج الاستدعاءات الفرعية تحته كمحاولات تابعة له، ولا تُحسب أبدا كطلبات مستقلة بذاتها.
  • مرر validate.data.accept مع سلسلة فرعية لا تحتويها إلا الصفحة الحقيقية. من دونها، لا يمكن لـ Auto التمييز بين رمز 200 حقيقي وصفحة اختبار بينية معادة برمز الحالة 200.
  • الصفحة المحذوفة هي رد الموقع الفعلي وليست رفضا للطلب. عندما تُرجع نقطتا خروج نفس رمز 404 أو 410 ولا يقبله validate الخاص بك، ينتهي الاستدعاء بذاك status وبـ error يبدأ بـ the site answered. أدرج رمز الحالة في validate.status.accept وسيقوم Auto بتسليم أول استجابة تحمل هذا الرمز وتجتاز بقية شروط validate الخاصة بك. ينطبق الأمر نفسه على أي حالة أخرى تدرجها هناك، باستثناء 403 و429 و503 و202، والتي ترسلها المواقع أيضا مصحوبة بصفحة اختبار.
  • يحدد timeout_ms الحد الأقصى للمكالمة بأكملها. قد يستغرق أول وصول بارد إلى موقع محمي عشرات الثواني؛ في حين تنتهي الجلسات الدافئة المعاد استخدامها عادة في أقل من ثانية.

exitClass في Smart Fetch

يعمل exitClass في Smart Fetch تماما كما يعمل في طلب الوكيل (Proxy Request): فهو تصريح وليس أمرا ملزما. يحاول Auto استخدام التجمع القياسي أولا. عندما يتعذر على التجمع القياسي الوصول إلى الصفحة ويحدد الطلب premium، يفتح Auto الصفحة في متصفح عبر نقطة خروج premium. تخدم الجلسة التي ينشئها هناك استدعاءاتك اللاحقة لنفس الموقع والتي تحدد أيضا premium؛ أما الاستدعاءات التي لا تحدده فلن تستخدمها مطلقا.

نفاد الرصيد لا يُعد خطأ. بمجرد استهلاك حركة مرور premium المضمنة في خطتك لفترة الفوترة الحالية، يستمر الاستدعاء عبر التجمع القياسي ويوضح meta.exitClass القيمة standard. أما في الخطط التي لا تتضمن نقاط خروج premium، يُرفض الاستدعاء الذي يرسل exitClass: premium برمز 403 يحمل X-FourA-Limit: plan_limit_premium، وذلك قبل بدء أي عمل.

يتم قياس حركة مرور premium كما هو الحال في Proxy Request. نظرا لأن فتح الصفحة في متصفح يحمل بيانات أكثر من مجرد محتوى الصفحة نفسه، فإن صفحة Smart Fetch من فئة premium تستهلك حركة مرور premium أكبر مقارنة بنفس الصفحة عند جلبها عبر Proxy Request. للحد من هذا الاستهلاك، يتم تحميل صفحة Smart Fetch من فئة premium دون صور أو خطوط أو وسائط، ودون نصوص برمجية تابعة لمزودي الإعلانات والتحليلات وإدارة الموافقة المعروفين.


Single Request

POST /api/single/

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

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

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

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

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

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

القواعد:

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

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

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

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

قواعد التحقق

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

{
  "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 تنجح الاستجابة عندما يتطابق زوج واحد على الأقل في أي قفزة إعادة توجيه. تتطابق الأسماء والقيم دون حساسية لحالة الأحرف، وعلى جزء من النص.
validate.headers.fail object أزواج مفتاح-قيمة في header التي تؤدي إلى الفشل
validate.data.accept string[] تنجح الاستجابة عندما يحتوي 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": "...", "set-cookie": ["session=abc", "tracker=xyz"]}],
  "data": "<!doctype html>...",
  "total_time": 0.342
}

عندما يُجري الهدف فحص روبوت في الطريق إلى نص الاستجابة، تتضمن الاستجابة أيضًا كائن 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. تعود الترويسات متعددة القيم (Set-Cookie، Link، WWW-Authenticate) كمصفوفات من السلاسل النصية.
data string/object جسم الـ response (بتنسيق JSON إذا كانت قيمة tryJsonData هي true)
total_time number إجمالي وقت الـ request بالثواني
proxy string المعرف المشفر للـ proxy الذي مر من خلاله الـ request (فقط عند توفير proxy في الـ request). أعد استخدامه في استدعاء لاحق لتثبيت نفس نقطة الخروج.
defense object يتوفر عندما يجري الهدف فحص bot على هذا الـ request، أو عندما تؤدي إعادة المحاولة باستخدام ملفات cookie الخاصة بالموقع نفسه إلى جلب محتوى الجسم. يوضح defense.solved ما إذا كان الفحص قد تم تجاوزه، ويوضح defense.retry ما إذا كانت إعادة المحاولة قد جلبت المحتوى. راجع فحوصات الموقع للاطلاع على كل حقل والقائمة الكاملة للأنظمة.
error string رسالة الخطأ في حال فشل الـ request

Proxy Request

POST /api/proxy/

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

جسم الـ Request

المعامل النوع مطلوب القيمة الافتراضية الوصف
request object نعم - جسم request فردي (نفس حقول Single Request أعلاه)
timeout_ms number لا 45000 المهلة الإجمالية لجميع المحاولات بالمللي ثانية (الحد الأقصى: 120000)
maxTries number لا 5 يتوقف FourA عن بدء محاولات جديدة بمجرد فشل هذا العدد (الحد الأقصى: 90). تعمل المحاولات بالتوازي، لذلك قد يكتمل عدد إضافي قليل مقارنة بهذا الرقم.
ignoreProxies string[] لا - معرفات proxy لاستبعادها من التدوير (استخدم المعرفات التي تم إرجاعها بواسطة responses السابقة)
exitCountries string[] لا - قائمة سماح صارمة لرموز الدول المكونة من حرفين والمرئية للهدف (مثل ["CZ", "GB"]). يتم اقتطاع القيم وتحويلها إلى أحرف كبيرة وإزالة التكرار منها. يتم استبعاد نقاط الخروج من standard pool ذات الدولة غير المعروفة، ولا يعود standard pool أبدًا إلى دولة غير مطلوبة. كما تنطلق نقطة الخروج من فئة premium من إحدى الدول المدرجة أيضًا.
exitClass string لا - standard أو premium. يتيح premium ترقية request إلى نقطة خروج premium عندما يواجه standard pool صعوبة مع هدف محمي. يتطلب خطة تتضمن نقاط خروج premium.
exitState string لا - المنطقة التي تنطلق منها نقطة الخروج. تتطلب exitClass: premium ودولة واحدة فقط في exitCountries. راجع Exit location.
exitCity string لا - المدينة التي تنطلق منها نقطة الخروج. تتطلب exitClass: premium ودولة واحدة فقط في exitCountries.
exitAsn string لا - الشبكة التي تنطلق منها نقطة الخروج، عبر رقم AS، على سبيل المثال 8866. تتطلب exitClass: premium ودولة واحدة فقط في exitCountries.
exitOs string لا - windows أو android أو ios أو mac: نوع الجهاز الذي ينتمي إليه العنوان. تتطلب exitClass: premium.
exitLifetimeMin integer لا - الدقائق التي تحتفظ فيها نقطة الخروج بعنوانها، من 3 إلى 1440. تتطلب exitClass: premium.

نطاق exitCountries

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

إذا لم يتضمن pool الحالي أي تطابق للدول المطلوبة، ولم يحدد request القيمة exitClass: premium، يُرجع 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"
    }
  }'

Response:

{
  "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، أيا كانت فئة المخرج التي خدمته. تحقق دائما من أنه أحد الرموز التي طلبتها قبل الوثوق بالـ response.
exitClass string فئة المخرج التي خدمت هذا الطلب، وتكون موجودة في الـ response الناجح عندما يحدد الطلب فئة منها. تعني premium أن مخرجا مميزا أرجع الـ body؛ بينما تعني standard أن التجمع القياسي هو من قام بذلك. الاستدعاء الفاشل لم يخدم أي شيء، لذا فهو لا يحمل exitClass؛ اقرأ حقل attemptReport لمعرفة ما واجهته المحاولات.
total number المدة الزمنية الإجمالية بالثواني (float). تشمل اختيار الـ proxy، وإعادة المحاولات، والمحاولة الناجحة. يمثل total_time مدة الطلب الداخلي فقط؛ وتكون قيمة total دائما >= total_time.
profile string ملف تعريف المتصفح الذي اختاره التدوير، ويكون موجودا فقط إذا لم يكن هو الملف الذي طلبته. غيابه يعني أن الطلب تم إرساله تماما كما هو مكتوب. مرر المعرف مجددا كـ profile في الاستدعاءات اللاحقة للاحتفاظ بالمتصفح الذي نجح.
error string رسالة الخطأ في حال فشل الطلب. عند عدم تطابق النطاق، تكون قيمة code هي no_eligible_proxy ويعرض details.exitCountries النطاق بعد تسويته.
attemptReport object موجود في كل استدعاء Proxy فاشل. يحسب ما واجهته المحاولات، حتى لا يظهر تجمع محظور، وتجمع غير متاح، وقاعدة validate لم تتطابق أبدا، بالخطأ نفسه. انظر أدناه.
request object موجود في استدعاء Proxy الفاشل: الطلب الذي نفذته FourA، مع تعبئة القيم الافتراضية وإدراج ignoreProxies الخاصة بك تماما كما أرسلتها.

يتم تضمين جميع حقول response الخاصة بـ Single Request أيضا، بما في ذلك defense: حيث إن محاولة proxy التي تصادف فحص bot تبلغ عنها بالطريقة نفسها التي يتبعها Single.

أسباب فشل استدعاء Proxy

تتم قراءة Download maxTry limit reached بالطريقة نفسها أيا كانت نتيجة المحاولات، لذا يحمل كل response فاشل لـ Proxy كائن attemptReport بجانب الخطأ:

{
  "error": "Download maxTry limit reached",
  "attemptReport": {
    "total": 25,
    "noResponse": 0,
    "defense": 0,
    "contentRejected": 25,
    "statusRejected": 0,
    "other": 0,
    "vendors": [],
    "profilesTried": ["default"],
    "summary": "25 attempt(s): 25 returned HTTP 200 with no defense present and were rejected only by your validate.data - the page was fetched, your content rule did not match it"
  },
  "total": 34.812
}
الحقل النوع الوصف
total integer المحاولات المنفذة
noResponse integer لم يستجب منفذ الخروج نهائيا، لذا لم يتم الوصول إلى الموقع
defense integer استجاب الموقع واكتُشف فحص روبوتات (bot check) في تلك الاستجابة
contentRejected integer رمز HTTP 200، بدون فحص روبوتات، رُفض فقط بواسطة validate.data الخاص بك
statusRejected integer استجاب الموقع، بدون فحص روبوتات، رُفض بواسطة validate.status الخاص بك
other integer استجاب الموقع، مع عدم انطباق أي مما سبق
vendors string[] مزودو فحص الروبوتات الذين تم التعرف عليهم في أي مكان داخل المهمة
profilesTried string[] ملفات تعريف المتصفح التي أرسلتها المهمة، مرتبة حسب أول استخدام. القيمة default تعني أن request تم إرساله دون أي تعديل.
summary string جملة واحدة تم إنشاؤها من الأعداد، وهي آمنة للتسجيل في السجلات

تبقى سلسلة error بدون تغيير، لذا يستمر عمل العميل الذي يعتمد على مطابقتها. الإجراء المطلوب لكل عدد: أسباب استنفاد محاولات Proxy Request.

exitClass

ترفض بعض الأهداف منافذ الخروج في التجمع القياسي بغض النظر عن عدد المحاولات. توجه القيمة exitClass: premium خدمة Proxy بإمكانية تصعيد مثل هذا request إلى premium exit بالإضافة إلى التجمع القياسي، بدلا من الاكتفاء بالتدوير داخله فقط.

{
  "exitClass": "premium",
  "request": { "method": "GET", "url": "https://example.com/report" }
}

ثمة ثلاثة أمور يجدر معرفتها قبل الإرسال.

إنه سماح وليس أمراً إلزامياً. لا يزال المجمع القياسي (standard pool) يتسابق لتقديم الإجابة، وعادة ما ينجح أولاً. لا يتدخل مخرج premium إلا بعد استنفاد المجمع ميزانية زمنية قصيرة على الـ request أو بعد رفض الهدف له بشكل صريح. أي request يجيب عليه المجمع القياسي قبل تجربة أي مخرج premium يُعد نجاحاً عادياً ولا يستهلك أي رصيد من حركة مرور premium. بمجرد تجربة مخرج premium، تُحسب حركة المرور الخاصة به وفق ما هو موضح أدناه.

يظل مخرج premium مقيداً بـ exitCountries. عند تحديد قائمة دول، يخرج مخرج premium من إحدى تلك الدول ويحدده exitCountry في الـ response، تماماً كما هو الحال مع المجمع القياسي.

يوضح الـ response المخرج الفعلي الذي تولى خدمتك. عند تحديد class، يُرجع الـ response الترويسة exitClass:

{
  "status": 200,
  "exitClass": "premium",
  "proxy": "Y2QXVK",
  "data": "..."
}

premium تعني أن مخرج premium أعاد نص الاستجابة. تعني standard أن التجمع القياسي هو من أعاده، وهي الاستجابة نفسها التي تحصل عليها عندما يتعذر الحصول على مخرج premium، وعند استنفاد حركة مرور premium المضمنة في خطتك (بالإضافة إلى أي رصيد إضافي اشتريته) خلال فترة الفوترة. لا يُعد أي منهما خطأ، ويمكنك تسوية حركة مرور premium الخاصة بك مقابل هذه القيم لكل طلب بدلا من الاعتماد على رقم شهري. تُرسل القيمة نفسها في ترويسة الاستجابة X-FourA-Exit-Class (راجع Response Headers).

تُقاس حركة مرور premium على الشبكة. تحتسب محاولة premium ما تم إرساله واستلامه أثناء مروره عبر الشبكة، في حالته المضغوطة والمشفرة، سواء نجحت في إعادة صفحتك أم لا. المحاولة التي كانت لا تزال قيد التشغيل عندما رد مخرج آخر يتم إيقافها فورا، وتُحتسب حركة المرور التي نقلتها حتى تلك اللحظة أيضا. تُحتسب حركة مرور premium ضمن حصة premium المخصصة لك وكذلك ضمن إجمالي النطاق الترددي الخاص بك: نفس البايتات، تُسجل مرتين، ولا تُجمع معا أبدا. عندما يسلّم مخرج premium الصفحة، تكون حركة مروره هي إجمالي حركة مرور الطلب، لذلك لا تُحتسب الصفحة مرة أخرى كحركة مرور قياسية. تعرض صفحة Usage & Limits الخاصة بك إجمالي حركة المرور، ونسبة premium منها، وحصة premium المخصصة التي يتم تقييمك بناء عليها.

حذف الحقل وإرسال standard يُبقيان الطلب على التجمع القياسي: فقط premium يسمح باستخدام مخرج premium. الطلب الناجح الذي يحدد فئة يحصل على exitClass في الاستجابة، بينما لا يحصل الطلب الذي يحذف الحقل على ذلك.

نفاد الرصيد ليس خطأ. الطلب الذي يحدد premium بعد استنفاد الحصة يستمر في العمل: يتولى التجمع القياسي خدمته وتذكر الاستجابة standard. الاستثناء الوحيد هو الطلب الذي يحدد موقع مخرج: لا يمكن للتجمع القياسي تلبيته، لذا يتم رفضه.

تتطلب exitClass: premium خطة تتضمن مخارج premium. في الخطة التي لا تتضمنها، لا يستهلك الطلب مخرج premium أبدا: يتم رفضه بالرمز 403 متضمنا X-FourA-Limit: plan_limit_premium (راجع Rate Limits)، قبل تنفيذ أي عمل.

موقع المخرج

يمكن لمخرج premium أن ينطلق من موقع داخل دولة ما، ويحتفظ بعنوانه طالما احتجت إليه:

{
  "exitClass": "premium",
  "exitCountries": ["BG"],
  "exitCity": "sofia",
  "exitLifetimeMin": 15,
  "request": { "method": "GET", "url": "https://example.com/" }
}

يحدد الـ response نقطة الخروج (exit) والدولة التي خرج منها:

{
  "status": 200,
  "exitClass": "premium",
  "exitCountry": "BG",
  "proxy": "1EM4GZY",
  "data": "..."
}

يحفظ معرّف proxy هذا كل شيء. مرّره إلى Single أو Browser وسيخرج الـ request من نفس المكان، دون أي حقل آخر بجانبه. راجع Pinning an Exit.

القواعد:

  • أي من exitState وexitCity وexitAsn وexitOs وexitLifetimeMin يرسل الـ request عبر مخارج premium فقط. لا تتم أي محاولة عبر الـ pool القياسي، لأنه لا يمكنه تلبيتها.
  • تتطلب هذه الحقول exitClass: premium. بدونها يتم رفض الـ request برمز 400 يحدد اسم الحقل.
  • توجد exitState وexitCity وexitAsn داخل دولة واحدة، لذا فهي تتطلب دولة واحدة بالضبط في exitCountries. أما exitOs وexitLifetimeMin فيمكن استخدامهما مع عدة دول: يختار المخرج إحداها، ويوضح exitCountry في الـ response الدولة المختارة.
  • تتطلب exitState وexitCity وexitAsn وexitOs خطة تدعم الاستهداف الجغرافي (geo targeting) بالإضافة إلى مخارج premium.
  • عند نفاد رصيد premium، يتم رفض الـ request برمز 403 مع X-FourA-Limit: plan_limit_premium، لأن الـ pool القياسي لا يمكنه خدمته.
  • إذا لم يستجب أي مخرج premium لهذا الموقع، يكون الـ response عبارة عن مظروف خطأ مشابه للموجود ضمن exitCountries scoping، مع الخطأ No premium exit answered for this request وcode: no_eligible_proxy. يظهر details.exitCountries عند إرسال قائمة دول.

المصطلحات هي نفسها التي يقبلها proxy port لكل من state وcity وasn وos.

تدوير ملفات تعريف المتصفح (Browser Profile Rotation)

يقوم Proxy بتدوير المخارج. عندما يرفض أحد المواقع المتصفح الذي قدمته FourA بدلا من المخرج الذي أتى منه، ينتقل Proxy أيضا إلى عائلة متصفح أخرى من الدليل. لا يضيف هذا أي محاولة إضافية: التدوير يغير ما ترسله إعادة المحاولة، ولا يحدد أبدا ما إذا كانت ستحدث أم لا.

يتذكر Proxy أيضا، لفترة معينة، آخر عائلة قبلها الموقع، بحيث يمكن لأي طلب لاحق لنفس الموقع البدء بتلك العائلة بدلا من الإعداد الافتراضي. يحدد الـ response اسمها في profile، كما يفعل مع أي عائلة يختارها التدوير.

لا يتم أبدا تجاوز أي تعيين صريح لـ profile أو browser أو os أو version في الـ request الداخلي الخاص بك، ولا يتم تجاوز أي request يتضمن header الـ User-Agent أو Cookie الخاص به، لأن إذن المرور يرتبط بالبصمة التي حصلت عليه.


طلب Browser (Browser Request)

POST /api/browser/

يفتح عنوان الـ URL الخاص بك في مثيل متصفح Chrome. يتم تحميل الصفحة، وتنفيذ JavaScript، وتحصل على الـ HTML المعروض بالكامل بالإضافة إلى الـ cookie jar.

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

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

مطابقة ساعة المتصفح مع نقطة الخروج

يمكن للصفحة قراءة المنطقة الزمنية للمتصفح ومقارنتها بدولة عنوان IP الذي تراه. يعد عدم التطابق أحد أبسط المؤشرات التي تعتمد عليها أنظمة كشف البوت، ولن يكلفك التخلص منه أي جهد.

لا تحتاج إلى اتخاذ أي إجراء. يقرأ FourA الدولة من معرّف proxy، ويبلّغ المتصفح عن منطقة زمنية تابعة لها.

  • إنها دولة نقطة الخروج، أي الدولة التي يراها الموقع المستهدف، وليست الدولة التي يُستضاف فيها الـ proxy. يختلف الاثنان بشكل متكرر يكفي لإحداث فرق.
  • عندما لا يتعرف FourA على دولة نقطة الخروج، فإنه يترك ساعة المتصفح دون تغيير بدلاً من التخمين. تملك نقطة الخروج من نوع premium دولة معروفة عند تحديدها باستخدام exitCountries في Proxy Request.
  • الساعة فقط هي التي تتبع الدولة. تظل ترويسة Accept-Language والمحتوى الذي يقدمه الموقع دون تغيير، لذا لن تتغير لغة الصفحة فجأة.

المعامل userAgent

أرسل userAgent وستكون هذه السلسلة تحديداً هي ما تراه الصفحة وعمالها (workers) والموقع المستهدف. يستنتج FourA أيضاً إشارات العميل (client hints) المطابقة منها (sec-ch-ua وsec-ch-ua-platform وnavigator.platform والقيم عالية العشوائية التي يطلبها نظام الكشف بالاسم)، وبذلك لا يصرّح الطلب عن متصفح معين في الترويسة وآخر في JavaScript.

قيمة userAgent الواردة في الاستجابة هي القيمة التي تم تقديمها بالفعل. هذا الأمر مهم عند إعادة استخدام إذن المرور: يرتبط ملف تعريف الارتباط cf_clearance بنقطة الخروج وقيمة User-Agent التي حصلت عليه، لذا أعد إرسال السلسلة التي أبلغت عنها الاستجابة، وليس السلسلة التي تعتقد أنه تم استخدامها. راجع Site checks.

أرسل سلسلة نصية غير تابعة لـ Chromium (مثل User-Agent الخاص بـ Firefox) وسيتم تقديمها كما هي، دون إرفاق أي قائمة علامات تجارية خاصة بـ Chromium.

مثال

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"
  }'

Response:

{
  "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"]}
}
الحقل النوع الوصف
status number رمز حالة HTTP من الهدف
headers object ترويسات الاستجابة
body string أو object محتوى الصفحة المعروض بالكامل. نص HTML عندما يكون content-type هو HTML؛ وobject عندما تُرجع الصفحة JSON ويتم تحليله تلقائياً.
cookies array كائنات ملفات تعريف الارتباط الكاملة من الصفحة. يتضمن كل ملف تعريف ارتباط name و value و domain و path و expires و httpOnly و secure و sameSite وخصائص ملفات تعريف الارتباط الأخرى.
userAgent string User-Agent الخاص بالمتصفح المستخدم
defenseSolved boolean يكون true إذا تمت مواجهة نظام حماية من البوت وتجاوزه بنجاح في هذا الاستدعاء، ويكون false في غير ذلك. يحدد ما إذا كان الاستدعاء يستهلك 5 أو 10 رصيد.
defenses object يسرد present جميع المزودين الذين تم التعرف عليهم أثناء تحميل الصفحة، ويسرد cleared المزودين الذين تتضمن الصفحة النهائية إذناً بتجاوزهم. قد يظهر المزود في present ولا يظهر أبداً في cleared. راجع Site checks.
proxy string المعرف المشفر لـ proxy الذي مر الطلب من خلاله (فقط عند تزويد proxy في الطلب). أعد استخدامه في الاستدعاءات اللاحقة للاحتفاظ بنفس نقطة الخروج.
error string رسالة الخطأ في حالة فشل الطلب

تثبيت نقطة الخروج

تُثبت قيمة proxy في طلب Single أو Browser نقطة الخروج التي استخدمها استدعاء سابق. أعد تمرير المعرف غير الشفاف تماماً كما ورد، ولا تمرر أبداً عنوان proxy. يحتفظ المعرف الناتج عن طلب Proxy الذي حدد بلداً أو مكاناً أو مدة صلاحية بتلك الإعدادات، لذا لا يحتاج الطلب المثبت إلى أي حقل آخر.

توجد ثلاث قيم مرفوضة، وجميعها برمز الحالة 400:

الخطأ المعنى
Invalid proxy format القيمة ليست معرفاً صادراً عن FourA. عنوان proxy المباشر يؤدي إلى هذا الخطأ.
Proxy not found تم فك تشفير المعرف، لكنه لم يعد يشير إلى نقطة خروج نشطة. احصل على معرف جديد من استدعاء جديد.
Managed exit: this proxy id cannot be pinned to a request نقطة الخروج موجودة، لكنها ليست نقطة تبقيها FourA مفتوحة لطلب مسمى. يؤدي معرف نقطة خروج premium إلى هذا الخطأ عندما لا يتبقى في خطتك حركة مرور premium لاستخدامها. أعد استخدام الجلسة التي وردت معها، أو نفّذ الاستدعاء عبر POST /api/proxy/ واستخدم نقطة الخروج التي يختارها.

تُحسب نقطة خروج premium المثبتة كحركة مرور premium. تتضمن الاستجابة X-FourA-Exit-Class: premium لتتمكن من تتبعها لكل طلب، وتُحسب حركة المرور التي نقلتها نقطة الخروج ضمن حركة مرور premium في صفحة Usage & Limits الخاصة بك بالإضافة إلى إجمالي استهلاك البيانات، سواء أرجَع الموقع الصفحة المطلوبة أم لا. يتطلب التثبيت توفر نقاط خروج premium في خطتك ورصيداً متبقياً، وإلا فسيتم رفض المعرف برمز 400 لنقطة الخروج المدارة الموضح أعلاه.

رموز حالة HTTP

الرمز المعنى
200 اكتمل الطلب (تحقق من status الداخلي لمعرفة استجابة الهدف)
400 نص طلب غير صالح، أو معلمات غير صالحة، أو IP الهدف يقع ضمن نطاق خاص/محجوز، أو هدف على مضيف API التابع لـ FourA نفسه، أو URL يحتوي على مسافة غير مشفرة بداخله (Single، Proxy، Auto)، أو معرف proxy لا يمكن تثبيته. في Single وProxy وBrowser، يتم تحديد الحقل الذي فشل في التحقق عبر: Invalid request: <field>: <reason>، بحد أقصى خمسة حقول. لا يتم احتساب تكلفة. يرد Auto على نفس الخطأ برمز HTTP 200 وstatus: 400 في نص الاستجابة.
401 مفتاح API مفقود أو غير صالح
403 نقطة النهاية (endpoint) أو إحدى المعلمات غير مشمولة في خطتك. يحدد X-FourA-Limit ذلك عبر: plan_limit_feature أو plan_limit_premium.
404 Not Found: لا توجد نقطة نهاية (endpoint) في هذا المسار.
413 حجم نص طلب JSON يتجاوز 100 كيلوبايت. الاستجابة ليست بتنسيق JSON ولا تحمل أي X-FourA-Request-Id.
429 تم تجاوز حد الخطة (تم تعيين X-FourA-Limit) أو الحصة المشتركة للمنصة في الدقيقة (بدون header)
500 خطأ داخلي في الخادم
502 Upstream unavailable: تعذر على FourA الاتصال بمحركه. Malformed JSON from backend: استجاب المحرك ولكن تعذر على FourA قراءة الرد. أعد المحاولة.
503 الخدمة معطلة مؤقتا أو وصلت إلى طاقتها الاستيعابية القصوى، API key check temporarily unavailable عندما يتعذر على FourA تأكيد مفتاحك للحظات (أعد المحاولة بعد Retry-After)، أو Backend service unavailable أثناء إعادة تشغيل المحرك. في Browser، تنتظر الصفحة ما يصل إلى 10 ثوان للحصول على متصفح متاح عندما تكون جميعها مشغولة، وتتلقى Backend service unavailable إذا لم يتوفر أي منها خلال ذلك الوقت.
504 Upstream timeout. لم يكمل المحرك المعالجة ضمن المهلة الزمنية المحددة لهذا الطلب. قم بزيادة timeout_ms أو أعد المحاولة.

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

آخر تحديث: 13 نوفمبر 2026