يتضمن كل response من FourA API مجموعة صغيرة من الـ headers المخصصة. وهي مفيدة للتتبع والدعم وتسوية الفواتير والتحليل اللاحق.

Headers يضبطها FourA

Header يُضبط عند الوصف
X-FourA-Request-Id كل response لـ /api/*، بما في ذلك الأخطاء وحالات 401، باستثناء body لا يستطيع FourA قراءته إطلاقاً (400 Invalid JSON in request body، 413)، والذي يتم رفضه قبل تعيين معرف UUID يحدد هذا الـ request. سجله في سجلاتك.
X-FourA-Credits كل response لـ /api/* وصل إلى الـ backend الرصيد المستهلك في هذا الاستدعاء. يُعاد عند النجاح وعند الفشل (تم تنفيذ العمل في الحالتين).
X-FourA-Limit كل 403 أو 429 ينتج عن أحد حدود خطتك الحد الذي رفض الاستدعاء: plan_limit_ متبوعاً بـ feature، أو premium، أو concurrency، أو rate، أو browser_daily، أو credits، أو bandwidth.
Retry-After حالات 429 لحدود الخطة التي يزيلها الانتظار (التزامن، ومعدل الطلبات، والرصيد، وعرض النطاق الترددي) و 503 API key check temporarily unavailable ثواني الانتظار، كعدد صحيح. يطابق retry_after_seconds في body حد الخطة و retryAfter في رمز 503.
X-FourA-Exit-Class كل استدعاء /api/proxy/ أو /api/auto/ حدد exitClass وقام بتسليم صفحة، وكل استدعاء Single أو Browser تم تقديمه عبر مخرج مميز premium أو standard: فئة المخرج الذي قام بتسليم الـ body. استدعاء Proxy الفاشل لم يسلم شيئاً ولا يحمل أي قيمة.
X-FourA-Browser-Used-Today كل استجابة POST /api/browser/ لم ترفضها حدود خطتك، وكل استجابة POST /api/auto/ أرسل تسلسلها request لم ترفضه الحدود طلبات Browser المحتسبة اليوم على حسابك: انظر أدناه.
X-FourA-Browser-Limit-Per-Day نفس الاستجابات، عندما تحدد خطتك عدداً يومياً طلبات Browser التي تسمح بها خطتك يومياً.
X-FourA-Check-Page استجابات Single و Proxy Finder و Browser التي يكون فيها HTTP 200 body صفحة فحص bot أو صفحة رفض يتعرف عليها FourA اسم الصفحة، على سبيل المثال amazon-captcha. لا يتم احتساب تكلفة هذا الـ request: انظر Request Outcomes.
Content-Type كل response دائماً application/json للغلاف (envelope). يُعاد content-type للهدف داخل حقل headers الخاص بالغلاف.

X-FourA-Request-Id

يتم تمييز كل استدعاء إلى POST /api/auto/، أو POST /api/single/، أو POST /api/proxy/، أو POST /api/browser/ بـ UUID. يتم ضبط الـ header حتى عند فشل المصادقة، لتتمكن من ربط الاستدعاءات الخاطئة أيضاً.

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/1.1 200 OK
X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
X-FourA-Credits: 2
Content-Type: application/json
...

حالات الاستخدام

  • تذاكر الدعم الفني: قم بتضمين معرف الـ request وسنتمكن من العثور على الاستدعاء بدقة في سجلاتنا.
  • سجلاتك الخاصة: احفظه بجانب سطر سجل تطبيقك. إذا وردت شكوى من عميل تفيد بأن "البيانات كانت غير صحيحة عند الساعة 14:32"، يمكنك إعادة تنفيذ نفس الـ request بدقة.
  • التتبع عبر لوحة التحكم: يظهر المعرف نفسه في موجز النشاط للمفاتيح التي تديرها، مما يتيح لك فتح الصف المطابق وفحص الـ request والـ response الملتقطين.

مثال: التسجيل من جانبك

import logging
import requests

log = logging.getLogger(__name__)

def fetch(url, api_key):
    resp = requests.post(
        "https://eu.api.foura.ai/api/single/",
        headers={"X-API-Key": api_key, "Content-Type": "application/json"},
        json={"method": "GET", "url": url},
    )
    request_id = resp.headers.get("X-FourA-Request-Id", "no-id")
    credits = resp.headers.get("X-FourA-Credits", "0")
    log.info("foura request_id=%s url=%s status=%s credits=%s", request_id, url, resp.status_code, credits)
    resp.raise_for_status()
    return resp.json()
async function fetchPage(url, apiKey) {
  const resp = await fetch('https://eu.api.foura.ai/api/single/', {
    method: 'POST',
    headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
    body: JSON.stringify({ method: 'GET', url })
  });

  const requestId = resp.headers.get('X-FourA-Request-Id') || 'no-id';
  const credits = resp.headers.get('X-FourA-Credits') || '0';
  console.log(`foura request_id=${requestId} url=${url} status=${resp.status} credits=${credits}`);

  return resp.json();
}

X-FourA-Credits

يُبلغ X-FourA-Credits عن تكلفة الرصيد للاستدعاء الذي قمت به للتو. إنه مقياس استهلاك وليس فاتورة: يعكس header ما استهلكه العمل بغض النظر عن النتيجة. تحتسب طبقة الفوترة في لوحة التحكم النتائج الخاضعة للفوترة فقط ضمن خطتك (راجع نتائج الطلب لمعرفة النتائج الخاضعة للفوترة).

مرجع التكلفة

Engine Base With unblocker
Single 1 2
Proxy 2 4
Browser 5 10 (when a defense was solved)

يُمثل /api/auto/ طلبًا واحدًا على لوحة التحكم الخاصة بك، وتكون تكلفة رصيده هي مجموع الاستدعاءات الفرعية التي أجراها داخليًا (قد تنتهي إعادة تشغيل واحدة على هدف جاهز بتكلفة 2، بينما يمكن أن يستهلك الحل الأولي على موقع صعب تكلفة أكبر بكثير). تتطابق قيمة X-FourA-Credits في استجابة auto مع meta.credits في جسم الاستجابة، وتتتبع تكلفة المسار بالكامل.

لماذا يتوفر في كل من header وحقل body؟

يتميز الـ header بسهولة الاستخدام: يمكنك قراءته قبل تحليل الـ body، أو تسجيله بجانب سطر الطلب الخاص بك، أو حسابه عبر استدعاءات متعددة دون الحاجة إلى معالجة JSON. في وضع Auto، يتضمن meta.credits في الـ body نفس الرقم. لا تحتوي أجسام Single وProxy وBrowser عليه، لذا فإن الـ header هو المكان الوحيد لقراءته في تلك الاستجابات. يظهر أيضًا في صف النشاط الخاص بكل استدعاء.

X-FourA-Limit

لا يظهر X-FourA-Limit إلا عندما يرفض أحد حدود خطتك الاستدعاء. لا تقوم حدود معدل الاستخدام المشتركة للنظام بتعيينه مطلقًا، لذا فإن الـ header هو أسرع طريقة للتمييز بين "خطتي أوقفت هذا" و"FourA مشغول" دون تحليل الـ body.

HTTP/1.1 429 Too Many Requests
X-FourA-Limit: plan_limit_concurrency
Retry-After: 1
X-FourA-Request-Id: 9f1c4e6c-7b2a-4d3e-8a1f-2c9d8e4a3b15
Content-Type: application/json

تأتي قيمتان من القيم السبع برمز 403 بدلا من 429: plan_limit_feature (الـ endpoint أو المعامل exitCountries غير مشمولين في خطتك) و plan_limit_premium (exitClass: premium غير مشمول في خطتك). لا يقوم أي منهما بتعيين Retry-After، لأن الانتظار لن يغير النتيجة.

STOP_ON = {
    "plan_limit_feature", "plan_limit_premium",
    "plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth",
}

resp = requests.post(url, headers=headers, json=payload)

limit = resp.headers.get("X-FourA-Limit")
if limit in STOP_ON:
    stop_the_run(limit)                # hours or days away, not seconds
elif limit:
    time.sleep(int(resp.headers.get("Retry-After", 1)))

القيم السبع وحقول body المرافقة لكل منها موجودة في Rate Limits.

X-FourA-Exit-Class

يحدد X-FourA-Exit-Class فئة المخرج الذي قام بتسليم الـ body: القيمة premium عندما يقدمه مخرج premium، والقيمة standard عندما تقدمه المجموعة standard. يظهر هذا الـ header في استجابة POST /api/proxy/ أو POST /api/auto/ التي سلمت صفحة كلما حدد الـ request قيمة exitClass، حيث يحمل الـ body نفس القيمة (exitClass في Proxy، وmeta.exitClass في Auto)، ويظهر في استجابة Single أو Browser كلما كان الـ proxy الذي قمت بتثبيته مخرج premium، حيث لا يحتوي الـ body على حقل له. استدعاء Proxy أو Auto الفاشل لم يقدم أي محتوى، وبالتالي لا يحمل الـ header ولا الحقل.

HTTP/1.1 200 OK
X-FourA-Exit-Class: premium
X-FourA-Credits: 2
X-FourA-Request-Id: 2c1d0f9e-4a7b-4c3e-9d2a-8b1f6e5c4d3a
Content-Type: application/json

يُحسب traffic عبر premium exit ضمن premium traffic الخاص بك وكذلك ضمن إجمالي bandwidth. يتم قياسه على الشبكة ويشمل محاولات premium التي لم تُرجع صفحتك، لذا فإن أي request تمت الإجابة عليه بواسطة standard قد يكون استهلك جزءًا من premium traffic، في محاولة فشلت قبل أن يجيب الـ standard pool. يُحدد هذا header الفئة التي قامت بالتسليم، وليس ما إذا كان قد تم استخدام premium traffic أم لا: تُظهر علامة premium في صف Activity وصفحة Usage & Limits ما تم احتسابه. ما يقوم به exitClass ومتى يتم استخدام premium exit: exitClass.

X-FourA-Browser-Used-Today و X-FourA-Browser-Limit-Per-Day

يحمل هذان الـ headers حصة المتصفح اليومية الخاصة بك في الـ response نفسه، وهي نفس الأرقام التي تعرضها صفحة Usage & Limits، حتى تتمكن من متابعتها دون الحاجة للتحقق المستمر من dashboard.

HTTP/1.1 200 OK
X-FourA-Browser-Used-Today: 1250
X-FourA-Browser-Limit-Per-Day: 5000
X-FourA-Credits: 47
X-FourA-Request-Id: 2c1d0f9e-4a7b-4c3e-9d2a-8b1f6e5c4d3a
Content-Type: application/json

يبدأ العد مجددا عند منتصف الليل بتوقيت UTC ويشمل كل مفتاح في خطتك، وليس فقط المفتاح الذي أجرى هذا الاستدعاء. الطلب الذي رفضته حدود خطتك لا يحمل أيا من header: يحتوي جسمه على used_today و limit_per_day بدلا من ذلك، راجع Rate Limits.

في POST /api/browser/ يتضمن العد الطلب الذي تقرأه. وفي POST /api/auto/ يمثل أعلى عد تلقاه ladder أثناء تشغيله، لذا قد يتأخر عن إجمالي اليوم بسبب طلباتك الأخرى التي لا تزال قيد التشغيل. الاستجابة التلقائية Auto التي لم ترسل أي طلب، مثل فترة التوقف لمدة 120 ثانية بعد حالات الفشل المتكررة في أحد المواقع، لا تحمل أيا من header. ما استهلكه استدعاء Auto واحد من العد موجود في meta.browserRequests: راجع Smart Fetch.

سلوك التخزين المؤقت

لا تعين API القيمة Cache-Control. يمكن أن تحمل الاستجابة قيمة ETag ضعيفة محسوبة من جسمها، ولكن لا يتم تخزين أي شيء مؤقتا: كل استدعاء يصل إلى backend. إذا كنت بحاجة إلى التخزين المؤقت، فأضفه من جانبك.

ترويسات استجابة الهدف

إن headers التي أعادها الموقع الهدف ليست موجودة في استجابة FourA API. بل تعود داخل غلاف JSON في حقل headers. بالنسبة لنقاط النهاية Single و Proxy، يكون هذا مصفوفة من كائنات headers لكل قفزة (إدخال واحد لكل خطوة إعادة توجيه). أما بالنسبة لنقطة النهاية Browser، فهو كائن مسطح يحتوي على headers للاستجابة النهائية.

{
  "status": 200,
  "headers": [
    { "Content-Type": "text/html; charset=utf-8", "Server": "..." }
  ],
  "data": "<!doctype html>...",
  "total_time": 0.42
}

إذا كنت بحاجة إلى header هدف محدد، فاقرأه من حقل headers الخاص بـ envelope، وليس من استجابة HTTP لطلب API نفسه.

  • API Endpoints: هياكل مغلفات request وresponse
  • API Errors: كيفية تنظيم استجابات الأخطاء
  • Request Outcomes: أي النتائج قابلة للفوترة
  • Activity Log: سجل لكل request مفهرس حسب معرّف request
  • Rate Limits: ما يعنيه كل قيمة لـ X-FourA-Limit
آخر تحديث: 5 نوفمبر 2026