واجهة الأحداث

أرسل أحداث المنتج واستعلم عنها لتقييم المخاطر.

الأدلة مرجع API أمثلة الكود أفضل الممارسات

واجهة الأحداث

إرسال متزامن أو غير متزامن، ثم قراءة السجل والإحصاءات باستخدام مفتاح API.

الطريقة	المسار	الاستخدام
POST	/api/v1/events	إرسال متزامن يعيد القرار والدرجة
POST	/api/v1/events/async	قبول الحدث في الطابور وإعادة jobId
GET	/api/v1/events	قائمة الأحداث مع المرشحات والترقيم
GET	/api/v1/events/:id	تفاصيل حدث واحد
GET	/api/v1/events/stats	عدادات مجمعة للأحداث والقرارات

الحقل	النوع	مطلوب	الوصف
eventName	string	نعم	اسم ثابت يصف الفعل مثل user.login
eventCategory	enum	نعم	مثل AUTHENTICATION أو TRANSACTION
customer	object	موصى به	المعرف الخارجي والبريد والبيانات الوصفية
device	object	لا	معرف الجهاز والبصمة
sessionId	string	موصى به	يربط النشاط داخل زيارة واحدة
metadata	object	لا	المبلغ والعملة وسمات المنتج
custom_fields	object	لا	حقول أعمال مخصصة بعمق وحجم محدودين

POST /api/v1/events

curl -X POST https://api.naiza.ai/api/v1/events \
  -H "x-api-key: naiza_api_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "eventName": "payment.completed",
    "eventCategory": "TRANSACTION",
    "customer": { "externalId": "user_123456" },
    "device": { "externalId": "device_abc123" },
    "sessionId": "session_xyz789",
    "metadata": { "amount": 250, "currency": "SAR" }
  }'

الاستجابة المتزامنة

{
  "eventId": "evt_ckm9876543210",
  "decision": "ALLOW",
  "score": 15,
  "rulesEvaluated": 5,
  "receivedAt": "2026-04-16T10:30:00.000Z",
  "processingTimeMs": 42.5
}

الإرسال غير المتزامن والبحث

يعيد المسار غير المتزامن 202 Accepted مع jobId. لمعالجة النتائج استخدم Webhook أو استعلامًا مضبوطًا.

تدعم القائمة مرشحات eventName وeventCategory وdecision وcustomer وdevice وcountry وfrom/to وsortBy/sortOrder.

تعيد الإحصاءات قيمًا مثل totalEvents وblockedEvents وeventsUnderReview وuniqueCustomers.