Server API

يتيح Server API لخادمك الخلفي أن يقرأ بيانات التعرّف التي جمعها TRACIO بالفعل لمساحة عملك: تاريخ الزائر، والجلسات المفردة، وعدّادات velocity على نافذة قصيرة.

وهو مكمّل لـ Webhooks لا بديل عنها:

كلا السطحين متاح اعتبارًا من خطة Pro وما فوقها.

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

https://api.tracio.ai/v1

هذا مضيف مختلف عن نقطة نهاية المتصفح (edge.tracio.ai) وعن لوحة التحكم (app.tracio.ai). والثلاثة منفصلة: يتحدث المتصفح إلى الحافة بمفتاحك العام، ويتحدث خادمك الخلفي إلى Server API بمفتاحك السرّي.

المصادقة

يحمل كل طلب مفتاحك السرّي بوصفه رمز bearer:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Server API مخصّص للاتصال بين الخوادم فقط. فترويسات CORS لا تُعاد عن قصد، ولذلك لا يستطيع المتصفح استدعاءه — وهذا هو ما يُبقي مفتاحك السرّي خارج الكود الذي يعمل من جهة العميل. لا تشحن المفتاح السرّي إلى المتصفح أبدًا.

الحصول على مفتاح سرّي

أنشئه في لوحة التحكم ضمن API Keys، واختر النوع secret.

• يُعرض المفتاح كاملًا مرة واحدة فقط، لحظة الإنشاء. ولا يُخزَّن لدينا سوى تجزئة له، فالمفتاح المفقود لا يمكن استرجاعه — بل يجري تدويره بدلًا من ذلك.
• يبدو المفتاح السرّي هكذا: tracio_sk_ متبوعًا بـ 43 حرفًا، أي 53 حرفًا في المجموع. وتسرده لوحة التحكم بأحرفه الأولى القليلة لتتمكّن من التمييز بين المفاتيح.
• تتطلب المفاتيح السرّية خطة Pro أو أعلى؛ أما المفتاح العام الذي يستخدمه وكيل المتصفح فهو قيمة منفصلة غير سرّية من 40 حرفًا.

تدوير مفتاح سرّي

يُصدر التدوير مفتاحًا جديدًا ويُبقي القديم صالحًا لمدة 7 أيام، فيمكنك طرحه دون توقّف للخدمة. انشر المفتاح الجديد، وتأكّد من انتقال حركة الطلبات إليه، ثم دع القديم ينتهي. أما المفاتيح العامة فغير قابلة للتدوير — فهي ليست أسرارًا وهي ظاهرة في شفرة صفحتك عن قصد.

نقاط النهاية

كل مسار هو GET. ولا توجد عمليات كتابة في Server API: فهو يقرأ البيانات، أما إعداداتك فتعيش في لوحة التحكم.

تُقبل الشرطة المائلة في نهاية المسار ويجري تجاهلها. أما المسار غير المعروف أو الطريقة الخاطئة فيعيدان مغلّف أخطاء JSON نفسه الذي يعيده كل شيء آخر، لا صفحة HTML ولا نصًّا عاديًا أبدًا.

النافذة الزمنية

كل قراءة محدودة بنافذة زمنية يضبطها معامِلا استعلام اختياريان:

• التاريخ المجرّد في to يشمل ذلك اليوم بأكمله.
• وأي شيء آخر يُرفض بالرمز 400 invalid_request وبالرسالة time must be YYYY-MM-DD or RFC3339.
• وإن لم تمرّر أيًّا منهما، كانت النافذة هي مدّة الاحتفاظ الكاملة لخطتك، منتهيةً الآن.
• والنافذة الممتدّة إلى الوراء أبعد مما تسمح به خطتك تُقلَّم بصمت بدل أن تُرفض. والنافذة المستخدَمة فعليًا يُبلَّغ عنها دائمًا في meta، لذا راجع meta.from وmeta.to بدل افتراض أن طلبك نُفِّذ حرفيًا.

البحث عن زائر

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

تحمل الاستجابة التاريخ المجمَّع وتُضمّن أحدث جلسة، فتكفي الحالةَ الشائعة طلبٌ واحد بدل طلبين:

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "firstSeenAt": "2026-05-02T10:11:12Z",
  "lastSeenAt": "2026-07-25T08:00:00Z",
  "visits": 42,
  "incognitoVisits": 3,
  "uniqueIps": 5,
  "uniqueCountries": 2,
  "browsers": ["Chrome"],
  "os": ["macOS"],
  "devices": ["desktop"],
  "risk": {
    "maxRiskScore": 63,
    "avgBotScore": 12.5,
    "botSessions": 7,
    "lastDecision": "real"
  },
  "network": {
    "vpnSeen": false,
    "proxySeen": false,
    "torSeen": false,
    "datacenterSeen": true,
    "lastIsp": "Deutsche Telekom"
  },
  "lastSession": {
    "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
    "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
    "accountId": "user_8842",
    "timestamp": "2026-07-25T08:00:00Z",
    "tag": "checkout",
    "url": "https://shop.example.com/checkout",
    "ip": "203.0.113.42",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "browser": { "name": "Chrome", "version": "126.0" },
    "os": { "name": "macOS", "version": "14.5" },
    "device": "desktop",
    "geo": {
      "country": "DE",
      "city": "Berlin",
      "timezone": "Europe/Berlin",
      "isp": "Deutsche Telekom"
    },
    "network": {
      "vpn": false,
      "proxy": false,
      "tor": false,
      "datacenter": false,
      "asn": 3320
    },
    "bot": { "result": "human", "score": 4.5, "antidetectScore": 2.1 },
    "identification": {
      "confidence": 0.97,
      "incognito": false,
      "matchType": "exact",
      "matchConfidence": 0.99
    },
    "decision": { "action": "real", "riskScore": 12 }
  },
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

الزائر الذي لا توجد له بيانات داخل نافذة الاحتفاظ يعيد 404 not_found مع الرسالة visitor not found in the retention window — وهذا ليس خطأً في تكاملك، بل يعني أن الزائر جديد أو أن بياناته تجاوزت مدّة الاحتفاظ.

حقول الحكم

تحمل الجلسة حكمَين اثنين، وهما يجيبان عن سؤالين مختلفين — هل كان العميل مؤتمتًا، وإلامَ انتهى محرّك المخاطر إجمالًا:

يقع كل من bot.score وdecision.riskScore على المقياس 0..100. واعتبارًا من Business وما فوقها، يحوّلهما guidance إلى توصية لكل سيناريو على السلّم allow ← challenge ← review ← deny — راجع Guidance لمعرفة معنى كل درجة.

سرد جلسات زائر

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/sessions?limit=100&minRiskScore=50"

تعود الجلسات بدءًا من الأحدث:

{
  "items": [
    {
      "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
      "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
      "timestamp": "2026-07-25T08:00:00Z"
    }
  ],
  "nextCursor": "MTcyMTg5NDQwMDAwMDphYmMxMjM",
  "hasMore": true,
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

التقسيم إلى صفحات

التصفّح قائم على المؤشّر. ولا يوجد معامِل page ولا offset: مرِّر قيمة nextCursor التي استلمتها بوصفها cursor، وواصِل ما دامت hasMore صحيحة.

async function allSessions(visitorId: string, secretKey: string) {
  const sessions = []
  let cursor: string | undefined

  do {
    const url = new URL(`https://api.tracio.ai/v1/visitors/${visitorId}/sessions`)
    url.searchParams.set("limit", "500")
    if (cursor) url.searchParams.set("cursor", cursor)

    const res = await fetch(url, { headers: { Authorization: `Bearer ${secretKey}` } })
    if (!res.ok) throw new Error(`Server API: ${res.status}`)

    const page = await res.json()
    sessions.push(...page.items)
    cursor = page.nextCursor
  } while (cursor)

  return sessions
}

تعامَل مع المؤشّر بوصفه معتمًا — فمحتواه تفصيل تنفيذي وقد يتغيّر. والمؤشّر الذي جرى تعديله يُرفض بالرمز 400 invalid_request وبالرسالة malformed cursor.

جلب جلسة واحدة

الجلسة الأحدث:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/sessions/latest"

يعيد هذا كائن جلسة مجرّدًا — لا مصفوفة ولا مغلَّفًا داخل غلاف. والزائر الذي لا جلسات له في النافذة يعيد 404 not_found مع no sessions for this visitor in the retention window.

أو عبر requestId، وهو المعرّف الذي يظهر أيضًا في حمولة الـ webhook:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/sessions/9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31?visitorId=X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

visitorId اختياري هنا، لكن تمريره حين تعرفه يجعل البحث أسرع بوضوح.

Velocity

يجيب velocity عن سؤال «كم كان نشاط هذا الزائر مؤخرًا» — وهو شكل حشو بيانات الاعتماد واختبار البطاقات والتسجيلات بالجملة.

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/velocity?window=1h"

يقبل window القيم 1h أو 24h أو 7d وقيمته الافتراضية 24h. وأي قيمة أخرى تُرفض بالرمز 400 invalid_request وبالرسالة window must be one of: 1h, 24h, 7d.

{
  "window": "1h",
  "events": 37,
  "uniqueIps": 9,
  "uniqueCountries": 3,
  "uniqueAccounts": 12,
  "botEvents": 4,
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-07-25T11:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

يعدّ uniqueAccounts قيم linkedId المختلفة التي أرسلتها لهذا الجهاز — راجع ربط الحسابات. وbotEvents متاح في Business وما فوقها.

أعراف الاستجابة

الحقل الغائب يعني «لا بيانات»، لا صفرًا أبدًا. فالحقول التي لا قيمة لها تُحذف بالكامل بدل أن تُرسَل بالقيمة 0 أو "" أو null: فالزائر الجديد تمامًا لا matchConfidence له، والزيارة النظيفة لا antidetectScore لها ولا suspectScore. والاستثناء الوحيد المقصود هو bot.score، فهو حاضر دائمًا حتى حين يساوي صفرًا. اقرأ الحقول بحذر.

تعتمد الحمولة على خطتك. كل خطة فيها وصول إلى API تحصل على الجلسة الأساسية — المعرّفات، والطابع الزمني، وعنوان URL، وعنوان IP، ووكيل المستخدم، والمتصفح، ونظام التشغيل، والجهاز، والموقع الجغرافي، والشبكة، والبوت، والتعرّف، والحكم. وتضيف Pro الحقول identification.matchType وidentification.matchConfidence وbot.antidetectScore. وتضيف Business وEnterprise الحقول geo.isp وnetwork.asn وdecision.suspectScore وidentification.driftScore وreasons وbehavior وguidance وdeviceInfo وحقول مستوى الشخص (personId وreputation وlinkedAccountsCount وlinkedVisitorsCount). وغياب حقل خاص بـ Business في خطة Pro ليس خطأً.

لا تُعاد أبدًا التفاصيل الداخلية على مستوى الإشارات، في أي خطة: فأسماء الإشارات المفردة وأوزانها والعتبات الكامنة خلف الحكم وقيم الإشارات الخام وتفصيل الدرجات تبقى لدينا. فالدرجة التي يمكن ردّها بالهندسة العكسية إلى مدخلاتها تكفّ عن كونها دفاعًا مفيدًا.

الأخطاء

يستخدم كل إخفاق مغلَّفًا واحدًا:

{
  "error": {
    "code": "unauthorized",
    "message": "missing Authorization: Bearer <secret key>",
    "requestId": "8f14e45fceea167a5a36dedd"
  }
}

requestId هذا ليس معرّف الزيارة. فقيمتان مختلفتان تتشاركان الاسم نفسه: داخل حمولة الجلسة يكون requestId هو UUID الزيارة، وهو نفسه الذي يسلّمه الـ webhook؛ أما داخل مغلَّف الخطأ فهو معرّف تتبّع من 24 حرفًا يُسكّ لكل استدعاء HTTP. ويعود معرّف التتبّع أيضًا في ترويسة X-Request-Id مع كل استجابة، ناجحة كانت أم لا. أدرِجه حين تتواصل مع الدعم — فهو الطريقة التي نعثر بها على استدعائك بالضبط.

تجري الفحوصات بترتيب ثابت — المفتاح، ثم الخطة، ثم الحدود — فالطلب بمفتاح خاطئ يُبلِّغ عن المفتاح أولًا دائمًا، لا عن مشكلة في الحصة.

تُقرأ حالتا 401 بصيغتين مختلفتين عن قصد: missing Authorization: Bearer <secret key> تعني أن الترويسة لم تصل إطلاقًا، بينما invalid or revoked API key تعني أنها وصلت ولم تطابق. أما 402 فتحمل Data API requires the Pro plan or higher.

حدود المعدل والحصص

تحمل كل استجابة مُصادَق عليها وضعك الحالي:

• تُسمح الدفعات القصيرة: فحدّ الطلبات في الثانية هو دلو رموز (token bucket) يتحمّل حتى ثلاثة أضعاف المعدل المستدام قبل أن يبدأ الرفض.
• الطلب المرفوض لتجاوزه معدّل الطلبات في الثانية لا يستهلك الحصة اليومية، فلا يمكن لدفعة واحدة أن تلتهم ميزانية اليوم.
• تُحتسب حدود Server API بمعزل عن حركة التعرّف. فقراءة تاريخك الخاص لا تنفق أبدًا عمليات التعرّف التي تدفع مقابلها.

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

• Webhooks — استقبل كل عملية تعرّف لحظة وقوعها
• ربط الحسابات — أرفِق معرّف حسابك الخاص بجهاز
• كشف البوتات — كيف يُنتَج الحكم بشأن البوت
• الخصوصية واللائحة العامة لحماية البيانات (GDPR) — التعامل مع طلبات أصحاب البيانات