> ## 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.

# تكامل مراقبة المعاملات: واجهة KYT البرمجية

> بنية KYT من Didit وأفضل ممارساتها: الزمن الفعلي مقابل الدفعات، والأطراف، وidempotency، والاستيعاب التاريخي، وwebhook. 1,000 شهرياً مشمولة، ثم $0.001 لكل عملية.

هذا الدليل يغطي جميع جوانب التكامل لمراقبة المعاملات. يساعدك [دليل البدء السريع](https://docs.didit.me/ar/transaction-monitoring/quickstart.md) على التشغيل الأولي، أما هذه الصفحة فتأخذك إلى الإنتاج.

## البنية

```mermaid theme={null}
sequenceDiagram
    participant You as Your platform
    participant Didit as Didit API
    participant Rules as Rule engine
    participant AML as AML providers
    participant Webhook as Your webhook

    You->>Didit: POST /v3/transactions/ (txn_id, parties, amount)
    Didit->>Didit: IP enrichment (inline)
    Didit->>AML: Screen wallet or transaction hash + address
    AML-->>Didit: Hits / clean
    Didit->>Rules: Evaluate all active rules
    Rules-->>Didit: Score + matched rules + actions
    Didit-->>You: Transaction record with status
    Didit->>Webhook: transaction.created
    Didit->>Webhook: transaction.status.updated (if async rules)
```

## المصادقة

استخدم ترويسة `x-api-key` القياسية. تُستخدم المفاتيح نفسها للجلسات والكيانات. راجع [مصادقة API](https://docs.didit.me/ar/getting-started/api-authentication.md).

## إرسال معاملة

نقطة نهاية واحدة: `POST /v3/transactions/`. راجع [إرسال المعاملات](https://docs.didit.me/ar/transaction-monitoring/transactions.md) للاطلاع على المخطط الكامل.

**الحمولة الدنيا:**

```json theme={null}
{
  "transaction_id": "tx-0001",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "500.00",
    "currency": "EUR"
  },
  "subject": { "entity_type": "person", "vendor_data": "user-42", "full_name": "John Doe" },
  "counterparty": { "entity_type": "company", "full_name": "Acme Corp" }
}
```

**حمولة أغنى تتضمن طرق الدفع وسياق الجهاز والخصائص المخصصة:**

```json theme={null}
{
  "transaction_id": "tx-0002",
  "transaction_at": "2026-04-16T10:00:00Z",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "12500.00",
    "currency": "USD",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "person",
    "vendor_data": "user-42",
    "full_name": "John Doe",
    "country_code": "US",
    "device_context": {
      "fingerprint": "fp-9f2c...",
      "user_agent": "Mozilla/5.0 ...",
      "browser_family": "Chrome",
      "platform": "web",
      "network_context": { "ip_address": "203.0.113.5" }
    },
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US12345678901234567890",
      "issuing_country": "US"
    }
  },
  "counterparty": {
    "entity_type": "company",
    "vendor_data": "biz-acme",
    "full_name": "Acme Corp",
    "country_code": "US",
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US09876543210987654321",
      "issuing_country": "US"
    }
  },
  "custom_properties": {
    "invoice_id": "INV-2026-00042",
    "category": "b2b_goods"
  }
}
```

تُقبل أسماء camelCase البديلة لكل حقل على المستوى الأعلى (`txnId`، `txnDate`، `type`، `info`، `applicant`، `props`، `travelRule`، `includeCryptoScreening`)، ويصل تنسيق الإرسال في SDK وتنسيق snake\_case إلى المكان نفسه.

## نمذجة الأطراف

كل معاملة تتطلب `subject` (عميلك، أي الطرف الذي تراقبه) وتقبل `counterparty` اختيارياً (الطرف المقابل). يحمل كل منهما `payment_method` الخاص به وسياق `device` اختيارياً.

في الاستجابة، تُعاد الأطراف في المصفوفة `parties` بالأدوار `APPLICANT` و`COUNTERPARTY`. يُخزَّن الطرف الذي لا يحتوي على `vendor_data` كلقطة خارجية (`kind: EXTERNAL`) دون كيان مرتبط.

راجع [حمولة المعاملات](https://docs.didit.me/ar/transaction-monitoring/transactions.md) للاطلاع على حقول الأطراف.

## Idempotency

`txn_id` (وهو `transaction_id` الذي ترسله) فريد لكل تطبيق.
عند إعادة إرسال `transaction_id` موجود مسبقاً، تُعيد الواجهة الخطأ `400` مع الرسالة `A transaction with this transaction_id already exists.` في الحقل `transaction_id`. وإذا تسابق طلبان متطابقان، يتلقى الطلب الثاني الرد `409`.
لا يعيد أيٌّ من الردين المعاملة الموجودة.
عند الرد `400` أو `409` لتكرار `transaction_id`، ابحث عن المعاملة الموجودة بدلاً من إعادة الإرسال: اقرأها عبر [`GET /v3/transactions/{uuid}/`](https://docs.didit.me/ar/management-api/transactions/get) باستخدام `uuid` من الاستجابة الأولى، أو استخدم `transaction_id` (معرّف uuid لدى Didit) الذي يحمله حدث webhook `transaction.created` بجوار `txn_id` الخاص بك.

**أنشئ دائماً `txn_id` من جهتك** قبل الإرسال، ولا تعتمد على معرّف تولّده Didit من أجل idempotency. استخدم معرّف قاعدة بياناتك، أو UUID، أو تجزئة (hash) لحقول المعاملة.

## الفوري مقابل الدفعات

* **الفوري:** الخيار الموصى به لمعظم حالات الاستخدام. أرسل المعاملة لحظة حدوثها في نظامك. تُقيَّم القواعد بشكل متزامن وتعيد القرار.
* **الدفعات / الاستيعاب بأثر رجعي:** لاستيعاب البيانات التاريخية، مرّر `txn_date` بتاريخ في الماضي. تُنفَّذ القواعد أيضاً ويمكنها تفعيل webhooks. لتجنب تفعيل القواعد أثناء الاستيعاب بأثر رجعي، استخدم استيراد CSV من لوحة التحكم مع تفعيل علامة "dry ingest".

## استيعاب البيانات التاريخية

عند الانتقال من نظام مراقبة معاملات آخر:

1. صدّر معاملاتك التاريخية إلى ملف CSV.
2. استخدم *Transactions → Import history* في لوحة التحكم (أو أرسل عبر API ضمن حلقة برمجية) مع `txn_date` بتاريخ في الماضي.
3. فعّل القواعد بعد انتهاء الاستيعاب فقط، أو استخدم dry ingest لتخطي تقييم القواعد.

> [!WARNING]
>
> كن حذراً في تقييم القواعد على البيانات التاريخية. فإدخال 6 أشهر من السجل عبر قاعدة "20 تحويلاً خلال 30 يوماً" سيولّد آلاف التنبيهات دفعة واحدة.

## Webhooks

اشترك في:

* `transaction.created`: كل معاملة مُرسلة.
* `transaction.status.updated`: تغييرات الحالة (مثلاً ينقل المحلل المعاملة من `IN_REVIEW` إلى `APPROVED`، أو يحدّث فحص AML غير المتزامن الدرجة).

التفاصيل الكاملة: [webhook الخاصة بـ TM](https://docs.didit.me/ar/transaction-monitoring/webhooks.md).

```typescript theme={null}
app.post('/webhooks/didit-tm', (req, res) => {
  if (!verifySignature(req)) return res.status(401).end();

  const { webhook_type, status, txn_id } = req.body;
  if (webhook_type === 'transaction.status.updated' && status === 'DECLINED') {
    suspendTransaction(txn_id);
  }
  res.status(200).end();
});
```

## التعامل مع الحالات

| الحالة | ما الذي يجب فعله |
| - | - |
| `APPROVED` | عالج المعاملة كالمعتاد. |
| `IN_REVIEW` | علّق المعاملة حتى تُحسم مراجعة المحلل أو إعادة الفحص الآلية. |
| `DECLINED` | ارفض المعاملة. اعرض رسالة خطأ عامة للمستخدم. |
| `AWAITING_USER` | يجب أن يتخذ المستخدم إجراءً قبل أن تُسوّى المعاملة. اقرأ كتلة `action_required` وسلّم `url` الخاص بها إلى المستخدم (تستطيع SDKs [التعامل مع ذلك تلقائياً](https://docs.didit.me/ar/transaction-monitoring/sdk-transaction-submission.md#الإجراءات-المطلوبة-من-المستخدم)). |

راجع [حالات TM](https://docs.didit.me/ar/transaction-monitoring/statuses.md).

## ربط المعاملات بالكيانات

مرّر `vendor_data` في كل طرف. وتتمثل الفوائد في:

* تتجمع كل معاملة في ملف المستخدم أو ملف الشركة.
* تستند قواعد السرعة والسلوك إلى السجل الكامل لتقييم المعاملات.
* يمتد حظر الكيان تلقائياً إلى المعاملات المستقبلية.

غياب `vendor_data` لا يُعد خطأً يمنع المعالجة: تُخزَّن المعاملة كلقطة خارجية، لكنك تفقد التجميع على مستوى الكيان.

## جلسات المعالجة

عندما يُعيّن إجراء قاعدة معاملةً إلى الحالة `AWAITING_USER`، ينشئ Didit تلقائياً **جلسة المعالجة التصحيحية**، وهي جلسة تحقق مستضافة قياسية لنفس `vendor_data`.
تحدد القواعد المخصصة دائماً سير العمل مباشرةً في الإجراء نفسه. أما في قواعد المكتبة المدمجة، فيُرجَع إلى [سير عمل المعالجة في إعدادات المعاملات](https://docs.didit.me/ar/transaction-monitoring/settings.md#سير-عمل-المعالجة)، ثم إلى سير **المصادقة البيومترية** في تطبيقك (عندما يكون للمستخدم وجه مرجعي مخزَّن)، ثم إلى سير العمل الافتراضي في تطبيقك.
لا تنطبق هذه الآلية الاحتياطية التلقائية على معاملات Travel Rule، إذ يكون إجراؤها المعلّق هو إثبات ملكية المحفظة.
تتضمن المعاملة (الاستجابة وكل قراءة لاحقة وكل webhook) هذه الجلسة في كتلة `action_required` القياسية:

```json theme={null}
{
  "status": "AWAITING_USER",
  "action_required": {
    "type": "verification_session",
    "url": "https://verify.didit.me/session/...",
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "status": "Not Started"
  },
  "remediation": {
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "url": "https://verify.didit.me/session/...",
    "status": "Not Started"
  }
}
```

`remediation` مُبقاة للتوافق مع الإصدارات السابقة، أما `action_required` فهي الكتلة القياسية، وتتضمن أيضاً إجراءات `wallet_ownership` لتحويلات [Travel Rule](https://docs.didit.me/ar/transaction-monitoring/travel-rule.md).
لا يغيّر إجراء `wallet_ownership` حالة المعاملة بمفرده: تحتفظ المعاملة بالحالة التي تمنحها إياها قواعدك، وغالباً ما تكون `APPROVED`، لذا تحقق من `action_required` في كل استجابة، لا في حالة `AWAITING_USER` وحدها.

يُكمل المستخدم التحقق. في سير عمل **المصادقة البيومترية**، يلتقط المستخدم صورة سيلفي مع فحص الحيوية تُطابَق مع الوجه الذي التُقط عند التسجيل الأصلي في KYC، وهي أقوى خطوة تحقق إضافية لـ[المعاملات عالية القيمة](https://docs.didit.me/ar/transaction-monitoring/sdk-transaction-submission.md#مثال-التحقق-البيومتري-الإضافي-لسحب-عالي-القيمة).
عندما تصل الجلسة إلى قرار، تتبع المعاملة هذا القرار تلقائياً: `APPROVED` (`decision_reason_code: user_action_approved`)، أو `DECLINED` (`user_action_declined`)، أو `IN_REVIEW` (`user_action_in_review`)، ويُرسَل webhook من نوع `transaction.status.updated`.

> [!NOTE]
>
> يمكن اختيار أي نوع من أنواع سير العمل باستثناء KYB.
> يتطلب سير عمل المصادقة البيومترية (وسير العمل الذي تُنفَّذ فيه مطابقة الوجه قبل التحقق من الهوية) أن يكون لدى المستخدم وجه مرجعي مخزَّن من عملية تحقق مقبولة مسبقاً. أما المستخدمون الذين لا يملكون وجهاً مرجعياً فيُوجَّهون إلى سير العمل الافتراضي في تطبيقك بدلاً من ذلك، مع ملاحظة تُسجَّل في المعاملة توضح هذا الاستبدال.

## أفضل الممارسات

| الممارسة | السبب |
| - | - |
| مرّر `vendor_data` دائماً | يتيح التجميع. |
| استخدم `txn_id` خاصاً بك | لضمان idempotency. |
| اشترك في `transaction.created` و`transaction.status.updated` معاً | لالتقاط تغييرات الحالة غير المتزامنة (مثل نتائج مراجعة المحلل). |
| حدِّد حدود القواعد بعناية | الحدود المنخفضة = تنبيهات أكثر، والحدود المرتفعة = مخاطر أكثر تفوتك. راجع [احتساب درجات المخاطر](https://docs.didit.me/ar/transaction-monitoring/risk-scoring.md). |
| راقب عدد مرات تشغيل القواعد في وحدة التحكم | لاكتشاف القواعد التي لا تعمل أبداً (بسبب سوء الإعداد) أو التي تعمل على كل شيء (لأنها فضفاضة أكثر من اللازم). |
| اختبر القواعد في وضع TEST قبل التشغيل الفعلي | راجع [القواعد](https://docs.didit.me/ar/transaction-monitoring/rules.md). |

## حدود المعدل

راجع [تحديد معدل الطلبات](https://docs.didit.me/ar/integration/rate-limiting.md). يُعد إنشاء المعاملة أحد endpoint الأعلى من حيث معدل معالجة الطلبات. تبلغ الحدود المعتادة مئات الطلبات في الثانية. توخَّ الحذر عند إرسال دفعات الطلبات.

## الخطوات التالية

> [card] [المعاملات](https://docs.didit.me/ar/transaction-monitoring/transactions.md)
>
> المرجع الكامل لـ payload.

> [card] [القواعد](https://docs.didit.me/ar/transaction-monitoring/rules.md)
>
> كيفية تقييم القواعد.

> [card] [webhook](https://docs.didit.me/ar/transaction-monitoring/webhooks.md)
>
> كتالوج الأحداث.

> [card] [استكشاف الأخطاء وإصلاحها](https://docs.didit.me/ar/transaction-monitoring/troubleshooting.md)
>
> أكثر مشكلات التكامل شيوعاً.


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