إرسال المعاملات عبر API: الحمولة ونموذج البيانات

قدّم المعاملات إلى Didit عبر واجهة إنشاء معاملة API. تتضمن كل معاملة بيانات منظَّمة عن الأطراف والدفع والسياق، يقيّمها محرك القواعد في الوقت الفعلي.

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

فئات المعاملات

لكل معاملة transaction_category يحدد كيف تعالجها القواعد والتحليلات:

الفئة	الوصف
`finance`	معاملة مالية قياسية (إيداع، أو سحب، أو تحويل)
`kyc`	حدث متعلق بالتحقق من الهوية
`travel_rule`	تحويل أصول افتراضية يتطلب الامتثال لـ Travel Rule
`user_event`	حدث مخصص للمنصة (تسجيل دخول، أو تغيير في الملف الشخصي، إلخ)
`gambling_bet`	رهان أو وضع رهان في الألعاب
`gambling_limit_change`	تغيير في حد إيداع اللاعب أو خسارته أو رهانه
`gambling_bonus_change`	منح المكافأة أو استردادها أو مصادرتها
`audit_trail_event`	حدث تدقيق للنظام أو للامتثال

تفاصيل المعاملة

يحمل كائن transaction_details البيانات المالية:

الحقل	النوع	الوصف
`direction`	string	`inbound` أو `outbound`
`amount`	string	قيمة المعاملة كسلسلة عشرية (مثل `"1500.50"`)
`currency`	string	رمز العملة ISO (مثل `USD` و`EUR` و`BTC`)
`currency_kind`	string	`fiat` أو `crypto` (الاسم البديل `currencyType`)؛ يحدد ما إذا كان فحص العملات المشفرة سيُفعَّل
`action_type`	string	تسمية الإجراء التي يحددها المزوّد (مثل `deposit` و`withdrawal` و`purchase`)
`payment_details`	string	وصف نصي حر للدفعة (مثل `"Bank transfer from ABC Corp"`)
`payment_reference_id`	string	معرّف مرجعي خارجي للدفعة. لفحص العملات المشفرة بعد التحويل، استخدم تجزئة المعاملة على البلوكتشين.

الطرف المعني والطرف المقابل

لكل معاملة طرف معني (إلزامي) وطرف مقابل (اختياري). يستخدم الطرفان نموذج الطرف نفسه:

الحقل	النوع	الوصف
`entity_type`	string	`person` أو `company`
`vendor_data`	string	معرّفك لهذا الطرف، ويربط المعاملة بـمستخدم أو ملف تعريف شركة
`full_name`	string	الاسم الكامل للطرف
`first_name`	string	الاسم الأول
`last_name`	string	اسم العائلة
`date_of_birth`	string	تاريخ ISO (مثل `1990-01-15`)
`country_code`	string	رمز الدولة ISO 3166-1 alpha-2
`address`	object or string	عنوان منظَّم يتضمن `street` و`city` و`state` و`country` و`postal_code`. ويقبل أيضاً نصاً عادياً، مثل عنوان محفظة لطرف مقابل في عملة مشفرة، ويحفظه Didit دون تغيير على الطرف.

يشتق Didit قيمة country_code للطرف من address.country عندما يكون address كائناً. وعندما يكون address نصاً، تعود قيمة country_code لذلك الطرف null. عندما يطابق vendor_data مستخدماً أو شركةً موجودةً، يربط Didit المعاملة تلقائياً بملف تعريف ذلك الكيان، ما يتيح تقييم القواعد عبر الجلسات وفحوصات وتيرة المعاملات. وفي الاستجابة، يُعاد الطرفان في المصفوفة parties بالدورين APPLICANT وCOUNTERPARTY.

طرق الدفع

أرفق payment_method بكل طرف لوصف أداة الدفع في ذلك الجانب:

الحقل	النوع	الوصف
`method_type`	string	`bank_card` أو `bank_account` أو `e_wallet` أو `crypto_wallet` أو `unhosted_wallet` أو `other` (الاسم البديل `type`)؛ وتُقبل `ewallet` و`card` و`crypto` كأسماء بديلة، والقيمة غير المعروفة تُخزَّن كـ `other`
`account_id`	string	رقم الحساب، أو عنوان المحفظة، أو رمز البطاقة
`issuing_country`	string	الدولة التي أصدرت أداة الدفع

في معاملات travelRule، تعلن طريقة الدفع الخاصة بالطرف المقابل مع method_type: "unhosted_wallet" (الاسم البديل type) أن محفظة الطرف المقابل ذاتية الاستضافة. عندما يكون Travel Rule مفعّلاً، ولا يقل المبلغ بعملة التطبيق الافتراضية عن threshold_amount، تنتقل الحوالة مباشرة إلى UNCONFIRMED_OWNERSHIP ومسار إثبات الملكية. راجع المحافظ ذاتية الاستضافة المعلنة. بالنسبة للمعاملات بالعملات المشفرة، ضمّن عناوين المحافظ في account_id واضبط currency_kind على crypto ليعمل فحص البلوكتشين تلقائياً. يحدد الاتجاهُ المحفظةَ التي تُفحص: يستخدم الفحص المسبق للوارد محفظةَ المُرسِل في counterparty.payment_method.account_id، ويستخدم فحص الصادر محفظةَ الوجهة في counterparty.payment_method.account_id. وإذا أرسلت تجزئة البلوكتشين في transaction_details.payment_reference_id، يتطلب فحص المعاملة الواردة عنوان الإيداع الخاص بخدمتك في subject.payment_method.account_id، بينما يتطلب فحص المعاملة الصادرة محفظةَ الوجهة في counterparty.payment_method.account_id.

تجاوز فحص العملات المشفرة

استخدم include_crypto_screening على المستوى الأعلى في الطلب لتجاوز الإعداد الافتراضي المضبوط في المعاملات > الإعدادات في وحدة التحكم:

القيمة	الوصف
`true`	فرض فحص العملات المشفرة لهذه المعاملة
`false`	تخطي فحص العملات المشفرة لهذه المعاملة
غير مُدرج أو `null`	استخدام الإعداد الافتراضي على مستوى التطبيق

سياق الجهاز

أضف معلومات الجهاز إلى الطرف المعني (واختيارياً إلى الطرف المقابل) لتفعيل قواعد ذكاء الجهاز. حقل الطلب هو device_context في كل طرف، والاسم البديل بصيغة camelCase وهو device مقبول أيضاً، وهو ما يستخدمه التنسيق السلكي لـ SDK. تعيد الاستجابة الحقل كـ device في كل طرف ضمن المصفوفة parties.

الحقل	النوع	الوصف
`device_context.fingerprint`	نص	بصمة الجهاز الفريدة
`device_context.persistent_device_id`	نص	معرّف جهاز ثابت عبر الجلسات (مخطط البصمة الإصدار 2)
`device_context.user_agent`	نص	سلسلة وكيل المستخدم الخاصة بالمتصفح أو التطبيق
`device_context.browser_family`	نص	عائلة المتصفح (مثل `Chrome` و`Firefox` و`Safari`). يجب إرسالها صراحةً، فهي لا تُستنتج من `user_agent`. تُفعّل قواعد مثل `subject_browser_family`.
`device_context.browser_version`	نص	إصدار المتصفح (مثل `131.0`). يجب إرسالها صراحةً.
`device_context.platform`	نص	معرّف المنصة (`web` و`ios` و`android` و`macos` و`windows` و`linux`). يجب إرسالها صراحةً، فهي لا تُستنتج من `user_agent`. تُفعّل قواعد مثل `subject_platform`.
`device_context.os_family`	نص	عائلة نظام التشغيل (مثل `iOS` و`Android` و`Windows`)
`device_context.os_version`	نص	إصدار نظام التشغيل
`device_context.accept_language`	نص	قيمة ترويسة Accept-Language (مثل `en-US,en;q=0.9`). في مسار SDK تُجمع تلقائياً.
`device_context.session_id`	نص	معرّف الجلسة الحالية للمستخدم. يُخزَّن في البيانات الوصفية. الاسم البديل بصيغة CamelCase: `sessionId`.
`device_context.session_age_ms`	رقم	عمر جلسة المستخدم بالمللي ثانية وقت المعاملة. تُفعّل قواعد مثل `subject_session_age_ms`.
`device_context.network_context.ip_address`	نص	عنوان IP للعميل
`device_context.network_context.ip_country_code`	نص	الدولة المحددة جغرافياً لعنوان IP (ISO 3166-1 alpha-3)
`device_context.network_context.latitude`	رقم	خط العرض الجغرافي لعنوان IP
`device_context.network_context.longitude`	رقم	خط الطول الجغرافي لعنوان IP

لا يتم استنتاج browser_family وplatform من user_agent. يجب إرسالهما كمفاتيح علوية صريحة داخل device_context لكي تعمل قواعد ذكاء الجهاز. إذا كنت تعتمد على SDK من Didit، فيتم جمع هذه الحقول تلقائياً.

يُقبل الاسم البديل بصيغة CamelCase لكل حقل: userAgent وbrowserFamily وbrowserVersion وosFamily وosVersion وacceptLang وsessionId وsessionAgeMs. ويقبل الكائن الفرعي network_context الأسماء البديلة ip وcountryCode3 وlat وlon، كما يُدمج الكائن ipInfo على المستوى الأعلى في network_context. يتيح سياق الجهاز قواعد مثل اكتشاف تعدد الحسابات (البصمة نفسها عبر أطراف مختلفة)، واكتشاف مزيج متصفح جديد وعنوان IP جديد، واكتشاف تحويل ذي قيمة عالية بعمر جلسة قصير، واحتساب درجة المخاطر بناءً على الموقع.

الخصائص المخصصة

أضف أي أزواج مفتاح-قيمة إضافية في الكائن custom_properties. يمكن للقواعد الإشارة إلى هذه الحقول في شروطها، وهذا مفيد لتمرير سياق خاص بالعمل، مثل فئة المنتج أو معرّف التاجر أو القناة.

"custom_properties": {
  "product_category": "electronics",
  "merchant_id": "MER456",
  "channel": "mobile_app"
}

في شروط القواعد، أشِر إلى كل مفتاح بمسار الحقل custom_values.<key>، فمثلاً الـ payload أعلاه يطابق custom_values.product_category eq "electronics". في منشئ القواعد في Console، تظهر المفاتيح التي وردت في المعاملات المستلمة مؤخراً في محدد حقول الشرط ضمن الخصائص المخصصة، ويتيح لك أدخل خاصية مخصصة في المجموعة نفسها كتابة أي مفتاح يدوياً (مع مراعاة حالة الأحرف). راجع القواعد واحتساب الدرجات للتفاصيل.

نموذج الطلب

curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "TXN-20260410-001",
    "transaction_at": "2026-04-10T15:30:00Z",
    "transaction_category": "finance",
    "transaction_details": {
      "direction": "outbound",
      "amount": "1500.50",
      "currency": "EUR",
      "currency_kind": "fiat",
      "action_type": "withdrawal"
    },
    "subject": {
      "entity_type": "person",
      "vendor_data": "user-123",
      "full_name": "John Doe",
      "country_code": "US",
      "payment_method": {
        "method_type": "bank_account",
        "account_id": "DE89370400440532013000",
        "issuing_country": "DE"
      }
    },
    "counterparty": {
      "entity_type": "company",
      "full_name": "John Doe",
      "country_code": "GB"
    },
    "custom_properties": {
      "order_id": "ORD-7891"
    }
  }'

الاستجابة

تعيد واجهة API المعاملة التي تم إنشاؤها مع نتائج التقييم الأولية:

الحقل	النوع	الوصف
`uuid`	نص	المعرّف الفريد للمعاملة في Didit
`txn_id`	نص	معرّف المعاملة الذي قدمته
`status`	نص	`APPROVED` أو `IN_REVIEW` أو `DECLINED` أو `AWAITING_USER`
`score`	رقم	مجموع درجات المخاطر من جميع القواعد المطابقة
`severity`	نص	أعلى مستوى خطورة للقواعد المطابقة (`LOW` و`MEDIUM` و`HIGH` و`CRITICAL`)
`decision_reason_code`	نص	سبب قرار الحالة بصيغة يمكن للآلة قراءتها
`decision_reason_label`	نص	وصف القرار بصيغة مفهومة للإنسان

راجع مرجع API للاطلاع على مخطط الطلب والاستجابة الكامل، ومرجع مخطط الاستجابة للاطلاع على جولة موضحة لنموذج الـ payload.

تعيين معاملة لمراجِع

عيّن معاملة معلّقة لعضو في تطبيقك، أو ألغِ تعيينها، باستخدام مفتاح API يملك الإذن write:transactions. يُسجَّل كل تغيير في الجدول الزمني للمعاملة بالحدث TRANSACTION_ASSIGNED.

الاستدعاء	الاستخدام
`POST /v3/transactions/{transaction_uuid}/assign/`	تعيين معاملة واحدة.
`POST /v3/transactions/assign/`	تعيين حتى 500 معاملة لعضو واحد.

يأخذ الاستدعاءان assignee_email، وهو البريد الإلكتروني لعضو في التطبيق سجّل الدخول إلى Didit. أرسل null أو سلسلة فارغة لإلغاء التعيين. ويأخذ الاستدعاء الجماعي أيضاً transaction_ids، وهي قائمة من 1 إلى 500 من معرّفات UUID للمعاملات.

curl -X POST "https://verification.didit.me/v3/transactions/assign/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction_ids": ["<transaction-uuid>"], "assignee_email": "analyst@example.com"}'

يعيد الاستدعاء الفردي uuid وtransaction_number وassignee وchanged (تكون false إذا كانت المعاملة معيّنة بالفعل لهذا المكلَّف)، أو 404 إذا لم تكن المعاملة موجودة في التطبيق. ويعيد الاستدعاء الجماعي transactions (عنصر واحد بالشكل أعلاه لكل معاملة)، وupdated_count وnot_found_transaction_ids. صفِّ قائمة المعاملات باستخدام assignee، وهي قائمة مفصولة بفواصل تُطابق أي قيمة فيها: me أو unassigned أو rules (قرّرتها القواعد وحدها دون تدخل مراجِع) أو بريد إلكتروني لعضو.

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 دائماً من جهتك (مثلاً معرّف قاعدة بيانات المعاملات لديك، أو UUID، أو تجزئة حتمية).

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

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

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

القواعد والتقييم

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

مخطط الاستجابة

حمولة الاستجابة الكاملة مع الشروح.

فحص العملات الرقمية

فحص المحافظ والمعاملات تلقائياً للمعاملات بالعملات الرقمية.

Travel Rule

إرفاق بيانات الامتثال لـ Travel Rule بتحويلات الأصول الافتراضية.

إثراء بيانات IP

السياق المستمد من عنوان IP المتاح للقواعد.

مرجع API

مخطط الطلب الكامل لنقطة إنشاء المعاملة.

البدء

الميزات

المرجع

Console

إرسال المعاملات عبر API: الحمولة ونموذج البيانات

فئات المعاملات

تفاصيل المعاملة

الطرف المعني والطرف المقابل

طرق الدفع

تجاوز فحص العملات المشفرة

سياق الجهاز

الخصائص المخصصة

نموذج الطلب

الاستجابة

تعيين معاملة لمراجِع

Idempotency

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

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

القواعد والتقييم

مخطط الاستجابة

فحص العملات الرقمية

Travel Rule

إثراء بيانات IP

مرجع API

​فئات المعاملات

​تفاصيل المعاملة

​الطرف المعني والطرف المقابل

​طرق الدفع

​تجاوز فحص العملات المشفرة

​سياق الجهاز

​الخصائص المخصصة

​نموذج الطلب

​الاستجابة

​تعيين معاملة لمراجِع

​Idempotency

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

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

القواعد والتقييم

مخطط الاستجابة

فحص العملات الرقمية

Travel Rule

إثراء بيانات IP

مرجع API

فئات المعاملات

تفاصيل المعاملة

الطرف المعني والطرف المقابل

طرق الدفع

تجاوز فحص العملات المشفرة

سياق الجهاز

الخصائص المخصصة

نموذج الطلب

الاستجابة

تعيين معاملة لمراجِع

Idempotency

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

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