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

# ربط بيانات المورّد: ربط المعرّفات بالكيانات

> معرّف vendor_data يربط نظامك بـ Didit، فيجمع الجلسات والمعاملات وكيانات المستخدم والشركة في ملف واحد. الدفع لكل استدعاء.

موجّه ربط بيانات المورّد
نسخ الموجّه إلى الحافظة

<pre>
  \`\`\`\`# Goal — link every session, transaction, and entity together using `vendor_data`

  `vendor_data` is the string identifier you choose and pass on every API call to bind it to a persistent [User](https://docs.didit.me/entities/users/overview.md) or [Business](https://docs.didit.me/entities/businesses/overview.md) entity. Get this right once and you never have to re-key history afterwards.

  ## Rules

  * `vendor_data` is **opaque** to Didit. Use your stable internal customer id.
  * Choose one canonical id per entity and never change it. Changing it orphans history under a new entity.
  * Prefix by entity type when convenient (`user_...`, `biz_...`) to avoid collisions in your own code.
  * Keep it under 128 chars, case-sensitive stable. Hard limit is 2000 bytes (UTF-8 encoded) - anything over that is rejected with a 400 rather than accepted.
  * **Never put raw PII in it** — it surfaces in webhooks, logs, and API responses.
  * Uniqueness is per application × entity type. User `user-42` and Business `user-42` are different entities (but don't do this).

  ## Where it goes

  | API | Field |
  | - | - |
  | `POST /v3/session/` | top-level `vendor_data` (KYC and KYB) |
  | `POST /v3/transactions/` | top-level `vendor_data` and `applicant.vendor_data` / `counterparty.vendor_data` |
  | `POST /v3/users/create/` / `POST /v3/businesses/create/` | `vendor_data` |
  | `GET /v3/sessions?vendor_data=...` | query param to retrieve history |
  | `GET /v3/users/{vendor_data}/` / `GET /v3/businesses/{vendor_data}/` | path param |

  ## Pattern — pre-create the entity, then run a session

  ```bash
  # 1) Seed the entity with metadata before any session
  curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "vendor_data": "user-42",
  "display_name": "Jane Doe",
  "metadata": {"tier": "premium", "signup_date": "2026-04-01"}
  }'

  # 2) Run a KYC session linked to the same entity
  curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "workflow_id": "$WORKFLOW_ID",
  "vendor_data": "user-42",
  "callback": "https://myapp.com/return"
  }'

  # 3) Later, retrieve every session for the entity
  curl -G https://verification.didit.me/v3/sessions/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  --data-urlencode "vendor_data=user-42"
  ```

  ## Auto-create semantics

  If you create a session with a new `vendor_data` and no entity exists, Didit creates the entity automatically with `status: ACTIVE` and links the session.

  ## Failure modes

  * Missing `vendor_data` on session create → session is orphaned, won't appear in any entity profile, cannot be filtered by `vendor_data` later (only by `session_id`).
  * Different case (`User-42` vs `user-42`) → two separate entities. Pick a casing convention and stick to it.
  * Same `vendor_data` across staging and prod apps → no collision; `vendor_data` is scoped per application.

  ## Sources of truth

  * /entities/users/operations — full User CRUD
  * /entities/businesses/operations — full Business CRUD
  * /sessions-api/create-session — session body shape
  * /integration/integration-prompt — canonical end-to-end prompt\`\`\`\`
</pre>

الصق في

`vendor_data` هو المعرّف الذي تُمرّره في كل جلسة ومعاملة لربطها بكيان [المستخدم](https://docs.didit.me/ar/entities/users/overview.md) أو [الشركة](https://docs.didit.me/ar/entities/businesses/overview.md). وهو أهم حقل لتجميع الكيانات: إذا أعددته بشكل صحيح، تعمل كل الميزات اللاحقة بسلاسة، مثل سجل الملف الشخصي ومراقبة المعاملات وتطبيق قائمة الحظر ومراقبة AML المستمرة.

## ما هو المعرّف

`vendor_data` هو **سلسلة نصية** تختارها بنفسك. يتعامل معها Didit كمعرّف غير شفاف ولا يفسّر محتواها. من القيم المعتادة:

| نظامك | قيم `vendor_data` المناسبة |
| - | - |
| قاعدة بيانات المستخدمين الداخلية | `user_1234`، و`uuid-v4` للمستخدم |
| معرّف يراه العميل | `CUST-2026-00042`، أو تجزئة البريد الإلكتروني |
| منصة SaaS متعددة المستأجرين | `tenant_acme:user_1234` |
| منصة B2B | `company-hq-global`، و`tax-id-US-123456789` |

> [!WARNING]
>
> لا **تضع** معلومات شخصية قابلة للتحديد (PII) مثل رسائل البريد الإلكتروني وأرقام الهواتف والأرقام الضريبية الخام مباشرةً في `vendor_data`. استخدم التجزئة (hash) أو أضف بادئة إليها. يظهر `vendor_data` في حمولات webhook ويُحفظ إلى أجل غير مسمى طالما الكيان موجود.

## كيف يربط العناصر ببعضها

```mermaid theme={null}
flowchart TD
    subgraph YourSystem["Your system"]
      Customer["Customer record: user-42"]
    end
    subgraph Didit["Didit platform"]
      Entity["User entity (vendor_data = user-42)"]
      S1[Session #1]
      S2[Session #2]
      T1[Transaction #1]
      T2[Transaction #2]
      F[Face biometric]
    end
    Customer -.vendor_data.-> Entity
    S1 --> Entity
    S2 --> Entity
    T1 --> Entity
    T2 --> Entity
    F --> Entity
```

عند إرسال جلسة أو معاملة مع قيمة `vendor_data`:

1. يبحث Didit عن الكيان في تطبيقك باستخدام `vendor_data` هذا.
2. إن وُجد الكيان، يُربط الكائن الجديد به.
3. إن لم يوجد، ينشئ Didit الكيان (بالحالة `status: ACTIVE`) ويربط الكائن الجديد به.

ينطبق هذا على:

* `POST /v3/session/`: جلسات التحقق من الهوية (KYC) والتحقق من الشركات (KYB)
* `POST /v3/transactions/`: المعاملات (للمتقدّم بالطلب والطرف المقابل على حد سواء)
* الحقلان `applicant.vendor_data` و`counterparty.vendor_data` داخل حمولات المعاملات

## التفرد والنطاق

`vendor_data` **فريد لكل تطبيق**، وليس فريداً عبر Didit بأكمله:

| النطاق | ضمان التفرد |
| - | - |
| ضمن تطبيق واحد | `vendor_data` فريد لكل نوع كيان (المستخدم والشركة مساحتا أسماء منفصلتان) |
| عبر التطبيقات في مؤسستك | `vendor_data` **غير مشترك**؛ القيمة نفسها في تطبيقين تشير إلى كيانين مختلفين |
| عبر المؤسسات | غير مشترك؛ لكل مؤسسة جداول كيانات خاصة بها |

وهذا يعني أنه يمكنك استخدام `vendor_data` نفسه في التطبيق في البيئة التجريبية وتطبيق الإنتاج دون تعارض، ويمكنك أن تملك مستخدماً `user-42` وشركة `user-42` دون تعارض، وإن كان ذلك غير مستحسن من أجل الوضوح.

## ماذا يحدث إذا أغفلت `vendor_data`

يمكنك إنشاء جلسة دون `vendor_data`. في هذه الحالة:

* لا يُنشأ أي كيان للجلسة.
* تصبح الجلسة يتيمة: لن تظهر في أي ملف شخصي لمستخدم أو شركة.
* لا يمكنك لاحقاً البحث عن الجلسة بواسطة `vendor_data`، بل بواسطة `session_id` فقط.

استخدم هذا النمط فقط للتحققات المجهولة أو لمرة واحدة التي لا تحتاج إلى تجميع الكيانات. أما في كل تكامل يتضمن إعادة التحقق أو المعاملات أو المراقبة المستمرة، فقدّم `vendor_data` دائماً.

## مثال: إنشاء كيان مسبقاً ثم تشغيل الجلسات

```bash theme={null}
# 1. Pre-create the User with initial metadata
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "tier": "premium", "signup_date": "2026-04-01" }
  }'

# 2. Create a User Verification (KYC) session for the same user
curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_kyc_standard",
    "vendor_data": "user-42"
  }'

# 3. Later, submit a transaction tied to the same user
curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "txn_id": "tx-0001",
    "direction": "OUTBOUND",
    "amount": "500.00",
    "currency": "EUR",
    "applicant": { "vendor_data": "user-42" },
    "counterparty": { "name": "Acme Corp" }
  }'
```

تُربط الاستدعاءات الثلاثة كلها بكيان المستخدم نفسه. وعندما تستدعي لاحقاً `GET /v3/users/user-42/`، سترى عدد الجلسات وعدادات الجلسات المقبولة والمرفوضة والمعاملات المرتبطة وأحدث بيانات الملف الشخصي.

## ترحيل المعرّفات الخارجية

إذا كنت تعتمد Didit بعد مزود KYC سابق، فمرّر معرّفات المستخدمين الثابتة الحالية كـ `vendor_data` من اليوم الأول. يسهّل ذلك:

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

## القواعد والاصطلاحات وأفضل الممارسات

| القاعدة | السبب |
| - | - |
| اختر معرّفاً أساسياً واحداً لكل كيان ولا تغيّره أبداً | التغيير ينشئ كياناً جديداً ويترك السجل السابق يتيماً |
| ابدأ قيم `vendor_data` ببادئة حسب نوع الكيان (`user_...`، `biz_...`) | يمنع التعارض العرضي بين الفضاءات داخل كودك |
| حافظ على ثبات `vendor_data` مع مراعاة حالة الأحرف | لا يُطبّع Didit حالة الأحرف |
| اجعل طول `vendor_data` أقل من 128 حرفاً | يناسب فهارس قواعد البيانات بسهولة |
| لا تكشف المعلومات الشخصية الخام أبداً | يظهر `vendor_data` في webhook وسجلات التدقيق واستجابات API |

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

> [card] [نظرة عامة على المستخدمين](https://docs.didit.me/ar/entities/users/overview.md)
>
> تعمّق في كيانات المستخدمين وعملياتها.

> [card] [نظرة عامة على الشركات](https://docs.didit.me/ar/entities/businesses/overview.md)
>
> تعمّق في كيانات الشركات وعملياتها.

> [card] [إنشاء جلسة](https://docs.didit.me/ar/sessions-api/create-session.md)
>
> ابدأ تحققاً لقيمة vendor\_data.

> [card] [إنشاء معاملة](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.