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

مرجع واجهة الأحداث: أرسل عمليات الدخول والمدفوعات والتسجيل إلى نيزا، واقرأ قرار السماح أو المراجعة أو الحظر لكل حدث.

الأدلة مرجع 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.