واجهة API لاستيعاب الأحداث - مراقبة غير مالية

الأحداث المعاملات هي الأموال. الأحداث هي كل ما تعرفه منصتك غير ذلك: تسجيل الدخول الذي سبق عملية السحب، واليد التي نقلت الرقائق بين حسابين، والمكافأة التي طُالب بها مرتين، وعملية ردّ المبلغ التي وصلت بعد أسبوع. تستخدم الأحداث غلافاً واحداً لكل فئة، وتتسم بخاصية idempotency بحكم التصميم، ويقيّمها محرك القواعد نفسه الذي يحتسب درجات معاملاتك.

استيعاب الأحداث اختياري. فعّله من Transactions → Settings → Event monitoring. قبل تفعيله لا يتغير شيء: تستمر قواعد المعاملات الحالية في العمل على المعاملات فقط، ولا يمكن إنشاء قاعدة حدث عن طريق الخطأ، لأن القاعدة تنطبق على المعاملات ما لم تُضمّن الأحداث صراحةً.قبل تفعيله، تُرجع كل مسارات الكتابة - POST /v3/events/ وPOST /v3/events/batch/ وPOST /v3/events/sdk-token/ ومسار الجهاز /v1/events/ - الاستجابة 403 مع {"code": "event_monitoring_disabled"}، ولا يُخزَّن شيء ولا يُثرى ولا يُقيَّم. عمليات القراءة لا تتأثر.

نقاط النهاية

نقطة النهاية	المصادقة	الاستخدام
`POST /v3/events/`	مفتاح API	حدث واحد من الخادم الخلفي
`POST /v3/events/batch/`	مفتاح API	حتى 500 حدث في طلب واحد
`POST /v3/events/sdk-token/`	مفتاح API	إصدار بيانات اعتماد محدودة النطاق للجهاز
`POST /v1/events/`	`X-Monitoring-Token`	حدث واحد من SDK الجهاز
`POST /v1/events/batch/`	`X-Monitoring-Token`	دفعة من مخزن SDK المؤقت بعد تفريغه
`GET /v3/events/`	مفتاح API	عرض الأحداث وتصفيتها
`GET /v3/events/{event_uuid}/`	مفتاح API	حدث واحد مع أدلة القاعدة
`GET /v3/events/subjects/{vendor_data}/`	مفتاح API	الخط الزمني لموضوع واحد (انظر `entity_type` أدناه)
`GET /v3/events/enrichment-metrics/`	مفتاح API	حالة ذاكرة التخزين المؤقت لإثراء IP

مسار /v3/ هو مسار الخادم، ويستخدم المصادقة x-api-key نفسها المستخدمة في بقية واجهة المعاملات البرمجية. مسار /v1/events/ هو مسار الجهاز، انظر إرسال أحداث SDK.

الغلاف

curl -X POST https://verification.didit.me/v3/events/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "login-2026-08-31-000001",
    "event_category": "auth",
    "action_type": "login",
    "occurred_at": "2026-08-31T20:40:31.123Z",
    "time_zone": "UTC",
    "subject": {
      "entity_type": "individual",
      "vendor_data": "user_391"
    },
    "session": { "session_id": "web-session-abc", "sequence": 142 },
    "device_context": {
      "fingerprint": "didit-fp-v2:a8c1",
      "network_context": { "ip_address": "203.0.113.42" }
    },
    "payload": { "method": "password" }
  }'

{
  "event_uuid": "0f2b...",
  "event_id": "login-2026-08-31-000001",
  "status": "ACCEPTED",
  "score": 0,
  "rules_evaluated_count": 6,
  "rules_matched_count": 0,
  "correlation_pending": false,
  "retention_class": "standard",
  "expires_at": "2026-09-30T20:40:31.123Z",
  "idempotent_replay": false,
  "rule_matches": []
}

الحقل	مطلوب	ملاحظات
`event_id`	نعم	معرّفك الخاص، فريد لكل تطبيق. وهو مفتاح idempotency.
`event_category`	نعم	واحدة من الفئات العشر الموضحة أدناه.
`action_type`	نعم	سلسلة نصية مفتوحة، بحد أقصى 128 حرفاً.
`occurred_at`	نعم	وقت وقوع الحدث من جهتك. حتى 7 أيام في الماضي، و5 دقائق في المستقبل.
`subject.vendor_data`	نعم	معرّف المستخدم لديك. يُربط بالمستخدم نفسه الذي تُربط به المعاملة.
`subject.entity_type`	لا	`individual` (الافتراضي) أو `company`.
`business.vendor_data`	لا	الشركة التي ينتمي إليها الحدث.
`session`	لا	`session_id` و`sequence` و`page_url` و`referrer`.
`device_context`	لا	`fingerprint` و`persistent_device_id` و`bot_score` و`network_context.ip_address`.
`transaction_context`	لا	`amount` و`currency` و`direction` و`payment_reference_id`.
`payload`	لا	الحقول الخاصة بمجال الفئة. حتى 16 كيلوبايت.
`custom_values`	لا	حتى 100 مفتاح ذي قيمة مفردة، ويمكن الوصول إليها من القواعد بالصيغة `custom_values.<key>`.

الفئات

عشر فئات أساسية، لكل منها تحقق قائم على الأنواع وحقول القواعد المُدارة.

الفئة	الإجراءات المعتادة
`auth`	`signup`، `login`، `login_failed`، `logout`، `password_forgot`، `password_reset`، `mfa_reset`، `mfa_challenge`
`session`	`session_started`، `session_ended`، `page_view`، `sdk_loaded`، `device_seen`، `bot_signal_observed`، `sdk_heartbeat`
`gameplay`	`round_started`، `round_completed`، `bet_placed`، `bet_settled`، `cashout`، `limit_change`، `p2p_settlement`
`bonus`	`bonus_claimed`، `bonus_wagered`، `bonus_released`، `promotion_viewed`
`affiliate`	`affiliate_attributed`، `referral_clicked`، `campaign_joined`، `commission_event`
`payment`	`deposit_initiated`، `deposit_completed`، `withdrawal_requested`، `withdrawal_completed`، `withdrawal_address_changed`، `payment_instrument_seen`
`dispute`	`chargeback_opened`، `chargeback_won`، `chargeback_lost`، `refund_issued`، `payment_dispute_updated`
`security`	`login_attempt`، `login_succeeded`، `login_failed`، `password_changed`، `mfa_changed`، `credential_reset`، `country_changed`، `device_changed`، `account_locked`
`responsible_gambling`	`self_exclusion_checked`، `self_exclusion_match`، `re_registration_attempt`، `limit_breach_attempt`، `registry_status_changed`
`custom`	أي إجراء تحدده

auth هي الفئة الواسعة في المنتج، وsecurity هي المجموعة الفرعية عالية المخاطر ذات دورة الحياة المرتبة التي تقرأها قواعد الاستيلاء على الحساب.

مفاتيح الحمولة المطلوبة

بعض الإجراءات لا يمكن ربطها دون مفاتيح محددة، لذلك يرفض التحقق هذه الأحداث بدلاً من تخزين أدلة لا يستطيع أحد ربطها.

الإجراء	المطلوب
`gameplay.p2p_settlement`	`game_id`، `counterparty_vendor_data`، `stake_amount`، `net_result_amount`، `role`، وواحد من `hand_id` / `round_id` / `match_id`
`gameplay.bet_placed`، `gameplay.bet_settled`	`game_id`
`payment.deposit_*`، `payment.withdrawal_completed`، `payment.withdrawal_requested`، `payment.deposit_initiated`	`payment_reference_id`، `amount`، `currency`، `payment_method`، `status`
`payment.withdrawal_address_changed`	`withdrawal_address_hash`
`dispute.chargeback_*`	`payment_reference_id`، وواحد من `dispute_id` / `chargeback_id`
`security.*_changed`	`changed_field`؛ وتحتاج تغييرات الحساب أو التحكم في الصرف أيضاً إلى `previous_reference_hash` أو `new_reference_hash`
`session.bot_signal_observed`	`telemetry_schema_version`، إضافة إلى `bot_score` أو مقياس تليمتري واحد على الأقل
`responsible_gambling.self_exclusion_match`	`registry_source`، `exclusion_status`، `identity_match_ref`

أرسل المراجع والتجزئات، ولا ترسل أبداً أسراراً خام. تُخزَّن أدوات الدفع ووجهات السحب وتغييرات التحكم في الحساب كمرجع مُجزّأ تُرسله أنت. لا ترسل أبداً رقم بطاقة، ولا عنوان سحب كاملاً، ولا تجزئة كلمة مرور، ولا سر MFA.

مثال: تسوية P2P

{
  "event_id": "p2p-hand-8842-user-391",
  "event_category": "gameplay",
  "action_type": "p2p_settlement",
  "occurred_at": "2026-08-31T12:34:17.392Z",
  "subject": { "vendor_data": "user_391" },
  "payload": {
    "game_id": "poker_holdem",
    "table_id": "table_17",
    "hand_id": "hand_8842",
    "role": "winner",
    "counterparty_vendor_data": "user_812",
    "stake_amount": "250.00",
    "net_result_amount": "240.50",
    "effective_margin": "0.038",
    "operator_ledger_ref": "ledger_998123"
  }
}

مثال: الاعتراض على عملية دفع

{
  "event_id": "chargeback-cb_921-opened",
  "event_category": "dispute",
  "action_type": "chargeback_opened",
  "occurred_at": "2026-08-31T09:22:05.000Z",
  "subject": { "vendor_data": "user_391" },
  "transaction_context": {
    "amount": "1000.00",
    "currency": "EUR",
    "payment_reference_id": "dep_735"
  },
  "payload": {
    "dispute_id": "disp_498",
    "chargeback_id": "cb_921",
    "reason_code": "fraudulent",
    "liability_shift": false
  }
}

دورات حياة النزاعات لا تقبل إلا الإضافة؛ التصحيح يكون حدث dispute جديداً، ولا يُعدَّل الحدث الأول أبداً.

idempotency

event_id فريد لكل تطبيق، وهو عقد idempotency كاملاً.

نفس event_id ونفس المحتوى يُعيد 200 مع "idempotent_replay": true والحدث المخزَّن أصلاً. أعد المحاولة بقدر ما تشاء.
نفس event_id ومحتوى مختلف يُعيد 409. أعدتَ استخدام المعرّف عن طريق الخطأ.

الدفعات

POST /v3/events/batch/ يقبل حتى 500 حدث. تنجح الدفعة جزئياً بحكم التصميم: لا يجب أبداً أن يُسقط عرض صفحة واحد مشوّه حدث النزاع المجاور له.

{
  "accepted_count": 2,
  "replayed_count": 0,
  "rejected_count": 1,
  "results": [
    { "index": 0, "outcome": "rejected", "errors": { "occurred_at": ["This field is required."] } },
    { "index": 1, "outcome": "accepted", "event_uuid": "…", "status": "ACCEPTED" },
    { "index": 2, "outcome": "accepted", "event_uuid": "…", "status": "IN_REVIEW" }
  ]
}

تكون الاستجابة 207 Multi-Status عند رفض أي حدث، و201 Created عند نجاح الكل.

الحالات

الحالة	المعنى
`ACCEPTED`	مخزَّن. لم تغيّر أي قاعدة وضعه (هذه هي الإجابة المعتادة لمعظم الأحداث).
`APPROVED`	شغّلتها قاعدة، وبقيت الدرجة تحت حد المراجعة لديك.
`IN_REVIEW`	دفعته قاعدة فوق حد المراجعة، أو عُيّنت الحالة مباشرة.
`DECLINED`	رفضته قاعدة.

correlation_pending: true يعني أن قاعدة عبر الكيانات ما زال يجب أن تعمل؛ تُحسم خلال دقائق، وتُحدَّث حالة الحدث ودرجته في مكانهما. راجع القواعد غير المتزامنة.

الاحتفاظ بالبيانات

تفوق الأحداث المعاملات بكثير في الحجم، لذلك يُصنَّف كل حدث في فئة احتفاظ عند وصوله.

الفئة	الاحتفاظ الساخن الافتراضي	ما يندرج هنا
`low_value`	14 يوماً	مشاهدات الصفحات، ونبضات الحياة، وإشارات رصد الأجهزة، وبيانات القياس عن بُعد الخاصة بالروبوتات، ومشاهدات العروض الترويجية
`standard`	30 يوماً	المصادقة والجلسات واللعب والمكافآت والشركاء والمخصص
`risk_relevant`	90 يوماً	أحداث الأمان والمقامرة المسؤولة، وأي حدث طابقته قاعدة
`monetary_or_compliance`	مدة احتفاظ المعاملات	أحداث الدفع والنزاعات

تترتب على الجدول قاعدتان:

الحدث الذي تطابقه قاعدة يُعدّ دليلاً، لذلك يُرقّى تلقائياً إلى risk_relevant.
تحتفظ أحداث الدفع والنزاعات بمدة احتفاظ المعاملات. لا تنتهي صلاحيتها أبداً وفق جدول الأحداث، ولا يمكن لتجاوزات الفئات أن تقصّرها.

يمكنك تجاوز الفئات الثلاث القابلة للانتهاء لكل تطبيق من Transactions → Settings → Event monitoring (بين 1-730 يوماً لكل منها).

إثراء عنوان IP

تحمل الأحداث إثراء IP نفسه الذي تحمله المعاملات، أي الدولة وASN وعلامات VPN/الوكيل وعلامات مراكز البيانات، ويُحسم الإثراء لكل عنوان IP فريد، لا لكل حدث. الجلسة التي تُطلق 200 عرض صفحة من عنوان واحد يُحدَّد إثراء ذلك العنوان مرة واحدة فقط. القياسات عن بُعد منخفضة القيمة تقرأ الإثراء فقط إذا كان حدث آخر قد حلّ ذلك العنوان بالفعل، ولا تُطلق بحثاً خاصاً بها أبداً. GET /v3/events/enrichment-metrics/ يُبلغ عن النتيجة، وتعرض وحدة التحكم الأرقام نفسها فوق قائمة الأحداث:

{
  "events_ingested": 128450,
  "enrichment_lookups": 41230,
  "enrichment_cache_hits": 40118,
  "enrichment_provider_calls": 1112,
  "enrichment_skipped_low_value": 74320,
  "unique_ips_seen": 1112,
  "cache_hit_rate": 0.973,
  "unique_ip_ratio": 0.0087,
  "provider_calls_per_1k_events": 8.65,
  "period_days": 30
}

قراءة الأحداث واسترجاعها

curl "https://verification.didit.me/v3/events/?event_category=payment&event_category=dispute&matched_only=true" \
  -H "x-api-key: YOUR_API_KEY"

التصفية: event_category، action_type، status، retention_class، subject_vendor_data، business_vendor_data، session_id، device_fingerprint، ip_address، game_id، round_id، affiliate_code، payment_reference_id، counterparty_vendor_data، matched_only، occurred_from، occurred_to، search. تُكرَّر المعاملات التي تقبل أكثر من قيمة لكل قيمة، مثل ?status=A&status=B.

الجدول الزمني لموضوع واحد

curl "https://verification.didit.me/v3/events/subjects/acct_9931/?entity_type=company" \
  -H "x-api-key: YOUR_API_KEY"

القيمة vendor_data فريدة ضمن نوع الكيان فقط، فقد يشير المعرّف نفسه إلى مستخدم وإلى شركة، ويتعامل Didit معهما كموضوعين مختلفين. يحدد entity_type الكيان المطلوب: individual (الافتراضي) أو company. إذا أغفلته عند استخدام معرّف شركة، فسيُعاد الجدول الزمني للفرد لا الاثنين معاً. تنطبق عليه المرشحات نفسها الواردة في القائمة. يضيف GET /v3/events/{event_uuid}/ payload، وسياق الجهاز، وإثراء عنوان IP، وإشارات المخاطر المخزنة مؤقتاً الخاصة بالموضوع، وكل تطابق مع القواعد مع أدلته، بما في ذلك ما إذا كان كل حقل متطابق مشتقاً من الخادم، أو مشتقاً من SDK، أو مقدَّماً من العميل. يحذف DELETE /v3/events/{event_uuid}/delete/ حدثاً واحداً. بعد الحذف لا يُعاد هذا الحدث في أي عملية قراءة، والحذف لا رجعة فيه.

القواعد على الأحداث

قواعد السرعة والنسبة والتسلسل والارتباط على بيانات الأحداث.

إرسال الأحداث من SDK

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

البدء

الميزات

المرجع

Console

واجهة API لاستيعاب الأحداث - مراقبة غير مالية

نقاط النهاية

الغلاف

الفئات

مفاتيح الحمولة المطلوبة

مثال: تسوية P2P

مثال: الاعتراض على عملية دفع

idempotency

الدفعات

الحالات

الاحتفاظ بالبيانات

إثراء عنوان IP

قراءة الأحداث واسترجاعها

الجدول الزمني لموضوع واحد

التالي

القواعد على الأحداث

إرسال الأحداث من SDK

​نقاط النهاية

​الغلاف

​الفئات

​مفاتيح الحمولة المطلوبة

​مثال: تسوية P2P

​مثال: الاعتراض على عملية دفع

​idempotency

​الدفعات

​الحالات

​الاحتفاظ بالبيانات

​إثراء عنوان IP

​قراءة الأحداث واسترجاعها

​الجدول الزمني لموضوع واحد

​التالي

القواعد على الأحداث

إرسال الأحداث من SDK

نقاط النهاية

الغلاف

الفئات

مفاتيح الحمولة المطلوبة

مثال: تسوية P2P

مثال: الاعتراض على عملية دفع

idempotency

الدفعات

الحالات

الاحتفاظ بالبيانات

إثراء عنوان IP

قراءة الأحداث واسترجاعها

الجدول الزمني لموضوع واحد

التالي