> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> أرسل الأنشطة غير المالية - تسجيلات الدخول، واللعب، والمكافآت، والمدفوعات، والنزاعات، وأمان الحسابات - إلى المحرك نفسه الذي يقيّم معاملاتك.

الأحداث

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

تستخدم الأحداث غلافاً واحداً لكل فئة، وتتسم بخاصية idempotency بحكم التصميم، ويقيّمها [محرك القواعد نفسه](https://docs.didit.me/ar/transaction-monitoring/event-rules.md) الذي يحتسب درجات [معاملاتك](https://docs.didit.me/ar/transaction-monitoring/transactions.md).

> [!NOTE]
>
> استيعاب الأحداث اختياري. فعّله من **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](https://docs.didit.me/ar/transaction-monitoring/sdk-event-submission.md).

## الغلاف

```bash theme={null}
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" }
  }'
```

```json theme={null}
{
  "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>`. |

## الفئات

عشر فئات أساسية، لكل منها تحقق قائم على الأنواع و[حقول القواعد المُدارة](https://docs.didit.me/ar/transaction-monitoring/event-rules.md#حقول-الأحداث).

| الفئة | الإجراءات المعتادة |
| - | - |
| `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` |

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

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

```json theme={null}
{
  "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"
  }
}
```

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

```json theme={null}
{
  "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 حدث**. تنجح الدفعة جزئياً بحكم التصميم: لا يجب أبداً أن يُسقط عرض صفحة واحد مشوّه حدث النزاع المجاور له.

```json theme={null}
{
  "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` يعني أن قاعدة عبر الكيانات ما زال يجب أن تعمل؛ تُحسم خلال دقائق، وتُحدَّث حالة الحدث ودرجته في مكانهما. راجع [القواعد غير المتزامنة](https://docs.didit.me/ar/transaction-monitoring/event-rules.md#القواعد-الفورية-وغير-المتزامنة).

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

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

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

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

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

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

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

تحمل الأحداث [إثراء IP](https://docs.didit.me/ar/transaction-monitoring/ip-enrichment.md) نفسه الذي تحمله المعاملات، أي الدولة وASN وعلامات VPN/الوكيل وعلامات مراكز البيانات، ويُحسم الإثراء **لكل عنوان IP فريد، لا لكل حدث**. الجلسة التي تُطلق 200 عرض صفحة من عنوان واحد يُحدَّد إثراء ذلك العنوان مرة واحدة فقط.

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

`GET /v3/events/enrichment-metrics/` يُبلغ عن النتيجة، وتعرض وحدة التحكم الأرقام نفسها فوق قائمة الأحداث:

```json theme={null}
{
  "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
}
```

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

```bash theme={null}
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`.

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

```bash theme={null}
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/` حدثاً واحداً. بعد الحذف لا يُعاد هذا الحدث في أي عملية قراءة، والحذف لا رجعة فيه.

## التالي

> [card] [القواعد على الأحداث](https://docs.didit.me/ar/transaction-monitoring/event-rules.md)
>
> قواعد السرعة والنسبة والتسلسل والارتباط على بيانات الأحداث.

> [card] [إرسال الأحداث من SDK](https://docs.didit.me/ar/transaction-monitoring/sdk-event-submission.md)
>
> التقاط الأحداث مباشرةً من الجهاز باستخدام بيانات اعتماد محدودة النطاق.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.