مرجع API

واجهة برمجة مكافحة الاحتيال

SDK للمتصفح للتعريف، وwebhooks موقّعة للأحداث في الوقت الفعلي، وServer API للقراءة فقط للاطّلاع على السجل. كل ما تحتاجه لإيقاف الاحتيال على مستوى الجهاز.

احصل على مفتاح API ساحة تجربة API

نقاط النهاية

SDK@tracio/sdk

عرّف زائرًا في المتصفح باستخدام الـ SDK الخاص بالعميل. يعيد معرّف زائر مستقرًا وحكمًا على الروبوتات دون أي جولة إلى الخادم. المفتاح العام آمن للشحن ضمن الكود على جانب العميل.

الطلب

import { Tracio } from '@tracio/sdk'
const tracio = Tracio.init({ publicKey: '5ca175fc...' })
const result = await tracio.getResult()

الاستجابة

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "bot": {
    "detected": false,
    "confidence": 2,
    "reasons": []
  }
}

POST/webhook/tracio

يسلّم TRACIO حدثًا موقّعًا إلى نقطة النهاية لديك عند كل عملية تعريف. تحقّق من ترويسة X-Tracio-Signature، ثم تصرّف بناءً على حمولة JSON المسطّحة. هذا هو سطح الدفع: لا حاجة إلى الاستقصاء. وإذا احتجت فعلًا إلى قراءة زيارة بعد وقوعها، فإن الـ Server API يجيب عبر requestId.

الطلب

POST /webhook/tracio HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Tracio-Payload-Version: 2
X-Tracio-Event-Type: identification
X-Tracio-Signature: t=1710432000,v1=5257a869e7ecebed...

الاستجابة

{
  "version": 2,
  "event": "identification",
  "eventId": "9c1f4b2e-7d3a-4f18-8b6c-2e5a71d0c4f9:primary",
  "requestId": "9c1f4b2e-7d3a-4f18-8b6c-2e5a71d0c4f9",
  "phase": "primary",
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "timestamp": "2026-03-12T16:00:00Z",
  "bot": { "result": "human", "score": 2 },
  "identification": { "confidence": 0.95, "incognito": false },
  "network": { "vpn": false, "proxy": false, "tor": false, "datacenter": false },
  "decision": { "action": "real", "riskScore": 4 }
}

GET/.well-known/webhook-keys

اجلب مفاتيح Ed25519 العامة للمنصة المستخدَمة للتحقق من تسليمات الـ webhook. لا يحتاج هذا المسار إلى مصادقة ويُخزَّن مؤقتًا لمدة خمس دقائق. ويخبرك الحقل kid في ترويسة التوقيع بالمفتاح الذي ينبغي استخدامه.

الطلب

curl https://api.tracio.ai/.well-known/webhook-keys

الاستجابة

{
  "keys": [
    {
      "kid": "k1",
      "alg": "Ed25519",
      "publicKey": "MCowBQYDK2VwAyEA9tR2v1kQ..."
    }
  ]
}

GET/v1/visitors/{visitorId}

اقرأ سجل زائر من الـ Server API بمفتاحك السري. متاح ابتداءً من خطة Pro. وتُقيَّد النافذة وفق خطتك، ويُبلَّغ عن النافذة التي حصلت عليها فعلًا في meta. يدعم طلبات حق الوصول بموجب GDPR.

الطلب

# Server API — available on the Pro plan and above
curl "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX"

الاستجابة

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "firstSeenAt": "2026-03-01T08:11:00Z",
  "lastSeenAt": "2026-03-16T14:22:01Z",
  "visits": 12,
  "incognitoVisits": 1,
  "uniqueIps": 4,
  "uniqueCountries": 2,
  "risk": { "maxRiskScore": 63, "lastDecision": "real" },
  "network": {
    "vpnSeen": false,
    "proxySeen": false,
    "torSeen": false,
    "datacenterSeen": true
  },
  "meta": {
    "plan": "pro",
    "retentionDays": 30,
    "from": "2026-02-14T00:00:00Z",
    "to": "2026-03-16T14:30:00Z"
  }
}

المصادقة

يستخدم TRACIO ثلاث بيانات اعتماد، واحدة لكل سطح: مفتاح عام لـ SDK المتصفح، ومفتاح سري (tracio_sk_…) يُرسَل بصيغة Authorization: Bearer لـ Server API، وسرّ توقيع HMAC للتحقق من تسليمات الـ webhook. يُنشأ المفتاح السري في لوحة التحكم، ويُعرض مرة واحدة، ويجب ألا يصل إلى متصفح أبدًا — فالـ Server API لا يُعيد ترويسات CORS عن قصد.

# Client SDK — public key (safe to ship in the browser)
Tracio.init({ publicKey: '5ca175fc...' })
# Server API — secret key, created in the dashboard and shown once
Authorization: Bearer tracio_sk_XXXX...XXXX
# Webhook verification — HMAC-SHA256 over "<t>.<rawBody>"
X-Tracio-Signature: t=<unix>,v1=<hmac_sha256_hex>

حدود المعدل

الحدود لكل مساحة عمل. وتُحتسب استدعاءات Server API بمعزل عن عمليات التعريف، فقراءة سجلك الخاص لا تستهلك أبدًا الحصة التي تدفع مقابلها. وتحمل كل استجابة X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset، إضافةً إلى Retry-After عند الخطأ 429. والـ Server API ليس جزءًا من خطة Free.

الخطة	معدل Server API	Server API يوميًا	نقاط نهاية webhook	نافذة الاستعلام
مجانية	غير مشمول	غير مشمول	0	7 days
احترافية	10 req/s	10,000	5	30 days
للأعمال	50 req/s	100,000	20	90 days
للمؤسسات	200 req/s	غير محدود	100	365 days

رموز الأخطاء

تُعيد كل الأخطاء المغلّف نفسه: كائن error يحمل رمز code نصيًا، ورسالة message مقروءة للبشر، وrequestId للاستدعاء الفاشل.

400طلب غير صالحمعاملات استعلام مشوّهة، أو نافذة غير مدعومة، أو معرّف ليس معرّف زائر صالحًا.

401غير مصرّحبيانات اعتماد مفقودة أو غير صالحة — المفتاح العام (SDK)، أو المفتاح السري (Server API)، أو توقيع الـ webhook.

402يلزم الترقيةخطتك لا تشمل الوصول إلى Server API. يبدأ من خطة Pro.

404غير موجودلا يوجد زائر أو جلسة بهذا المعرّف داخل نافذة الاستعلام الخاصة بخطتك.

405الطريقة غير مسموح بهاالـ Server API للقراءة فقط. وكل مسار يستجيب لـ GET وحده لا غير.

429تجاوز حد المعدلطلبات كثيرة جدًا في الثانية، أو استُنفدت الحصة اليومية. تحقّق من ترويسة Retry-After وحدود خطتك.

500خطأ داخليخطأ في الخادم. أعد المحاولة مع تراجع أُسّي. وإذا استمر، تواصل مع الدعم مع ذكر requestId.

503الخدمة غير متاحةالـ API غير قادر مؤقتًا على الاستجابة. أعد المحاولة مع تراجع أُسّي.

تنسيق استجابة الخطأ

{
  "error": {
    "code": "rate_limited",
    "message": "too many requests",
    "requestId": "8f14e45fceea167a5a36dedd"
  }
}

ابدأ البناء

احصل على مفتاح API الخاص بك وأجرِ أول طلب تعريف في أقل من 5 دقائق.

احصل على مفتاح API وثائق API الكاملة