ترويسات Response

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

الـ Headers التي تعينها FourA

Header	يُعين في	الوصف
`X-Foura-Request-Id`	كل response لـ `/api/*`، بما في ذلك الأخطاء وحالات 401	معرف UUID يحدد هذا الـ request. قم بتسجيله في سجلاتك.
`Content-Type`	كل response	دائماً `application/json` للغلاف. يأتي الـ content-type الخاص بالهدف داخل حقل `headers` في الغلاف.

X-Foura-Request-Id

يتم تمييز كل استدعاء لـ 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
Content-Type: application/json
...

متى تستخدمه

تذاكر الدعم: قم بتضمين الـ request ID وسنتمكن من العثور على الاستدعاء بدقة في سجلاتنا.
سجلاتك الخاصة: قم بتخزينه بجانب سطر سجل التطبيق الخاص بك. إذا اشتكى عميل من أن "البيانات كانت خاطئة في الساعة 14:32"، يمكنك إعادة تشغيل الـ request بدقة.
تتبع Dashboard: يظهر نفس المعرف في Activity feed للمفاتيح التي تديرها، بحيث يمكنك فتح الصف المطابق وفحص الـ 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")
    log.info("foura request_id=%s url=%s status=%s", request_id, url, resp.status_code)
    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';
  console.log(`foura request_id=${requestId} url=${url} status=${resp.status}`);

  return resp.json();
}

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

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

ترويسات Response للموقع الهدف

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

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

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