> ## 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: الحمولة ونموذج البيانات

> أرسل المعاملات لمراقبتها في الوقت الفعلي مع Didit، مع الأطراف وطرق الدفع والجهاز والخصائص المخصصة. 1,000 شهرياً مشمولة، ثم $0.001 لكل عملية.

قدّم المعاملات إلى Didit عبر واجهة [إنشاء معاملة](https://docs.didit.me/ar/management-api/transactions/create.md) API. تتضمن كل معاملة بيانات منظَّمة عن الأطراف والدفع والسياق، يقيّمها محرك القواعد في الوقت الفعلي.

> [!TIP]
>
> عندما تنشأ المعاملة على جهاز المستخدم النهائي، مثل سحب عملة مشفرة أو دفع داخل التطبيق، فكّر في [إرسال المعاملات عبر SDK](https://docs.didit.me/ar/transaction-monitoring/sdk-transaction-submission.md): يحلّ 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 | معرّفك لهذا الطرف، ويربط المعاملة بـ[مستخدم](https://docs.didit.me/ar/management-api/users/list.md) أو [ملف تعريف شركة](https://docs.didit.me/ar/business-verification/business-profiles.md) |
| `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` ومسار إثبات الملكية. راجع [المحافظ ذاتية الاستضافة المعلنة](https://docs.didit.me/ar/transaction-monitoring/travel-rule.md#المحافظ-ذاتية-الاستضافة-المُصرَّح-بها).

بالنسبة للمعاملات بالعملات المشفرة، ضمّن عناوين المحافظ في `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 |

> [!NOTE]
>
> **لا يتم استنتاج** `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`. يمكن للقواعد الإشارة إلى هذه الحقول في شروطها، وهذا مفيد لتمرير سياق خاص بالعمل، مثل فئة المنتج أو معرّف التاجر أو القناة.

```json theme={null}
"custom_properties": {
  "product_category": "electronics",
  "merchant_id": "MER456",
  "channel": "mobile_app"
}
```

في شروط القواعد، أشِر إلى كل مفتاح بمسار الحقل `custom_values.<key>`، فمثلاً الـ payload أعلاه يطابق `custom_values.product_category eq "electronics"`. في منشئ القواعد في Console، تظهر المفاتيح التي وردت في المعاملات المستلمة مؤخراً في محدد حقول الشرط ضمن **الخصائص المخصصة**، ويتيح لك **أدخل خاصية مخصصة** في المجموعة نفسها كتابة أي مفتاح يدوياً (مع مراعاة حالة الأحرف). راجع [القواعد واحتساب الدرجات](https://docs.didit.me/ar/transaction-monitoring/rules.md#الإشارة-إلى-الخصائص-المخصصة) للتفاصيل.

## نموذج الطلب

```bash theme={null}
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](https://docs.didit.me/ar/management-api/transactions/create.md) للاطلاع على مخطط الطلب والاستجابة الكامل، و[مرجع مخطط الاستجابة](https://docs.didit.me/ar/transaction-monitoring/response-schema.md) للاطلاع على جولة موضحة لنموذج الـ 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 للمعاملات.

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

صفِّ [قائمة المعاملات](https://docs.didit.me/ar/management-api/transactions/list.md) باستخدام `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}/`](https://docs.didit.me/ar/management-api/transactions/get) باستخدام `uuid` من الاستجابة الأولى، أو استخدم `transaction_id` (وهو uuid الخاص بـ Didit) الذي يحمله webhook الحدث `transaction.created` بجانب `txn_id` الخاص بك.
أنشئ `txn_id` دائماً من جهتك (مثلاً معرّف قاعدة بيانات المعاملات لديك، أو UUID، أو تجزئة حتمية).

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

مرّر `txn_date` بتاريخ في الماضي لاستيعاب المعاملات التاريخية. يستمر تقييم القواعد افتراضياً، واستخدم استيراد CSV من لوحة التحكم مع وضع الإدخال الجاف إذا أردت تخطي تقييم القواعد أثناء التحميل الجماعي للبيانات التاريخية. راجع [دليل التكامل](https://docs.didit.me/ar/transaction-monitoring/integration-guide.md#استيعاب-البيانات-التاريخية).

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

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

> [card] [مخطط الاستجابة](https://docs.didit.me/ar/transaction-monitoring/response-schema.md)
>
> حمولة الاستجابة الكاملة مع الشروح.

> [card] [فحص العملات الرقمية](https://docs.didit.me/ar/transaction-monitoring/aml-screening.md)
>
> فحص المحافظ والمعاملات تلقائياً للمعاملات بالعملات الرقمية.

> [card] [Travel Rule](https://docs.didit.me/ar/transaction-monitoring/travel-rule.md)
>
> إرفاق بيانات الامتثال لـ Travel Rule بتحويلات الأصول الافتراضية.

> [card] [إثراء بيانات IP](https://docs.didit.me/ar/transaction-monitoring/ip-enrichment.md)
>
> السياق المستمد من عنوان IP المتاح للقواعد.

> [card] [مرجع API](https://docs.didit.me/ar/management-api/transactions/create.md)
>
> مخطط الطلب الكامل لنقطة إنشاء المعاملة.


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