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

# التحقق من الشركات (KYB): دليل التكامل والبنية والأنماط

> تكامل KYB جاهز للإنتاج مع Didit: البنية والجلسات والصفحات المستضافة وwebhook والاستطلاع والقرارات. ابتداءً من $2.00 لكل فحص، حسب الدولة والمستوى.



موجه تكامل KYB
        نسخ الموجّه إلى الحافظة



      
      

\<pre>

\````# Goal — ship a production-ready KYB (business verification) integration

KYB runs through the same `/v3/session/` endpoint as KYC. The session's workflow determines whether it's a KYC or KYB session — pass a KYB workflow id and Didit creates a business session automatically (`session_kind: "business"`).

\## End-to-end flow

\```
You: POST /v3/session/ (KYB workflow_id, vendor_data) → session_id, url, session_token
You: deliver url to the business contact (email / your UI / iframe)
Biz: completes the hosted flow (registry confirm → Key People → documents → AML)
Didit → Webhook: status.updated with session_kind: "business"
You: GET /v3/session/{session_id}/decision/ → full KYB decision
You: branch on decision.status ("Approved" / "Declined" / "In Review" / "Resubmitted")
\```

\## Create a KYB session

\```bash
curl -X POST https://verification.didit.me/v3/session/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflow_id": "$KYB_WORKFLOW_ID",
"vendor_data": "biz-acme",
"callback": "https://myapp.com/kyb/return",
"metadata": {"plan": "growth", "country": "GBR"}
}'
\```

Recommended fields:

\- `workflow_id` — references your KYB workflow.
\- `vendor_data` — your business id; binds the session to a [Business entity](/entities/businesses/overview).
\- `callback` — where to redirect the user after completion.
\- `metadata` — JSON attached to the session for your own reporting.

\## Webhook events for KYB

\| Event | Trigger |
\|---|---|
\| `status.updated` (with `session_kind === "business"`) | KYB session status changed. Follow this event for progress. |
\| `data.updated` (with `session_kind === "business"`) | A reviewer edited registry data or Key People in the console, or the registry reported a change (registry monitoring). Not sent for document uploads or Key People submissions. |
\| `business.status.updated` | Linked Business entity status changed |
\| `business.data.updated` | Linked Business entity profile / counters changed |

Subscribe via `POST /v3/webhook/destinations/` with `webhook_version: "v3"`. Verify the `X-Signature-V2` header (HMAC-SHA256 of canonical JSON). De-dupe on `event_id`. Respond within 5 seconds.

\## KYB decision shape (V3 plural arrays)

\```bash
curl https://verification.didit.me/v3/session/$SESSION_ID/decision/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

Key V3 arrays you'll iterate:

\| Array | Holds |
\|---|---|
\| `key_people_checks[]` | UBOs, shareholders, directors, officers — bucketed into `registry` (from the registry lookup) and `submitted` (what the business confirmed). Plus a `ubo_kyc_summary` rollup. |
\| `document_verifications[]` | Each item has `status`, `node_id`, `items[]` (signed `file_url` + OCR extract), `groups`, `required_groups`. |
\| `aml_screenings[]` | Company AML and per-person AML hits. |

The KYB-specific features are `KYB_REGISTRY`, `AML`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`. Statuses are the exact labels `"Not Finished"`, `"Approved"`, `"Declined"`, `"In Review"`, `"Resub Requested"`.

\## Apply-decision logic

\```ts
switch (decision.status) {
case "Approved":   await onboardBusiness(decision); break;
case "Declined":   await logRejection(collectWarnings(decision), decision); break; // warnings[] tags on each feature array
case "In Review":  await markPending(decision); break; // wait for next webhook
case "Resubmitted":await notifyBusiness(decision); break; // business needs to re-upload
case "Awaiting User": await pingChildPersonForKyc(decision); break; // child Key People KYC pending
}
\```

See /business-verification/statuses for the full state machine.

\## Resubmission flow

When a session transitions to `Resubmitted` (or a feature to `Resub Requested`, or a feature is marked for resubmission), re-deliver the same `url` — the hosted flow resumes at the resubmission step. To re-verify a specific Key Person, resubmit that person's child KYC session; the parent `kyb_key_people` re-aggregates automatically.

\## Key People child KYC

If your KYB workflow has KYC required for some roles, each person triggers a child KYC session automatically. While any child is in progress, the parent's `kyb_key_people` status is `Awaiting User`. Configure per-role required/skippable behaviour at *Workflows → [KYB workflow] → Key People*. A child session expires after the session expiration time of the KYC workflow its role is mapped to, not the KYB session's. A party whose session was deleted, or whose link expired before the person started it, is reissued with `POST /v3/session/{session_id}/kyb/parties/{party_uuid}/regenerate/`.

\## Failure modes

\| Scenario | Response |
\|---|---|
\| Invalid `workflow_id` | `400 Bad Request` |
\| Wrong workflow type (KYC instead of KYB) | Session is created but runs KYC steps — verify the workflow's `workflow_type` is `"kyb"` |
\| Duplicate `vendor_data` | A new session is created — that's by design for re-KYB |
\| Company country outside the workflow's allowed countries | The registry check raises the `KYB_COUNTRY_RESTRICTED` warning |
\| Registry provider outage during company search | `502` with `code: "kyb_registry_provider_unavailable"`. Not billed. In Didit's hosted flow, the business is automatically offered manual company entry instead of a retry-only error. |
\| Rate limit | `429` with `Retry-After` header |

\## Sources of truth

\- /sessions-api/create-session — request body schema
\- /business-verification/response-schema — KYB decision payload
\- /business-verification/statuses — feature state machine
\- /business-verification/webhooks — KYB-specific event catalog
\- /entities/businesses/data-model — Business entity schema
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

الصق في

يكمّل هذا الدليل [دليل البدء السريع](https://docs.didit.me/ar/business-verification/quickstart.md). ويغطي البنية، وكل قرارات التكامل، وأنماط التشغيل التي تجعل التحقق من الشركات موثوقاً في بيئة الإنتاج.## البنية```mermaid theme={null}
sequenceDiagram
    participant You as Your platform
    participant Didit as Didit API
    participant Biz as Business contact
    participant Webhook as Your webhook endpoint

    You->>Didit: POST /v3/session/ (workflow_id, vendor_data)
    Didit-->>You: session_id, url, token
    You->>Biz: Deliver hosted verification URL (your email/flow)
    Biz->>Didit: Completes KYB hosted flow
    Didit->>Didit: Registry lookup, AML screening, OCR
    Didit->>Webhook: status.updated (session_kind: business)
    You->>Didit: GET /v3/session/{id}/decision/
    Didit-->>You: Full KYB decision payload
    You->>You: Onboard / reject / escalate based on status
```## المصادقةتتطلب جميع الطلبات رأس `x-api-key` مع مفتاح API الخاص بتطبيقك. راجع [مصادقة API](https://docs.didit.me/ar/getting-started/api-authentication.md) لتدوير المفاتيح وفصل البيئات والنطاقات.## إنشاء الجلسةنقطة نهاية واحدة: `POST /v3/session/`. يحدد نوع سير العمل ما إذا كانت الجلسة KYC أو KYB، ولا حاجة إلى حقل صريح باسم "business".**الحقول الموصى بها عند الإنشاء:**| الحقل | الغرض |
| - | - |
| `workflow_id` | مطلوب. يشير إلى سير عمل KYB الخاص بك. |
| `vendor_data` | معرّفك للشركة. يربط الجلسة بـ[كيان الشركة](https://docs.didit.me/ar/entities/businesses/overview.md). |
| `callback_url` | اختياري. الصفحة التي يُعاد توجيه المستخدم إليها بعد الإكمال. |
| `expected_details` | اختياري. `{ company_name, registry_country, registration_number }`. يملأ بحث سجل الشركات مسبقاً: يُحدَّد بلد التأسيس ويُقفل (`registry_country` بصيغة `XX`، أو `XX-YY` للسجلات على مستوى الولايات، مثل `US-CA`)، وتُملأ حقلا اسم الشركة ورقم التسجيل، ويُنفَّذ البحث المحدد تلقائياً، مع دمج المعرفين معاً عند توفرهما. تعبئة مسبقة فقط، ولا تُنتج الاختلافات أي تحذيرات. |
| `metadata` | اختياري. JSON يُرفق بالجلسة. |المخطط الكامل: [إنشاء جلسة](https://docs.didit.me/ar/sessions-api/create-session.md).## تسليم الرابط المستضافالحقل `url` في الاستجابة هو رابط تحقق مستضاف. خيارات التسليم:- أرسله بالبريد الإلكتروني من منصتك.
- ضمّنه في واجهة التسجيل لديك كرابط.
- افتحه في webview داخل التطبيق (iOS / Android / React Native).يمكنك **تخصيص** تجربة الصفحة المستضافة، ومنها الشعار واللون والنطاق وقوالب البريد الإلكتروني، عبر [العلامة البيضاء](https://docs.didit.me/ar/console/white-label.md).## الاستطلاع مقابل webhooksتُعد webhooks النمط الموصى به. يرسل Didit أحداث الإكمال بطريقة POST إلى نقطة النهاية التي اشتركت فيها فور انتهاء المعالجة.الاستطلاع مدعوم للتطوير، أو عندما تكون وجهة webhook غير قابلة للوصول:* استطلع `GET /v3/session/{id}/decision/` بتأخير متزايد أسياً (كل 10 ثوانٍ في البداية، ويصل إلى 60 ثانية).
* أوقف الاستطلاع عندما تكون `status` إحدى القيم `"Approved"` أو `"Declined"` أو `"In Review"`.> [!WARNING]
>
> قد يؤدي الاستطلاع بتكرار عالٍ إلى الوصول إلى [حدود المعدل](https://docs.didit.me/ar/integration/rate-limiting.md). فضّل webhooks دائماً في بيئة الإنتاج.## التعامل مع webhooksاشترك في الأحداث التي تهمك. تغطي الأحداث نفسها KYC وKYB، مع `session_kind: "business"` داخل payload لتحديد أحداث جلسات الشركات:- `status.updated`: تغيّرت حالة الجلسة. صفِّ بـ `session_kind === "business"` لجلسات KYB.
- `data.updated`: قام مراجع بتعديل بيانات السجل أو الأشخاص الرئيسيين في Business Console، أو أبلغ السجل عن تغيير. لا يُرسل هذا الحدث عندما يرفع المتقدم مستنداً أو يرسل الأشخاص الرئيسيين، لذا تابع `status.updated` في تلك الحالة. ينطبق الفلتر نفسه `session_kind`.
- `business.status.updated` / `business.data.updated`: تغيّر [كيان الشركة](https://docs.didit.me/ar/entities/businesses/overview.md) المرتبط.الكتالوج الكامل للأحداث: [webhooks الخاصة بـ KYB](https://docs.didit.me/ar/business-verification/webhooks.md). التحقق من التوقيع وسلوك إعادة المحاولة: [مرجع webhooks](https://docs.didit.me/ar/integration/webhooks.md).## التعامل مع القرارات```typescript theme={null}
switch (decision.status) {
  case 'Approved':
    await onboardBusiness(decision);
    break;
  case 'Declined':
    // The KYB decision has no single reason code: collectWarnings is your helper
    // that flattens warnings[] from registry_checks, document_verifications,
    // key_people_checks and aml_screenings
    await logRejection(collectWarnings(decision), decision);
    break;
  case 'In Review':
    // Wait for analyst decision — another webhook will fire
    await markPending(decision);
    break;
  case 'Resubmitted':
    // The business was asked to re-upload a document
    await notifyBusiness(decision);
    break;
}
```راجع [حالات KYB](https://docs.didit.me/ar/business-verification/statuses.md) للاطلاع على آلة الحالات الكاملة، و[تحذيرات KYB](https://docs.didit.me/ar/business-verification/warnings.md) للوسوم التي تفسر القرار.## تدفق إعادة الإرسالعندما تنتقل جلسة التحقق من الشركات (KYB) إلى الحالة `Resubmitted` (أو عندما تُعلَّم ميزة للإرسال من جديد)، تحتاج الشركة إلى رفع بيانات مصححة أو إضافية.يمكنك:- **إعادة إرسال** الرابط `url` نفسه. يواصل التدفق المستضاف من النقطة التي تلزم فيها إعادة الإرسال.
- **إعادة إصدار رابط شخص رئيسي غير صالح**: يحصل الطرف الذي حُذفت جلسة KYC الفرعية الخاصة به، أو انتهت صلاحيتها قبل أن يبدأها الشخص، على جلسة جديدة باستخدام [إعادة إنشاء جلسة KYC للأشخاص الرئيسيين](https://docs.didit.me/ar/sessions-api/regenerate-kyb-party.md).
- **فتح [حالة](https://docs.didit.me/ar/transaction-monitoring/cases.md)** في Business Console لتتبع التواصل المتبادل داخلياً.## تنفيذ الخطوات من واجهتك الأماميةيمكن أيضاً تشغيل خطوتي المستندات والأشخاص الرئيسيين من خادمك باستخدام مفتاح API الخاص بك، فتحتفظ بواجهة المستخدم بينما يتولى Didit التحقق والقرار.
يقتصر كل استدعاء على جلسة KYB، ويحتاج إلى الإذن `write:businesses` (وقراءة الأطراف المستخرجة تقبل أيضاً `read:businesses` أو `read:sessions`)، وينفذ الفحوصات نفسها، ويطبق الفوترة نفسها، ويتيح التقدم في الخطوة نفسها كما في الصفحة المستضافة.1) [رفع المستندات المؤسسية](https://docs.didit.me/ar/sessions-api/kyb-upload-documents.md) بينما تكون الجلسة في خطوة مستندات KYB.
2) [قراءة الأطراف المذكورة في المستندات](https://docs.didit.me/ar/sessions-api/kyb-extracted-parties.md)، بما في ذلك المساهمون ونسب الملكية، وعرضها على المتقدم.
3) [إنشاء](https://docs.didit.me/ar/sessions-api/kyb-create-party-draft.md) و[تعديل](https://docs.didit.me/ar/sessions-api/kyb-update-party-draft.md) و[حذف](https://docs.didit.me/ar/sessions-api/kyb-delete-party-draft.md) [مسودات الأطراف](https://docs.didit.me/ar/sessions-api/kyb-list-party-drafts.md). المسودة غير مُعلنة ولا تكلّف شيئاً.
4) [إرسال المسودات](https://docs.didit.me/ar/sessions-api/kyb-submit-parties.md). يحدد Didit الأطراف الذين يجب التحقق منهم، وينشئ جلسة KYC لكل منهم، ويعيد `kyc_session_url` الخاص بها لترسله أو تضمّنه.
5) اقرأ القرار الموحد من الجلسة، كما في التدفق المستضاف.يُرجع الاستدعاء الذي يُجرى والجلسة في خطوة أخرى الخطأ `409 kyb_step_mismatch` مع الخطوة التي توجد فيها، وتُرجع الجلسة المكتملة الخطأ `409 kyb_session_not_writable`.## تجميع ملف الشركةإذا مررت `vendor_data` عند إنشاء الجلسة، يجمع Didit كل الجلسات الخاصة بتلك الشركة في [كيان شركة](https://docs.didit.me/ar/entities/businesses/overview.md) واحد. استخدم الخريطة `features` في الكيان للإجابة عن سؤال "هل هذه الشركة موثقة بالكامل الآن؟" دون المرور على الجلسات واحدة تلو الأخرى.الفوائد:- تُلحق تدفقات إعادة التحقق الدورية من الشركات بالملف نفسه.
- تحمل المعاملات المراقبة بالقيمة `vendor_data` نفسها سياق المخاطر الخاص بالشركة.
- يُربط المستفيدون الحقيقيون والمسؤولون بكيانات المستخدمين، فتُنشأ علاقات بين الكيانات.## أفضل الممارسات| الممارسة | السبب |
| - | - |
| مرّر دائماً `vendor_data` | بدونه تصبح الجلسة يتيمة ولا يمكن تجميعها. |
| استخدم webhooks بدلاً من الاستطلاع | زمن استجابة أقل، ولا ضغط على حد المعدل. |
| تحقّق من توقيعات webhook | يمنع الأحداث المزيفة. |
| خزّن `session_id` في نظامك | مطلوب لاسترجاع القرار وإنشاء ملفات PDF. |
| ضع وسوماً للجلسات باستخدام `metadata` | يُبسّط إعداد التقارير وتصحيح الأخطاء. |
| أعدّ سير عمل للاختبار | استخدم سير عمل في البيئة التجريبية لاختبار التكامل قبل الإنتاج. |## معالجة الأخطاء| السيناريو | الاستجابة |
| - | - |
| `workflow_id` غير صالح | `400 Bad Request` |
| جلسة مكررة بالقيمة نفسها لـ `vendor_data` | تُنشأ جلسة جديدة، وهذا مقصود لأن إعادة التحقق متوقعة. |
| دولة الشركة خارج الدول المسموح بها في سير العمل | يُصدر فحص السجل التحذير `KYB_COUNTRY_RESTRICTED`. |
| انقطاع مزوّد السجل أثناء البحث عن الشركة | يُرجع `POST /v3/kyb/search/` الاستجابة `502` مع `code: "kyb_registry_provider_unavailable"`. لا تُحتسب رسوم على هذا الطلب. أعد المحاولة، أو تفرّع حسب `code` لعرض خيار إدخال الشركة يدوياً. في تدفق التحقق المستضاف من Didit، تُوجَّه الشركة تلقائياً إلى الإدخال اليدوي بدلاً من أن يكون خطأً يقتصر على إعادة المحاولة. راجع [بحث سجل KYB](https://docs.didit.me/ar/standalone-apis/kyb-registry-search.md#التعامل-مع-انقطاعات-السجل). |
| حد المعدل | `429 Too Many Requests` مع رأس `Retry-After`. |المرجع الكامل لـ[حدود المعدل](https://docs.didit.me/ar/integration/rate-limiting.md).## الخطوات التالية> [card] [Webhooks](https://docs.didit.me/ar/business-verification/webhooks.md)
>
> كل أحداث KYB وpayload الخاص بها.> [card] [الحالات](https://docs.didit.me/ar/business-verification/statuses.md)
>
> مرجع آلة الحالات.> [card] [مخطط الاستجابة](https://docs.didit.me/ar/business-verification/response-schema.md)
>
> فك ترميز قرار KYB.


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