مرجع API

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

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

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

نقاط النهاية

SDK@tracio/sdk

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

الطلب

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

الاستجابة

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

POST/webhook/tracio

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

الطلب

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

الاستجابة

{
  "requestId": "1710432000_abc123",
  "visitorId": "X7fh2Hg9LkMn3pQr",
  "bot": { "result": "human", "type": "", "score": 0.02 },
  "identification": { "confidence": 0.95, "visitType": "returning" },
  "network": { "vpn": false, "proxy": false, "tor": false, "datacenter": false },
  "decision": { "action": "allow", "riskScore": 4 }
}

POST/api/v1/workspaces/{workspaceId}/webhooks

سجّل نقطة نهاية webhook عبر واجهة برمجة إدارة مساحة العمل. تُصادَق باستخدام رمز JWT لجلسة لوحة التحكم (Clerk) وتُفحَص مقابل دورك في مساحة العمل. يُعاد سرّ التوقيع مرة واحدة عند الإنشاء.

الطلب

curl -X POST \
  https://app.tracio.ai/api/v1/workspaces/{workspaceId}/webhooks \
  -H "Authorization: Bearer <clerk-session-jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.com/webhook/tracio", "events": [] }'

الاستجابة

{
  "ok": true,
  "data": {
    "id": "wh_abc123",
    "url": "https://your-server.com/webhook/tracio",
    "events": [],
    "signingSecret": "f3a9…<hex>",
    "status": "active",
    "createdAt": "2024-03-12T16:00:00Z"
  }
}

GET/api/v1/workspaces/{workspaceId}/visitors/{visitorId}

ابحث في السجل المخزّن لزائر عبر واجهة برمجة إدارة مساحة العمل، مع المصادقة برمز JWT لجلسة لوحة التحكم (Clerk). يدعم طلبات حق الوصول بموجب GDPR.

الطلب

curl \
  https://app.tracio.ai/api/v1/workspaces/{workspaceId}/visitors/X7fh2Hg9LkMn3pQr \
  -H "Authorization: Bearer <clerk-session-jwt>"

الاستجابة

{
  "ok": true,
  "data": {
    "visitorId": "X7fh2Hg9LkMn3pQr",
    "firstSeenAt": "2024-03-01T08:11:00Z",
    "lastSeenAt": "2024-03-16T14:22:01Z",
    "visits": 12
  }
}

المصادقة

يستخدم TRACIO ثلاث بيانات اعتماد، واحدة لكل سطح: مفتاح عام لـ SDK المتصفح، ورمز JWT لجلسة لوحة التحكم (Clerk) لواجهة برمجة إدارة مساحة العمل، وسرّ توقيع HMAC للتحقق من تسليمات الـ webhook. لا يوجد سرّ API مستقل.

# Client SDK — public key (safe to ship in the browser)
Tracio.init({ publicKey: '5ca175fc...' })
# Workspace management API — dashboard session (Clerk) JWT,
# additionally checked against your workspace role (RBAC)
Authorization: Bearer <clerk-session-jwt>
# Webhook verification — HMAC-SHA256 over "<t>.<rawBody>"
X-Tracio-Signature: t=<unix>,v1=<hmac_sha256_hex>

حدود المعدل

الحدود لكل مساحة عمل. تتضمن استجابات واجهة برمجة الإدارة ترويسات X-RateLimit-Limit وX-RateLimit-Remaining وRetry-After.

الخطة	التعريفات	أحداث الـ webhook	واجهة برمجة الإدارة	عمليات البحث عن الزوار
مجانية	100/day	100/day	50/day	100/day
احترافية	1,000/min	1,000/min	500/min	1,000/min
للمؤسسات	10,000/min	10,000/min	5,000/min	10,000/min

رموز الأخطاء

تعيد جميع الأخطاء نص JSON يتضمن الحقول code وmessage وdetails.

400طلب غير صالحنص طلب مشوّه أو حقول مطلوبة مفقودة.

401غير مصرّحبيانات اعتماد مفقودة أو غير صالحة — المفتاح العام (SDK)، أو رمز Clerk JWT (واجهة برمجة الإدارة)، أو توقيع الـ webhook.

403ممنوعدورك في مساحة العمل (RBAC) يفتقر إلى الإذن لهذه العملية.

404غير موجودمعرّف الزائر أو الـ webhook غير موجود في مساحة عملك.

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

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

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

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded",
    "details": "1000 requests per minute limit reached for this workspace",
    "retryAfter": 12
  }
}

ابدأ البناء

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

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