> ## 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 سجل KYB: البحث عن الشركات واختيارها

> ابحث في سجلات الشركات واسترجع بياناتها مع Didit بالمستوى الذي تريده: Lite، أو المساهمين، أو المستفيدين الحقيقيين بأسعار لكل دولة.

## endpoints والفوترة

تكلّف عمليات البحث المستقلة الناجحة باستخدام مصدر مدفوع لبيانات الشركات **\$0.50 لكل طلب**، بغض النظر عن عدد المرشحين. لا يتم فرض رسوم على النتائج الفارغة وعمليات البحث الفاشلة والنتائج المقدمة من مصادر أخرى فقط. وتتم فوترة استرداد الملف التعريفي لاحقاً بشكل منفصل.

يُباع الاسترداد في ثلاثة مستويات من البيانات، مع endpoint لكل مستوى، ويُسعر لكل دولة ([الأسعار لكل دولة](https://docs.didit.me/ar/getting-started/kyb-registry-pricing.md)):

| Endpoint | ما تحصل عليه | السعر |
| - | - | - |
| [`POST /v3/kyb/search/`](https://docs.didit.me/ar/standalone-apis/kyb-registry-search) | الشركات المرشحة: الاسم، ورقم التسجيل، والحالة، والنوع | \$0.50 عند إرجاع نتائج من مصدر مدفوع |
| [`POST /v3/kyb/select/`](https://docs.didit.me/ar/standalone-apis/kyb-registry-select) | **Lite**: الملف التعريفي للشركة (المعرّفات، والحالة، والشكل القانوني، وتاريخ التأسيس، والعنوان المسجل، والنشاط، وبيانات الاتصال) والمسؤولين | سعر Lite: \$2.00-\$3.00 بحسب الدولة |
| [`POST /v3/kyb/shareholders/`](https://docs.didit.me/ar/standalone-apis/kyb-registry-shareholders) | مستوى Lite بالإضافة إلى المساهمين المباشرين مع نطاقات ملكيتهم | سعر Shareholders: \$5.00-\$22.00 بحسب الدولة |
| [`POST /v3/kyb/ubo/`](https://docs.didit.me/ar/standalone-apis/kyb-registry-ubo) | مستوى Shareholders بالإضافة إلى المستفيدين الحقيقيين النهائيين الذين تم تحديدهم عبر سلسلة الملكية | سعر UBO: \$9.00-\$96.00 بحسب الدولة |

يُمثل `select` مستوى Lite: وهو ما يفوتره سير عمل KYB المستضاف للتحقق من السجل في مستوى Lite، ويظل خاضعًا للعقد المعمول به منذ البداية. المقصود بأوروبا هو المنطقة الاقتصادية الأوروبية (EEA) والمملكة المتحدة وسويسرا.

يستعلم بحث Shareholders أو UBO من مصدر الملكية الذي يخدم هذا المستوى. وعندما يجيب هذا المصدر بأنه لا يحتفظ بسجل للشركة، يستعلم البحث أيضاً من مصادر السجلات الأخرى في الدولة، وبالتالي فإن الشركة التي لا يدرجها مصدر الملكية تظل معروضة كمرشح بدلاً من أن تنتهي إلى الإدخال اليدوي. يحتفظ المرشحون الذين يتم العثور عليهم بهذه الطريقة بالمستوى الذي طلبته: يؤدي استردادهم إلى إعادة التحقق من مصدر الملكية، وإذا كان لا يزال لا يحتفظ بسجل للشركة، يتم تسليم ملف Lite والفوترة عليه، مع `registry_ownership_status: "not_held"`.

> [!NOTE]
>
> **أنت تدفع مقابل المستوى الذي تم تسليمه.** تتضمن كل استجابة الحقلين `registry_tier_requested` و`registry_tier_delivered`. عندما لا تحتوي سجلات الدولة على بيانات ملكية، أو لا يمتلك السجل أي سجل ملكية للشركة المحددة، يتم تسليم طلب الملكية وتتم فوترته وفقاً لأعلى مستوى متاح (عادةً Lite)، ويوضح `registry_ownership_status` سبب ذلك. أما طلب UBO الذي لا يذكر تقريره الناتج أي شخص طبيعي بصفته مستفيداً حقيقياً، فيتم تسليمه وتتم فوترته كـ Shareholders.

> [!NOTE]
>
> **الإصدارات.** يتوفر endpoint الخاص بـ Shareholders وendpoint الخاص بـ UBO على `/v3/` فقط. وتنطبق أيضاً رسوم البحث المستقل على `/v2/kyb/search/`؛ وتتم فوترة استرداد الملف التعريفي بشكل منفصل.

## حالة الملكية

يُبيّن الحقل `registry_ownership_status` ما حدث لبيانات الملكية في طلب Shareholders أو UBO:

| القيمة | المعنى |
| - | - |
| `not_requested` | كان الاستدعاء عملية استرداد لـ Lite، لذا لم تُطلب أي بيانات ملكية. |
| `delivered` | قدّم السجل بيانات الملكية، والمستوى الموجود في `registry_tier_delivered` هو ما تدفع مقابله. |
| `not_held` | استجاب سجل الملكية وتبيّن أنه لا يُدرج هذه الشركة، وبالتالي ليس لديه سجل ملكية لتقديمه - تم العثور على الشركة بواسطة مصدر آخر من مصادر السجلات في الدولة. يتم تسليم ملف تعريف Lite والفوترة بناءً عليه بدلاً من ذلك، مع `registry_data.ownership_error: "company_not_found"`. |
| `unavailable` | لم يتم تقديم بيانات الملكية لأي سبب آخر: السجل المحتفظ به في سجل الشركات لا يذكر أي مالك، أو أن السجل لم يُرجع قسم الملكية على الإطلاق، أو تعذّر الاستعلام منه. يُحدد `registry_data.ownership_error` السبب. يتم تسليم ملف تعريف Lite والفوترة بناءً عليه بدلاً من ذلك. |
| `pending` | لم يتم استرداد قسم الملكية من السجل بعد. لا تتم فوترة أي شيء ويكون `registry_tier_delivered` بقيمة `null` حتى يكتمل ذلك. |

يتم تسليم كل من `not_held` و`unavailable` وتتم فوترتهما كـ Lite، وهما ليسا النتيجة نفسها: يعني `not_held` أن مصدر بيانات الملكية لا يغطي الشركة - وهي فجوة في التغطية - في حين يعني `unavailable` أنه لم يتم تقديم البيانات، سواء بسبب انقطاع في الخدمة أو لأن السجل ترك هذا القسم فارغاً. يُحدد `registry_data.ownership_error` السبب. التحديدات التي كانت تُبلّغ سابقاً عن `unavailable` لأن سجل الملكية لم يُدرج الشركة تُبلّغ الآن عن `not_held`؛ إذا كان منطقك البرمجي يتفرّع بناءً على الحالة، فعامل كلتيهما كتسليم Lite نفسه. هناك قيمتان له تعنيان أمرين مختلفين ويجب عدم اعتبارهما النتيجة نفسها:

| `ownership_error` | المعنى |
| - | - |
| `no_owners_on_record` | استجاب السجل لقسم الملكية ولكنه لا يذكر أي مالك. ليس لدى الشركة جدول رأس المال مسجل في ذلك السجل. |
| `ownership_section_unavailable` | لم يُرجع السجل قسم الملكية، لذا لم يتم تسليم أي شيء بشأنه. القائمة مفقودة وليست فارغة: هذا لا يعبر عن أي معلومات بشأن من يملك الشركة. |

يتم أيضاً تسجيل أي قسم لم يُرجعه السجل بشكل منظم ضمن `registry_data.section_errors`، مفهرساً حسب القسم (`officers`، `shareholders`، `group_structure`) مع الحالة التي استجاب بها السجل:

```json theme={null}
{
  "section_errors": {
    "shareholders": {
      "status_code": 404
    }
  }
}
```

يصف `section_errors` الاستجابة الحالية لديك، وليس السجل التاريخي السابق لها. أي قسم لم يتم إرجاعه في الطلب الأول وتم تقديمه في محاولة لاحقة (راجع الاسترداد غير المتزامن أدناه) يفقد مدخله، بحيث يتطابق دائماً `registry_ownership_status` و`ownership_error` و`section_errors`: لا يحتوي القسم ذو الحالة `delivered` على أي مدخل، ولا تصاحب `no_owners_on_record` أبداً مدخلات تخص `shareholders`. كما لا يتم تسليم أي قسم جزئياً أبداً: إذا قدّم السجل الصفحة الأولى من القائمة ثم فشل في تقديم صفحة لاحقة، فلن تكتمل عملية الاسترداد في تلك المحاولة - ويُعاد استرداد الطلب ذي الحالة `pending` في المحاولة التالية، بينما يُجاب عن الطلب الجديد بخطأ عدم توفر السجل - لذلك فإن قائمة `officers` أو المساهمين المسلّمة تكون دائماً القائمة الكاملة التي يحتفظ بها السجل. تعامل مع أي قسم مدرج في `section_errors` كبيانات لم يتم تسليمها مطلقاً، وليس كنتيجة فارغة: وجود قائمة `officers` أو مساهمين فارغة إلى جانب مدخل `section_errors` خاص بها لا يعبر عن أي معلومات بشأن الشركة.

### استرداد الملكية بشكل غير متزامن

يتم الاستعلام من بعض السجلات عند الطلب: فالطلب الأول لشركة لم يسبق الاستعلام عنها من ذلك المصدر لا يُرجع قسم الملكية أثناء جلب البيانات، وتصل البيانات في غضون دقيقتين. والإبلاغ عن ذلك بأنه "لا توجد ملكية في السجل" قد يبخس حق شركة لديها مساهمون بالفعل، لذا يعود الطلب بالحالة `pending` بدلاً من ذلك.

أثناء وجود الاسترداد في الحالة `pending`، تكون قيمة `fetch_status` أيضاً `pending` وتكون حالة الاستجابة `202 Accepted`. تعيد Didit محاولة جلب القسم تلقائياً وتُكمل الاسترداد دون الحاجة لأي استدعاء إضافي منك:

* بمجرد وصول بيانات الملكية، يظهر المساهمون والمستفيدون الحقيقيون في الفحص المحفوظ، وتصبح قيمة `registry_tier_delivered` هي المستوى الذي تم تقديمه، ويتم احتساب رسوم الاستخدام وفقاً لذلك المستوى؛
* إذا ظل القسم فارغاً عند انتهاء نافذة إعادة المحاولة، تصبح الحالة `unavailable` ويتم تسليم الطلب وفوترته كـ Lite.

احتفظ بـ `request_id` وقم بإجراء استطلاع دوري لـ `GET /v3/session/{request_id}/decision/` حتى تصبح قيمة `registry_checks[0].company.fetch_status` هي `resolved`. لا تكرر طلب الاسترداد أثناء وجوده في الحالة `pending`: فكل طلب `POST` جديد يُعد طلباً منفصلاً وتتم فوترته بشكل منفصل.

استخدم `POST /v3/kyb/search/` للبحث عن الشركات المرشحة. لا يُنشئ البحث فحصاً محفوظاً. يحدد مُدخل `tier` في البحث السلسلة التي يبحث فيها — راجع [مستوى البحث](https://docs.didit.me/ar/standalone-apis/kyb-registry-search.md#مستوى-البحث).

قد تستغرق عمليات البحث في السجل حوالي 90 ثانية. أرسل `webhook_url` عندما تريد من Didit الاستجابة على الفور وإخطار عنوان URL الخاص بك بمجرد أن تصبح الشركات المرشحة جاهزة. يكون إشعار رد الاتصال للبحث غير موقّع عن قصد، لذا لا تحتاج إلى تكوين السر المشترك لهذا الإشعار الخفيف.

استخدم `POST /v3/kyb/select/` أو `POST /v3/kyb/shareholders/` أو `POST /v3/kyb/ubo/` مع `kyb_response_id` المُرجع لاسترداد ملف التعريف بالمستوى الذي تحتاجه. يُعد الاسترداد خاضعاً للفوترة ويحفظ النتيجة كـ Manual Check في Business Console.

## سير العمل النموذجي

1. ابحث باستخدام اسم الشركة ورقم التسجيل والدولة، على المستوى `tier` الذي تنوي شراءه (`basic` هي سلسلة Lite الافتراضية؛ وتبحث `shareholders` و`ubo` في سلسلة ذلك المستوى).
2. إذا كانت `search_resolved=false`، فانتظر رد الاتصال الاختياري لـ `webhook_url` بدلاً من الاستطلاع الدوري.
3. اعرض الشركات المرشحة المُرجعة على مسؤول التشغيل لديك أو على العميل.
4. استرد `kyb_response_id` المطابق بالمستوى الذي تحتاجه (select لـ Lite، أو shareholders، أو ubo).
5. احفظ `request_id` المُرجع واستخدمه لاسترداد نتيجة التحقق المحفوظة من الشركات.

## استدعاء البحث

عندما يُبلِغ المزود Didit بانتهاء عملية البحث، ترسل Didit طلب `POST` واحداً إلى `webhook_url` الخاص بك:

```json theme={null}
{
  "event_id": "7f5a1c93-6a44-4f0e-9f2b-3d8a1c6f2e91",
  "event_type": "kyb.registry_search.resolved",
  "request_id": "b5ef9df5-bd9e-4d61-bbe5-5eb7a8fb6f85",
  "vendor_data": "business-123",
  "metadata": {
    "source": "onboarding"
  },
  "search_status": "resolved",
  "search_resolved": true,
  "kyb_registry": {
    "companies": [
      {
        "kyb_response_id": "kyb_resp_123",
        "name": "TESCO PLC",
        "registration_number": "00445790",
        "status": "active",
        "type": "Public Limited Company",
        "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA",
        "risk_level": null,
        "fetch_status": "pending"
      }
    ],
    "pagination": {
      "total": 1,
      "page": 1,
      "per_page": 25
    },
    "search_status": "resolved",
    "search_resolved": true
  },
  "timestamp": 1767225600,
  "created_at": 1767225600
}
```

تعامل مع الاستدعاء كإشعار بالتسليم. استخدم `kyb_response_id` المُعاد مع `POST /v3/kyb/select/` أو `POST /v3/kyb/shareholders/` أو `POST /v3/kyb/ubo/` لتشغيل جلب ملف تعريف السجل الخاضع للفوترة.


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