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

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

البنية

المصادقة

استخدم ترويسة x-api-key القياسية. تُستخدم المفاتيح نفسها للجلسات والكيانات. راجع مصادقة API.

إرسال معاملة

نقطة نهاية واحدة: POST /v3/transactions/. راجع إرسال المعاملات للاطلاع على المخطط الكامل. الحمولة الدنيا:

{
  "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" }
}

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

{
  "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) دون كيان مرتبط. راجع حمولة المعاملات للاطلاع على حقول الأطراف.

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}/ باستخدام uuid من الاستجابة الأولى، أو استخدم transaction_id (معرّف uuid لدى Didit) الذي يحمله حدث webhook transaction.created بجوار txn_id الخاص بك. أنشئ دائماً txn_id من جهتك قبل الإرسال، ولا تعتمد على معرّف تولّده Didit من أجل idempotency. استخدم معرّف قاعدة بياناتك، أو UUID، أو تجزئة (hash) لحقول المعاملة.

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

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

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

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

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

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

Webhooks

اشترك في:

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

التفاصيل الكاملة: webhook الخاصة بـ TM.

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 التعامل مع ذلك تلقائياً).

راجع حالات TM.

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

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

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

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

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

عندما يُعيّن إجراء قاعدة معاملةً إلى الحالة AWAITING_USER، ينشئ Didit تلقائياً جلسة المعالجة التصحيحية، وهي جلسة تحقق مستضافة قياسية لنفس vendor_data. تحدد القواعد المخصصة دائماً سير العمل مباشرةً في الإجراء نفسه. أما في قواعد المكتبة المدمجة، فيُرجَع إلى سير عمل المعالجة في إعدادات المعاملات، ثم إلى سير المصادقة البيومترية في تطبيقك (عندما يكون للمستخدم وجه مرجعي مخزَّن)، ثم إلى سير العمل الافتراضي في تطبيقك. لا تنطبق هذه الآلية الاحتياطية التلقائية على معاملات Travel Rule، إذ يكون إجراؤها المعلّق هو إثبات ملكية المحفظة. تتضمن المعاملة (الاستجابة وكل قراءة لاحقة وكل webhook) هذه الجلسة في كتلة action_required القياسية:

{
  "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. لا يغيّر إجراء wallet_ownership حالة المعاملة بمفرده: تحتفظ المعاملة بالحالة التي تمنحها إياها قواعدك، وغالباً ما تكون APPROVED، لذا تحقق من action_required في كل استجابة، لا في حالة AWAITING_USER وحدها. يُكمل المستخدم التحقق. في سير عمل المصادقة البيومترية، يلتقط المستخدم صورة سيلفي مع فحص الحيوية تُطابَق مع الوجه الذي التُقط عند التسجيل الأصلي في KYC، وهي أقوى خطوة تحقق إضافية لـالمعاملات عالية القيمة. عندما تصل الجلسة إلى قرار، تتبع المعاملة هذا القرار تلقائياً: APPROVED (decision_reason_code: user_action_approved)، أو DECLINED (user_action_declined)، أو IN_REVIEW (user_action_in_review)، ويُرسَل webhook من نوع transaction.status.updated.

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

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

الممارسة	السبب
مرّر `vendor_data` دائماً	يتيح التجميع.
استخدم `txn_id` خاصاً بك	لضمان idempotency.
اشترك في `transaction.created` و`transaction.status.updated` معاً	لالتقاط تغييرات الحالة غير المتزامنة (مثل نتائج مراجعة المحلل).
حدِّد حدود القواعد بعناية	الحدود المنخفضة = تنبيهات أكثر، والحدود المرتفعة = مخاطر أكثر تفوتك. راجع احتساب درجات المخاطر.
راقب عدد مرات تشغيل القواعد في وحدة التحكم	لاكتشاف القواعد التي لا تعمل أبداً (بسبب سوء الإعداد) أو التي تعمل على كل شيء (لأنها فضفاضة أكثر من اللازم).
اختبر القواعد في وضع TEST قبل التشغيل الفعلي	راجع القواعد.

حدود المعدل

راجع تحديد معدل الطلبات. يُعد إنشاء المعاملة أحد endpoint الأعلى من حيث معدل معالجة الطلبات. تبلغ الحدود المعتادة مئات الطلبات في الثانية. توخَّ الحذر عند إرسال دفعات الطلبات.

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

المعاملات

المرجع الكامل لـ payload.

القواعد

كيفية تقييم القواعد.

webhook

كتالوج الأحداث.

استكشاف الأخطاء وإصلاحها

أكثر مشكلات التكامل شيوعاً.

البدء

الميزات

المرجع

Console

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

البنية

المصادقة

إرسال معاملة

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

Idempotency

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

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

Webhooks

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

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

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

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

حدود المعدل

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

المعاملات

القواعد

webhook

استكشاف الأخطاء وإصلاحها

​البنية

​المصادقة

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

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

​Idempotency

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

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

​Webhooks

​التعامل مع الحالات

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

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

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

​حدود المعدل

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

المعاملات

القواعد

webhook

استكشاف الأخطاء وإصلاحها

البنية

المصادقة

إرسال معاملة

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

Idempotency

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

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

Webhooks

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

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

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

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

حدود المعدل

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