مرجع 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 أو أعد المحاولة. |
الخطوات التالية
- Smart Fetch (Auto): متى تترك FourA يختار المسار نيابة عنك
- Choosing the Right Endpoint: متى تختار Single أو Proxy أو Browser يدويا
- Authentication: إدارة مفاتيح API الخاصة بك
- Error Handling: معالجة الأخطاء بسلاسة
- Site checks: قراءة حقل
defenseوإعادة تطبيق التخويل - Why a Proxy Request Ran Out of Tries: قراءة
attemptReportوالتصرف بناء عليها - Rate Limits: فهم حدود الطلبات
- Quick Start: أول طلب لك في 30 ثانية