> ## 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.
# إنشاء حدث مراقبة - واجهة برمجة التطبيقات
> أرسل حدث تسجيل دخول أو لعب أو مكافأة أو دفع أو نزاع أو أمان من الخادم الخاص بك إلى Didit ليتم تخزينه وإثرائه وتقييمه بقواعدك.
موجّه إنشاء حدث المراقبة عبر API
نسخ الموجّه إلى الحافظة
\
\`Send one non-monetary monitoring event (login, session, gameplay, bonus, affiliate, payment, dispute, security, responsible gambling or custom) from my backend to Didit.
Endpoint:
POST https://verification.didit.me/v3/events/
Authentication:
Use the x-api-key header with my Didit API key, from my backend only. A scoped key needs transactions: write.
Goal:
\- Record what happened on my platform so Didit's event rules can score it alongside my transactions, and read the verdict from the response.
Request body (application/json):
\{
"event_id": "login-2026-10-17-000001", // required - my id, unique per application, the idempotency key (max 128)
"event_category": "auth", // required - auth, session, gameplay, bonus, affiliate, payment, dispute, security, responsible_gambling, custom
"action_type": "login", // required - what happened inside the category (max 128)
"occurred_at": "2026-10-17T09:15:02.481Z", // required - at most 7 days in the past, 5 minutes in the future
"subject": { "vendor_data": "user-42", "entity_type": "individual" }, // required - entity_type individual (default) or company
"session": { "session_id": "web-session-abc", "sequence": 142 },
"device_context": { "fingerprint": "didit-fp-v2:a8c1", "network_context": { "ip_address": "203.0.113.42" } },
"transaction_context": { "amount": "1000.00", "currency": "EUR", "payment_reference_id": "dep_735" },
"payload": { "method": "password" }, // category fields, max 16 KB
"custom_values": { "vip_tier": "gold" } // max 100 scalar keys
}
Behavior:
\- Validated, stored, IP-enriched and evaluated by the real-time event rules before the response returns. Cross-subject and long-window rules run asynchronously within minutes (correlation_pending: true).
\- Some actions require payload keys, for example gameplay.p2p_settlement (game_id, counterparty_vendor_data, stake_amount, net_result_amount, role, and one of hand_id, round_id, match_id), payment.deposit_completed (payment_reference_id, amount, currency, payment_method, status) and dispute.chargeback_opened (payment_reference_id and one of dispute_id, chargeback_id). transaction_context keys count towards these requirements.
\- Send hashes and references, never a card number, a full withdrawal address, a password hash or an MFA secret.
\- Idempotency: the same event_id with the same event_category, action_type, occurred_at, subject.vendor_data and payload returns 200 with idempotent_replay true and the stored event's result. Different values in those fields return 409; the other fields are not compared. Retry safely on timeouts.
\- The IP address used for enrichment and rules is device_context.network_context.ip_address as you send it.
\- In a sandbox application no rules run: status is ACCEPTED and rules_evaluated_count is 0.
\- The subject resolves to the user (or company) with that vendor_data; one is created when none exists.
\- Event ingestion is opt-in: until it is switched on in Transactions > Settings > Event monitoring, this call returns 403 with code event_monitoring_disabled and stores nothing.
Example call:
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-10-17-000001","event_category":"auth","action_type":"login","occurred_at":"2026-10-17T09:15:02.481Z","subject":{"vendor_data":"user-42"},"device_context":{"network_context":{"ip_address":"203.0.113.42"}},"payload":{"method":"password"}}'
What to read from the response:
\- event_uuid - Didit id of the stored event.
\- status - ACCEPTED (stored, no rule changed it), APPROVED, IN_REVIEW or DECLINED.
\- score, rules_evaluated_count, rules_matched_count, rule_matches[] (rule_id, library_key, mode, is_async).
\- correlation_pending - when true, read GET /v3/events/{event_uuid}/ later for the final status.
\- retention_class and expires_at (null for payment and dispute events).
\- idempotent_replay - true when the event was already stored.
Failure modes:
\- 400 - validation error keyed by field (missing field, occurred_at outside the window, payload over 16 KB, nested custom_values, missing required payload keys).
\- 401 - the API key has expired.
\- 403 - missing API key (a wrong, revoked or expired key gets 401), a scoped key without transactions: write, or code event_monitoring_disabled.
\- 409 - event_id reused with different content; use a new event_id.
\- 429 - more than 600 ingestion requests per minute for this API key (event and transaction ingestion share this budget, apart from the 300 of every other write); honor Retry-After.
Side effects: stores the event, may create the subject's user or company, and applies the actions of matched active rules (score, status, tags, notes, list entries, cases).
For the full integration shape, see /integration/integration-prompt.`
\
الصق في
> [!NOTE]
>
> استيعاب الأحداث اختياري. فعّله من **Transactions > Settings > Event monitoring** قبل إرسال أي حدث، وإلى ذلك الحين ترد نقطة النهاية هذه بالرمز `403` مع `"code": "event_monitoring_disabled"`.يشرح [استيعاب الأحداث](https://docs.didit.me/ar/transaction-monitoring/events.md) الإطار العام للحدث، والفئات العشر، ومفاتيح الحمولة المطلوبة، وفئات الاحتفاظ بالبيانات. ويوضح [القواعد المطبقة على الأحداث](https://docs.didit.me/ar/transaction-monitoring/event-rules.md) القواعد التي تُنفَّذ ضمن الطلب والقواعد التي تُنفَّذ بشكل غير متزامن. وإذا أردت إرسال الأحداث من المتصفح أو من التطبيق بدلاً من الخادم الخلفي، فاستخدم [إرسال الأحداث عبر SDK](https://docs.didit.me/ar/transaction-monitoring/sdk-event-submission.md).
## OpenAPI
````yaml ar/openapi-25.json POST /v3/events/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: API التحقق من الهوية. قم بالمصادقة باستخدام الرأس x-api-key.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/events/:
post:
tags:
- Monitoring Events
summary: إنشاء حدث مراقبة
description: >-
أرسل حدثاً واحداً غير مالي (تسجيل الدخول، الجلسة، أسلوب اللعب، المكافأة،
التسويق بالعمولة، الدفع، النزاع، الأمان، المقامرة المسؤولة، أو مخصص) من
الواجهة الخلفية الخاصة بك. يتم التحقق من صحة الحدث وفقاً لعقد فئته، ثم
يُخزّن، ويُثرى ببيانات عنوان IP مرة واحدة لكل عنوان عام فريد، وتُقيّمه
قواعد الأحداث في الوقت الفعلي الخاصة بك قبل إرجاع الاستجابة؛ تعمل
القواعد متعددة الموضوعات وتلك ذات النطاق الزمني الطويل بشكل غير متزامن
(`correlation_pending: true`)، وفي تطبيق البيئة التجريبية لا تعمل أي
قواعد. يمثل `event_id` مفتاح idempotency: يؤدي إرسال نفس `event_id` مع
نفس `event_category` و`action_type` و`occurred_at`
و`subject.vendor_data` و`payload` إلى إرجاع `200` مع `idempotent_replay:
true` والنتيجة المخزنة (لا تتم مقارنة حقول المغلف الأخرى)، بينما تؤدي
القيم المختلفة إلى إرجاع `409`. استيعاب الأحداث اختياري لكل تطبيق: حتى
يتم تفعيله، يُرجع هذا endpoint رمز `403` مع `code:
event_monitoring_disabled` ولا يخزن أي شيء. يحتاج مفتاح API ذو الصلاحيات
المحددة إلى `transactions: write`. راجع [استيعاب
الأحداث](https://docs.didit.me/ar/transaction-monitoring/events) و[قواعد
الأحداث](https://docs.didit.me/ar/transaction-monitoring/event-rules)؛
لإرسال الأحداث من متصفح أو تطبيق، استخدم [إرسال الأحداث عبر
SDK](https://docs.didit.me/ar/transaction-monitoring/sdk-event-submission).
operationId: create_monitoring_event
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MonitoringEventCreateRequest'
examples:
Login:
value:
event_id: login-2026-10-17-000001
event_category: auth
action_type: login
occurred_at: '2026-10-17T09:15:02.481Z'
time_zone: Europe/Madrid
subject:
vendor_data: user-42
entity_type: individual
session:
session_id: web-session-abc
sequence: 142
device_context:
fingerprint: fp-a8c1
network_context:
ip_address: 203.0.113.42
payload:
method: password
custom_values:
vip_tier: gold
Deposit completed:
value:
event_id: deposit-2026-10-17-000002
event_category: payment
action_type: deposit_completed
occurred_at: '2026-10-17T09:16:40Z'
subject:
vendor_data: user-42
transaction_context:
amount: '100.00'
currency: EUR
direction: inbound
payment_reference_id: dep_736
payload:
payment_method: card
status: completed
Chargeback opened:
value:
event_id: chargeback-2026-10-16-000318
event_category: dispute
action_type: chargeback_opened
occurred_at: '2026-10-16T14:02:11Z'
subject:
vendor_data: user-42
payload:
payment_reference_id: dep_735
chargeback_id: cb_5521
amount: '250.00'
currency: EUR
reason_code: fraud
responses:
'200':
description: >-
إعادة تشغيل idempotency: تم تخزين حدث يحمل `event_id` هذا والمحتوى
نفسه بالفعل. لم يتم تخزين أو تقييم أي شيء مرة أخرى؛ يصف نص الاستجابة
الحدث المخزّن.
content:
application/json:
schema:
$ref: '#/components/schemas/MonitoringEventIngestResult'
examples:
Replay:
value:
event_uuid: 33333333-4444-5555-6666-777777777777
event_id: login-2026-10-17-000001
status: ACCEPTED
score: 0
rules_evaluated_count: 6
rules_matched_count: 0
correlation_pending: false
retention_class: standard
expires_at: '2026-11-16T09:15:02.481000Z'
idempotent_replay: true
rule_matches: []
'201':
description: تم تخزين الحدث وتقييمه.
content:
application/json:
schema:
$ref: '#/components/schemas/MonitoringEventIngestResult'
examples:
Stored, no rule matched:
value:
event_uuid: 33333333-4444-5555-6666-777777777777
event_id: login-2026-10-17-000001
status: ACCEPTED
score: 0
rules_evaluated_count: 6
rules_matched_count: 0
correlation_pending: false
retention_class: standard
expires_at: '2026-11-16T09:15:02.481000Z'
idempotent_replay: false
rule_matches: []
Rule matched, async rule pending:
value:
event_uuid: 33333333-4444-5555-6666-777777777777
event_id: login-2026-10-17-000001
status: IN_REVIEW
score: 40
rules_evaluated_count: 6
rules_matched_count: 1
correlation_pending: true
retention_class: risk_relevant
expires_at: '2027-01-15T09:15:02.481000Z'
idempotent_replay: false
rule_matches:
- rule_id: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
library_key: null
mode: ACTIVE
is_async: false
'400':
description: >-
فشل التحقق. تكون مفاتيح نص الطلب هي الحقول؛ وتكون الحقول المتداخلة
كائنات متداخلة. لم يتم تخزين أي شيء.
content:
application/json:
examples:
Missing fields:
value:
event_id:
- This field is required.
subject:
- This field is required.
Unknown category:
value:
event_category:
- '"login" is not a valid choice.'
occurred_at too old:
value:
occurred_at:
- >-
occurred_at is more than 7 days in the past. Use the
batch import lane for backfills.
occurred_at in the future:
value:
occurred_at:
- occurred_at is more than 5 minutes in the future.
Missing subject vendor_data:
value:
subject:
vendor_data:
- This field is required.
Missing required payload keys:
value:
payload:
- >-
payment.deposit_completed requires: payment_method,
status.
Missing one-of payload key:
value:
payload:
- >-
dispute.chargeback_opened requires one of: dispute_id,
chargeback_id.
Security change without changed_field:
value:
payload:
- security.*_changed requires 'changed_field'.
Payload too large:
value:
payload:
- >-
payload exceeds 16384 bytes. Summarise telemetry
client-side.
Too many custom_values:
value:
custom_values:
- custom_values accepts at most 100 keys.
Nested custom value:
value:
custom_values:
- >-
custom_values['limits'] must be a scalar - rule
conditions cannot address nested values.
'401':
description: >-
انتهت صلاحية مفتاح API محدد النطاق. المفتاح منتهي الصلاحية فقط هو ما
يتلقى `401`؛ أما المفتاح المفقود أو غير الصالح فيتلقى `403`.
content:
application/json:
examples:
Expired key:
value:
detail: This API key has expired.
'403':
description: >-
`x-api-key` مفقود (المفتاح الخاطئ أو الملغى أو منتهي الصلاحية يتلقى
`401`)، أو مفتاح ذو نطاق محدد يفتقر إلى `transactions: write`، أو
مفتاح مقتصر على بعض مسارات سير العمل أو على الجلسات المقبولة (مثل
هذا المفتاح لا يصل أبداً إلى بيانات مراقبة المعاملات)، أو طلب من
خارج قائمة العناوين المسموح بها للمفتاح. يُرجع أيضاً مع `code:
event_monitoring_disabled` أثناء تعطيل استيعاب الأحداث للتطبيق؛ لا
يتم تخزين أي شيء في تلك الحالة، ويتم إجراء الفحص قبل التحقق من صحة
نص الطلب.
content:
application/json:
examples:
Event monitoring disabled:
value:
detail: >-
Event monitoring is not enabled for this application. Turn
on event ingestion in the transaction monitoring settings
before submitting events.
code: event_monitoring_disabled
Missing or invalid API key:
value:
detail: You do not have permission to perform this action.
Scoped key without access:
value:
detail: This API key has no write access to transactions.
Key limited to workflows or approved sessions:
value:
detail: >-
This API key only reaches sessions inside its workflow or
status limits, so it can't use this endpoint.
IP not allowed:
value:
detail: This API key can't be used from this IP address.
'409':
description: >-
تم استخدام `event_id` بالفعل لحدث ذي محتوى مختلف (الفئة، نوع
الإجراء، `occurred_at`، أو `vendor_data` الخاص بالموضوع، أو
payload). أرسل الحدث بقيمة `event_id` جديدة.
content:
application/json:
examples:
event_id reused:
value:
event_id: >-
event_id 'login-2026-10-17-000001' already exists with a
different payload.
'429':
description: >-
تم تجاوز حد المعدل: تتشارك عمليات إنشاء المعاملات واستيعاب الأحداث
(`POST /v3/transactions/`، `POST /v3/events/`، `POST
/v3/events/batch/`) رصيداً قدره 600 طلب في الدقيقة لكل مفتاح API،
وهو منفصل عن رصيد الـ 300 المشترك بين سائر طلبات الكتابة الأخرى.
انتظر لعدد الثواني المحدد في `Retry-After`، ثم أعد المحاولة.
headers:
Retry-After:
description: >-
عدد الثواني التي يجب انتظارها قبل إعادة المحاولة، مقربة للأعلى
لتقع إعادة المحاولة في النافذة التالية.
schema:
type: integer
minimum: 1
example: 30
content:
application/json:
examples:
Throttled:
value:
detail: >-
Ingestion rate limit exceeded. You can make up to 600
requests per minute.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: |-
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-10-17-000001",
"event_category": "auth",
"action_type": "login",
"occurred_at": "2026-10-17T09:15:02.481Z",
"subject": {"vendor_data": "user-42", "entity_type": "individual"},
"session": {"session_id": "web-session-abc", "sequence": 142},
"device_context": {
"fingerprint": "fp-a8c1",
"network_context": {"ip_address": "203.0.113.42"}
},
"payload": {"method": "password"}
}'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY.
client = Didit()
result = client.monitoring_events.create(
event_id="login-2026-10-17-000001",
event_category="auth",
action_type="login",
occurred_at="2026-10-17T09:15:02.481Z",
time_zone="Europe/Madrid",
subject={
"vendor_data": "user-42",
"entity_type": "individual",
},
session={
"session_id": "web-session-abc",
"sequence": 142,
},
device_context={
"fingerprint": "fp-a8c1",
"network_context": {
"ip_address": "203.0.113.42",
},
},
payload={"method": "password"},
custom_values={"vip_tier": "gold"},
)
print(result)
- lang: javascript
label: Node.js
source: |-
import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY.
const didit = new Didit();
const result = await didit.monitoringEvents.create({
event_id: "login-2026-10-17-000001",
event_category: "auth",
action_type: "login",
occurred_at: "2026-10-17T09:15:02.481Z",
time_zone: "Europe/Madrid",
subject: {
vendor_data: "user-42",
entity_type: "individual",
},
session: {
session_id: "web-session-abc",
sequence: 142,
},
device_context: {
fingerprint: "fp-a8c1",
network_context: {
ip_address: "203.0.113.42",
},
},
payload: { method: "password" },
custom_values: { vip_tier: "gold" },
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.MonitoringEvents.Create(ctx, didit.MonitoringEventCreateRequest{\n\tEventID: \"login-2026-10-17-000001\",\n\tEventCategory: \"auth\",\n\tActionType: \"login\",\n\tOccurredAt: time.Date(2026, 10, 17, 9, 15, 2, 0, time.UTC),\n\tTimeZone: didit.String(\"Europe/Madrid\"),\n\tSubject: didit.MonitoringEventCreateRequestSubject{\n\t\tVendorData: \"user-42\",\n\t\tEntityType: didit.String(\"individual\"),\n\t},\n\tSession: didit.Some(didit.MonitoringEventCreateRequestSession{\n\t\tSessionID: didit.String(\"web-session-abc\"),\n\t\tSequence: didit.Int(142),\n\t}),\n\tDeviceContext: didit.Some(didit.MonitoringEventCreateRequestDeviceContext{\n\t\tFingerprint: didit.String(\"fp-a8c1\"),\n\t\tNetworkContext: didit.Some(didit.MonitoringEventCreateRequestDeviceContextNetworkContext{\n\t\t\tIPAddress: didit.String(\"203.0.113.42\"),\n\t\t}),\n\t}),\n\tPayload: didit.Some(map[string]any{\"method\": \"password\"}),\n\tCustomValues: didit.Some(map[string]any{\"vip_tier\": \"gold\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: >-
import java.time.OffsetDateTime;
import java.util.Map;
import me.didit.Didit;
import me.didit.types.MonitoringEventCreateRequest;
// Reads DIDIT_API_KEY.
Didit client = new Didit();
var result =
client.monitoringEvents().create(MonitoringEventCreateRequest.builder()
.eventId("login-2026-10-17-000001")
.eventCategory(MonitoringEventCreateRequest.EventCategory.of("auth"))
.actionType("login")
.occurredAt(OffsetDateTime.parse("2026-10-17T09:15:02.481Z"))
.timeZone("Europe/Madrid")
.subject(MonitoringEventCreateRequest.Subject.builder()
.vendorData("user-42")
.entityType("individual")
.build())
.session(MonitoringEventCreateRequest.Session.builder()
.sessionId("web-session-abc")
.sequence(142L)
.build())
.deviceContext(MonitoringEventCreateRequest.DeviceContext.builder()
.fingerprint("fp-a8c1")
.networkContext(MonitoringEventCreateRequest.DeviceContext.NetworkContext.builder()
.ipAddress("203.0.113.42")
.build())
.build())
.payload(Map.of("method", "password"))
.customValues(Map.of("vip_tier", MonitoringEventCreateRequest.CustomValuesValue.ofString("gold")))
.build());
System.out.println(result);
- lang: php
label: PHP
source: |-
monitoringEvents->create([
'event_id' => 'login-2026-10-17-000001',
'event_category' => 'auth',
'action_type' => 'login',
'occurred_at' => '2026-10-17T09:15:02.481Z',
'time_zone' => 'Europe/Madrid',
'subject' => [
'vendor_data' => 'user-42',
'entity_type' => 'individual',
],
'session' => [
'session_id' => 'web-session-abc',
'sequence' => 142,
],
'device_context' => [
'fingerprint' => 'fp-a8c1',
'network_context' => [
'ip_address' => '203.0.113.42',
],
],
'payload' => ['method' => 'password'],
'custom_values' => ['vip_tier' => 'gold'],
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY.
didit = Didit::Client.new
result = didit.monitoring_events.create(
event_id: "login-2026-10-17-000001",
event_category: "auth",
action_type: "login",
occurred_at: "2026-10-17T09:15:02.481Z",
time_zone: "Europe/Madrid",
subject: {
vendor_data: "user-42",
entity_type: "individual",
},
session: {
session_id: "web-session-abc",
sequence: 142,
},
device_context: {
fingerprint: "fp-a8c1",
network_context: {
ip_address: "203.0.113.42",
},
},
payload: { method: "password" },
custom_values: { vip_tier: "gold" }
)
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Collections.Generic;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY.
using var client = new DiditClient();
var result = await client.MonitoringEvents.CreateAsync(new
MonitoringEventCreateRequest
{
EventId = "login-2026-10-17-000001",
EventCategory = "auth",
ActionType = "login",
OccurredAt = DateTimeOffset.Parse("2026-10-17T09:15:02.481Z"),
TimeZone = "Europe/Madrid",
Subject = new()
{
VendorData = "user-42",
EntityType = "individual",
},
Session = new MonitoringEventCreateRequestSession
{
SessionId = "web-session-abc",
Sequence = 142,
},
DeviceContext = new MonitoringEventCreateRequestDeviceContext
{
Fingerprint = "fp-a8c1",
NetworkContext = new MonitoringEventCreateRequestDeviceContextNetworkContext
{
IpAddress = "203.0.113.42",
},
},
Payload = new Dictionary { ["method"] = "password" },
CustomValues = new Dictionary { ["vip_tier"] = "gold" },
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
schemas:
MonitoringEventCreateRequest:
type: object
description: >-
غلاف الحدث (envelope)، وهو متطابق لكل فئة. تُقبل الأسماء البديلة بصيغة
camelCase: `eventId`، و`eventCategory` (أو `category`)، و`actionType`،
و`occurredAt`، و`timeZone` (أو `zoneId`)، و`deviceContext` (أو
`device`)، و`transactionContext`، و`customValues` (أو `props`)؛ وداخل
`subject`: `vendorData`، و`entityType`، و`fullName`؛ وداخل `session`:
`sessionId`، و`pageUrl`؛ وداخل `transaction_context`:
`paymentReferenceId`.
required:
- event_id
- event_category
- action_type
- occurred_at
- subject
properties:
event_id:
type: string
maxLength: 128
description: >-
المعرّف الخاص بك للحدث، ويكون فريداً لكل تطبيق. إنه مفتاح
idempotency: إعادة إرسال نفس `event_category` و`action_type`
و`occurred_at` و`subject.vendor_data` و`payload` تحته تُعد إعادة
تشغيل، وأي اختلاف يُعد تعارضاً.
example: login-2026-10-17-000001
event_category:
type: string
enum:
- auth
- session
- gameplay
- bonus
- affiliate
- payment
- dispute
- security
- responsible_gambling
- custom
description: فئة الحدث.
example: auth
action_type:
type: string
minLength: 1
maxLength: 128
description: >-
ما حدث ضمن الفئة. مفردات مفتوحة؛ تتيح الإجراءات المُدارة المدرجة في
[استيعاب
الأحداث](https://docs.didit.me/ar/transaction-monitoring/events)
(على سبيل المثال `login` و`deposit_completed` و`chargeback_opened`)
التحقق من النوع وحقول القواعد المُدارة. يتم اقتطاع المسافات البيضاء
في البداية والنهاية.
example: login
occurred_at:
type: string
format: date-time
description: >-
وقت وقوع الحدث من جانبك، بتنسيق ISO 8601 (أي قيمة بدون فارق زمني
تُقرأ على أنها UTC). يجب ألا يزيد عمره على 7 أيام في الماضي وألا
يتجاوز 5 دقائق في المستقبل.
example: '2026-10-17T09:15:02.481Z'
time_zone:
type: string
nullable: true
maxLength: 64
description: >-
المنطقة الزمنية لحدوث الواقعة من جانبك، على سبيل المثال
`Europe/Madrid`. يتم تخزينها مع الحدث؛ ولا تُرجعها endpoint الخاصة
بالقراءة.
subject:
type: object
description: >-
المستخدم أو الشركة التي ينتمي إليها الحدث. ويُحدَّد بالمستخدم (أو
الشركة) التي تملك `vendor_data` هذه في تطبيقك؛ ويتم إنشاء واحد عند
عدم وجوده.
required:
- vendor_data
properties:
vendor_data:
type: string
minLength: 1
maxLength: 255
description: المعرّف الخاص بك للكيان.
example: user-42
entity_type:
type: string
maxLength: 32
default: individual
description: >-
يحلّ `company` الموضوع إلى شركة؛ وأي قيمة أخرى (الافتراضية
`individual`) تحلّه إلى فرد. يمكن لنفس `vendor_data` تسمية واحد
من كل منهما.
example: individual
full_name:
type: string
nullable: true
maxLength: 512
description: اسم العرض، يُستخدم فقط عندما يُنشئ هذا الحدث المستخدم أو الشركة.
email:
type: string
format: email
nullable: true
description: تم التحقق من صحته كعنوان بريد إلكتروني؛ ولا يتم تخزينه في الحدث.
phone:
type: string
nullable: true
maxLength: 32
description: تم التحقق من صحته؛ ولا يتم تخزينه في الحدث.
country:
type: string
nullable: true
maxLength: 3
description: تم التحقق من صحته؛ ولا يتم تخزينه في الحدث.
business:
type: object
description: >-
الشركة التي ينتمي إليها الحدث، عندما تختلف عن الكيان المعني. تُقرأ
`vendor_data` فقط.
additionalProperties: true
properties:
vendor_data:
type: string
maxLength: 255
description: المعرّف الخاص بك للشركة. يمكن تصفيته كـ `business_vendor_data`.
example: merchant-7
session:
type: object
description: سياق الجلسة الخاص بك للحدث.
properties:
session_id:
type: string
nullable: true
maxLength: 255
description: معرّف الجلسة الخاص بك. قابل للتصفية ويُعاد كـ `session_id`.
sequence:
type: integer
nullable: true
description: موضع الحدث داخل الجلسة. يُرجع كـ `session_sequence`.
page_url:
type: string
nullable: true
maxLength: 2048
description: تم التحقق من صحته؛ ولا يتم تخزينه في الحدث.
referrer:
type: string
nullable: true
maxLength: 2048
description: تم التحقق من صحته؛ ولا يتم تخزينه في الحدث.
device_context:
type: object
additionalProperties: true
description: >-
سياق الجهاز والشبكة، يُخزن كما تم إرساله ويُرجع بواسطة `GET
/v3/events/{event_uuid}/`. في مسار الخادم هذا، لا ترى Didit اتصال
المستخدم النهائي، لذا فإن عنوان IP المُثرى والمُستخدم بواسطة القواعد
هو `network_context.ip_address` كما ترسله أنت.
properties:
fingerprint:
type: string
maxLength: 255
description: بصمة الجهاز. قابلة للتصفية كـ `device_fingerprint`.
persistent_device_id:
type: string
maxLength: 255
description: معرّف جهازك الدائم.
bot_score:
type: integer
description: درجة البوت من نظام الكشف الخاص بك، كعدد صحيح.
network_context:
type: object
additionalProperties: true
properties:
ip_address:
type: string
maxLength: 64
description: >-
عنوان IP الخاص بالمستخدم النهائي. يتم إثراء العناوين العامة
مرة واحدة لكل عنوان فريد.
example: 203.0.113.42
transaction_context:
type: object
description: >-
سياق الأموال. تلبي القيم غير الفارغة هنا أيضاً مفاتيح payload
المطلوبة للإجراء.
properties:
amount:
type: string
nullable: true
description: المبلغ كسلسلة عشرية (يُقبل أيضاً كرقم).
example: '1000.00'
currency:
type: string
nullable: true
maxLength: 10
description: رمز العملة.
direction:
type: string
nullable: true
maxLength: 16
description: اتجاه حركة الأموال، على سبيل المثال `inbound` أو `outbound`.
payment_reference_id:
type: string
nullable: true
maxLength: 255
description: مرجع الدفع الخاص بك. يمكن تصفيته كـ `payment_reference_id`.
payload:
type: object
additionalProperties: true
description: >-
حقول النطاق الخاصة بالفئة، بحد أقصى 16384 بايت بمجرد ترميزها بتنسيق
JSON. تتطلب بعض الإجراءات مفاتيح (في `payload` أو
`transaction_context`): يتطلب `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_initiated`
و`payment.deposit_completed` و`payment.withdrawal_requested`
و`payment.withdrawal_completed` كلاً من `payment_reference_id`
و`amount` و`currency` و`payment_method` و`status`؛ ويتطلب
`payment.withdrawal_address_changed` المعرّف
`withdrawal_address_hash`؛ ويتطلب `dispute.chargeback_opened`
و`dispute.chargeback_won` و`dispute.chargeback_lost` الحقل
`payment_reference_id` وواحداً من `dispute_id` أو `chargeback_id`؛
ويتطلب `session.bot_signal_observed` الحقل
`telemetry_schema_version` وواحداً من `bot_score` أو
`actions_per_minute` أو `timing_variance_ms` أو `pointer_entropy` أو
`keystroke_entropy` أو `reaction_time_ms_p50`؛ ويتطلب
`responsible_gambling.self_exclusion_match` كلاً من
`registry_source` و`exclusion_status` و`identity_match_ref`. يتطلب
كل إجراء `security` ينتهي بـ `_changed` الحقل `changed_field`،
بالإضافة إلى `previous_reference_hash` أو `new_reference_hash` عندما
يكون الحقل هو `password` أو `mfa_method` أو `mfa` أو `email` أو
`phone` أو `withdrawal_address` أو `payout_method` أو `api_key`.
أرسل التجزئات والمراجع، ولا ترسل أبداً رقم بطاقة أو عنوان سحب كاملاً
أو تجزئة كلمة مرور أو سر MFA.
custom_values:
type: object
description: >-
ما يصل إلى 100 مفتاح خاص بك، يمكن الرجوع إليها من القواعد بصيغة
`custom_values.`. يجب أن تكون القيم عددية أو نصية بسيطة (string
أو number أو boolean أو null)؛ ويتم رفض الكائنات والمصفوفات
المتداخلة.
additionalProperties:
nullable: true
oneOf:
- type: string
- type: number
- type: boolean
example:
event_id: login-2026-10-17-000001
event_category: auth
action_type: login
occurred_at: '2026-10-17T09:15:02.481Z'
time_zone: Europe/Madrid
subject:
vendor_data: user-42
entity_type: individual
session:
session_id: web-session-abc
sequence: 142
device_context:
fingerprint: fp-a8c1
network_context:
ip_address: 203.0.113.42
payload:
method: password
custom_values:
vip_tier: gold
MonitoringEventIngestResult:
type: object
description: >-
نتيجة استيعاب حدث واحد. يُعاد الشكل نفسه لحدث جديد ولإعادة تشغيل
idempotent.
required:
- event_uuid
- event_id
- status
- score
- rules_evaluated_count
- rules_matched_count
- correlation_pending
- retention_class
- expires_at
- idempotent_replay
- rule_matches
properties:
event_uuid:
type: string
format: uuid
description: معرّف Didit للحدث المخزن.
event_id:
type: string
description: حقل `event_id` الخاص بك.
status:
type: string
enum:
- ACCEPTED
- APPROVED
- IN_REVIEW
- DECLINED
description: >-
الحالة بعد تشغيل القواعد في الوقت الفعلي. انظر
`MonitoringEvent.status`.
score:
type: integer
description: الدرجة بعد تشغيل القواعد في الوقت الفعلي.
rules_evaluated_count:
type: integer
minimum: 0
description: >-
عدد قواعد الأحداث التي تم تقييمها في الطلب. 0 في تطبيق البيئة
التجريبية، حيث لا يتم تشغيل أي قواعد.
rules_matched_count:
type: integer
minimum: 0
description: عدد القواعد التي تطابقت، بما في ذلك قواعد وضع `TEST`.
correlation_pending:
type: boolean
description: >-
تكون القيمة `true` عندما لا يزال يتعين تشغيل قاعدة غير متزامنة. اقرأ
`GET /v3/events/{event_uuid}/` بعد بضع دقائق للحصول على `status`
و`score` النهائيين.
retention_class:
type: string
enum:
- low_value
- standard
- risk_relevant
- monetary_or_compliance
description: فئة الاحتفاظ، بعد أي ترقية بواسطة قاعدة مطابقة.
expires_at:
type: string
format: date-time
nullable: true
description: >-
وقت انتهاء صلاحية الحدث بموجب فئة الاحتفاظ به وحذفه. القيمة Null
لأحداث `monetary_or_compliance` (المدفوعات والنزاعات).
idempotent_replay:
type: boolean
description: >-
تكون القيمة `true` عندما يكون هناك حدث بهذا الـ `event_id` وبالمحتوى
نفسه مخزناً بالفعل؛ وتكون القيم هي قيم الحدث المخزن ولم يتم تشغيل أي
قاعدة مرة أخرى.
rule_matches:
type: array
description: القواعد التي تطابقت مع الحدث.
items:
type: object
required:
- rule_id
- library_key
- mode
- is_async
properties:
rule_id:
type: string
format: uuid
description: معرّف UUID للقاعدة.
library_key:
type: string
nullable: true
description: >-
مفتاح المكتبة عندما يتم تثبيت القاعدة من مكتبة القواعد، وإلا
يكون null.
mode:
type: string
enum:
- ACTIVE
- TEST
description: تسجل قواعد `TEST` التطابق ولكنها لا تطبق أي إجراءات.
is_async:
type: boolean
description: >-
تكون `true` عندما تكون المطابقة ناتجة عن المعالجة غير
المتزامنة.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console.
يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا
شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات
المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن
المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم
إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو
الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير
404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة
بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL
للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك
إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع
https://docs.didit.me/console/api-keys.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.