API سجل KYB: البحث عن الشركات واختيارها

endpoints والفوترة

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

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

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

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

الإصدارات. يتوفر 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) مع الحالة التي استجاب بها السجل:

{
  "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 في البحث السلسلة التي يبحث فيها — راجع مستوى البحث. قد تستغرق عمليات البحث في السجل حوالي 90 ثانية. أرسل webhook_url عندما تريد من Didit الاستجابة على الفور وإخطار عنوان URL الخاص بك بمجرد أن تصبح الشركات المرشحة جاهزة. يكون إشعار رد الاتصال للبحث غير موقّع عن قصد، لذا لا تحتاج إلى تكوين السر المشترك لهذا الإشعار الخفيف. استخدم POST /v3/kyb/select/ أو POST /v3/kyb/shareholders/ أو POST /v3/kyb/ubo/ مع kyb_response_id المُرجع لاسترداد ملف التعريف بالمستوى الذي تحتاجه. يُعد الاسترداد خاضعاً للفوترة ويحفظ النتيجة كـ Manual Check في Business Console.

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

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

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

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

{
  "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/ لتشغيل جلب ملف تعريف السجل الخاضع للفوترة.

آخر تعديل في ٧ نوفمبر ٢٠٢٦

​endpoints والفوترة

​حالة الملكية

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

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

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

endpoints والفوترة

حالة الملكية

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

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

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