# مرجع API Endpoints

> URL: https://foura.ai/ar/docs/api/endpoints
> Updated: 2026-11-13
> Index: https://foura.ai/llms.txt

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

## عنوان URL الأساسي

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

## المصادقة

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

```bash
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](https://foura.ai/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](https://foura.ai/docs/api/outcomes) لمعرفة النتائج الخاضعة لاحتساب التكلفة. |

يربط معرف الـ request نفسه معاينة حمولة الـ request والـ response في [Activity Log](https://foura.ai/docs/dashboard/activity-log) في Dashboard (يتم الاحتفاظ بها لمدة 24 ساعة، لآخر 200 لكل مفتاح)، بحيث يمكنك البحث عن الـ request بدقة لاحقا وإعادة تشغيله من Activity مباشرة إلى [Playground](https://foura.ai/docs/dashboard/playground). قم بتضمينه عند الاتصال بالدعم، وسيحدد الـ request في ثوان معدودة.

```bash
$ 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](https://foura.ai/docs/api/response-headers) للاطلاع على القائمة الكاملة ونصائح الاستخدام.

## نقاط النهاية (Endpoints)

> **هل تستخدم نقاط النهاية هذه عبر MCP؟** يوفّر خادم [`@fouradata/mcp`](https://foura.ai/docs/mcp/server) نقاط النهاية الأربع كأدوات MCP أصلية (`foura_auto` و `foura_single` و `foura_proxy` و `foura_browser`) بنفس هياكل الإدخال، بالإضافة إلى خيار `offload_large` لمعالجة الاستجابات الكبيرة بكفاءة من حيث استهلاك الـ tokens. الفروقات: لا يحتوي `foura_browser` على حقل `lean`، كما أن `foura_proxy` لا يدعم حقول [موقع الخروج (exit location)](#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. |

للحصول على شرح أكثر تفصيلاً حول متى تختار كل منها، راجع [اختيار نقطة النهاية المناسبة](https://foura.ai/docs/guides/choosing-task-type) ودليل [الجلب الذكي (Smart Fetch)](https://foura.ai/docs/guides/smart-fetch).

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

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

```json
{ "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`](https://foura.ai/docs/api/inspect).

```json
{ "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](#exitclass). يتيح `premium` تصعيد الطلب إلى مخرج مميز (premium exit) بمجرد عجز المجموعة القياسية عن الوصول إلى الصفحة. يتطلب خطة تتضمن مخارج مميزة. راجع [exitClass on Smart Fetch](#exitclass-on-smart-fetch). |

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

```json
{
  "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](https://foura.ai/docs/guides/smart-fetch). |

### مثال

```bash
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)](https://foura.ai/docs/dashboard/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)](#exitclass): فهو تصريح وليس أمرا ملزما. يحاول 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`. لا يمكن تثبيت بعض المعرّفات: راجع [تثبيت نقطة الخروج](#pinning-an-exit). |
| `browser` | string | لا | Chrome | المتصفح المراد تمثيله: Chrome أو Edge أو Safari أو Firefox أو Tor. راجع [ملفات تعريف المتصفح](#browser-profiles). |
| `os` | string | لا | - | نظام التشغيل المراد تمثيله: Windows أو macOS أو Android أو iOS. يقبل اسم الفئة أيا من إصداراتها. |
| `version` | string | لا | newest | إصدار المتصفح المراد تمثيله، كما هو مدرج في الدليل. عند وجود أكثر من تطابق، يتم اختيار الأحدث. |
| `profile` | string | لا | - | معرّف ملف التعريف الدقيق من `GET /api/profiles`، بدلا من الحقول الثلاثة المذكورة أعلاه. |
| `validate` | object | لا | - | قواعد التحقق من صحة الاستجابة (انظر أدناه) |

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

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

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

القواعد:

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

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

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

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

### قواعد التحقق

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

```json
{
  "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 تؤدي إلى الفشل |

### مثال

```bash
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:

```json
{
  "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` يحدد اسم المزود وما إذا كان الفحص قد تم تجاوزه بنجاح:

```json
{
  "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` ما إذا كانت إعادة المحاولة قد جلبت المحتوى. راجع [فحوصات الموقع](https://foura.ai/docs/api/site-checks) للاطلاع على كل حقل والقائمة الكاملة للأنظمة. |
| `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](#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 مع غلاف خطأ:

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

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

### مثال

```bash
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:

```json
{
  "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` بجانب الخطأ:

```json
{
  "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](https://foura.ai/docs/troubleshooting/proxy-attempt-report).

### exitClass

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

```json
{
  "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`:

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

`premium` تعني أن مخرج premium أعاد نص الاستجابة. تعني `standard` أن التجمع القياسي هو من أعاده، وهي الاستجابة نفسها التي تحصل عليها عندما يتعذر الحصول على مخرج premium، وعند استنفاد حركة مرور premium المضمنة في خطتك (بالإضافة إلى أي رصيد إضافي اشتريته) خلال فترة الفوترة. لا يُعد أي منهما خطأ، ويمكنك تسوية حركة مرور premium الخاصة بك مقابل هذه القيم لكل طلب بدلا من الاعتماد على رقم شهري. تُرسل القيمة نفسها في ترويسة الاستجابة `X-FourA-Exit-Class` (راجع [Response Headers](https://foura.ai/docs/api/response-headers#x-foura-exit-class)).

**تُقاس حركة مرور premium على الشبكة.** تحتسب محاولة premium ما تم إرساله واستلامه أثناء مروره عبر الشبكة، في حالته المضغوطة والمشفرة، سواء نجحت في إعادة صفحتك أم لا. المحاولة التي كانت لا تزال قيد التشغيل عندما رد مخرج آخر يتم إيقافها فورا، وتُحتسب حركة المرور التي نقلتها حتى تلك اللحظة أيضا. تُحتسب حركة مرور premium ضمن حصة premium المخصصة لك وكذلك ضمن إجمالي النطاق الترددي الخاص بك: نفس البايتات، تُسجل مرتين، ولا تُجمع معا أبدا. عندما يسلّم مخرج premium الصفحة، تكون حركة مروره هي إجمالي حركة مرور الطلب، لذلك لا تُحتسب الصفحة مرة أخرى كحركة مرور قياسية. تعرض صفحة [Usage & Limits](https://foura.ai/docs/dashboard/quota) الخاصة بك إجمالي حركة المرور، ونسبة premium منها، وحصة premium المخصصة التي يتم تقييمك بناء عليها.

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

**نفاد الرصيد ليس خطأ.** الطلب الذي يحدد `premium` بعد استنفاد الحصة يستمر في العمل: يتولى التجمع القياسي خدمته وتذكر الاستجابة `standard`. الاستثناء الوحيد هو الطلب الذي يحدد [موقع مخرج](#exit-location): لا يمكن للتجمع القياسي تلبيته، لذا يتم رفضه.

تتطلب `exitClass: premium` خطة تتضمن مخارج premium. في الخطة التي لا تتضمنها، لا يستهلك الطلب مخرج premium أبدا: يتم رفضه بالرمز 403 متضمنا `X-FourA-Limit: plan_limit_premium` (راجع [Rate Limits](https://foura.ai/docs/api/rate-limits#plan-limits))، قبل تنفيذ أي عمل.


### موقع المخرج

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

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

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

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

يحفظ معرّف `proxy` هذا كل شيء. مرّره إلى Single أو Browser وسيخرج الـ request من نفس المكان، دون أي حقل آخر بجانبه. راجع [Pinning an Exit](#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](#exitcountries-scoping)، مع الخطأ `No premium exit answered for this request` و`code: no_eligible_proxy`. يظهر `details.exitCountries` عند إرسال قائمة دول.

المصطلحات هي نفسها التي يقبلها [proxy port](https://foura.ai/docs/api/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](#exit-location).
- الساعة فقط هي التي تتبع الدولة. تظل ترويسة `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](https://foura.ai/docs/api/site-checks).

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

### مثال

```bash
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:

```json
{
  "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](https://foura.ai/docs/api/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](https://foura.ai/docs/dashboard/quota) الخاصة بك بالإضافة إلى إجمالي استهلاك البيانات، سواء أرجَع الموقع الصفحة المطلوبة أم لا. يتطلب التثبيت توفر نقاط خروج 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)](https://foura.ai/docs/guides/smart-fetch): متى تترك FourA يختار المسار نيابة عنك
- [Choosing the Right Endpoint](https://foura.ai/docs/guides/choosing-task-type): متى تختار Single أو Proxy أو Browser يدويا
- [Authentication](https://foura.ai/docs/getting-started/authentication): إدارة مفاتيح API الخاصة بك
- [Error Handling](https://foura.ai/docs/api/errors): معالجة الأخطاء بسلاسة
- [Site checks](https://foura.ai/docs/api/site-checks): قراءة حقل `defense` وإعادة تطبيق التخويل
- [Why a Proxy Request Ran Out of Tries](https://foura.ai/docs/troubleshooting/proxy-attempt-report): قراءة `attemptReport` والتصرف بناء عليها
- [Rate Limits](https://foura.ai/docs/api/rate-limits): فهم حدود الطلبات
- [Quick Start](https://foura.ai/docs/getting-started/quick-start): أول طلب لك في 30 ثانية
