الانتقال إلى المحتوى الرئيسي
POST
curl
استخدم نقطة النهاية هذه أولاً للعثور على مرشحين مطابقين من سجل الشركات. لا ينشئ البحث فحصاً يدوياً محفوظاً. تُكلّف عمليات البحث المستقلة الناجحة التي تستخدم مصدر بيانات شركات مدفوعاً $0.50 لكل طلب، بغض النظر عن عدد المرشحين. لا تُحتسب رسوم على النتائج الفارغة، أو عمليات البحث الفاشلة، أو النتائج التي تأتي فقط من مصادر أخرى. ويُفوتَر استرجاع الملف التعريفي لاحقاً بشكل منفصل. بالنسبة إلى البحث الذي قد يستخدم مصدراً مدفوعاً، يتحقق Didit من سعر البحث المطبّق ويحجزه قبل الاتصال بالسجل. عند عدم كفاية الرصيد، يُعيد الطلب الاستجابة 403 مع code: "insufficient_credits". تتبع الفوترة التعاقدية سعر البحث المتفق عليه معك؛ ويُرفض أي سعر تعاقدي غير مُعدّ قبل تنفيذ البحث. عمليات البحث في البيئة التجريبية مجانية. كل عملية بحث ناجحة مكررة تُعد طلباً جديداً قابلاً للفوترة؛ ولا يضيف تسليم الاستدعاء رسوماً إضافية على البحث. إذا أرسلت webhook_url، يمكن أن يعيد Didit الاستجابة فوراً بينما يحلّ المزوّد البحث، ثم يرسل المرشحين إلى رابط الاستدعاء الخاص بك عند جاهزيتهم. الاستدعاء غير موقّع بحكم التصميم، لذلك لا تحتاج إلى إعداد سر webhook لإشعار البحث هذا. راجع مثال على حمولة استدعاء البحث. بعد اختيار kyb_response_id الصحيح، استدعِ POST /v3/kyb/select/ (Lite) أو POST /v3/kyb/shareholders/ أو POST /v3/kyb/ubo/ لاسترجاع الملف التعريفي القابل للفوترة من السجل بالمستوى الذي تحتاجه.
تكون قيمة fetch_status لكل مرشح pending وقت البحث، وتبقى pending حتى تختار ذلك المرشح. فالبحث يسرد المرشحين فقط، والاختيار هو ما يجلب الملف التعريفي الكامل. لا تُكرّر الاستعلام عن البحث في انتظار حلّ هذه القيمة.kyb_response_id معرّف غامض ومؤقت مرتبط بطلب بحث واحد: أعِده تماماً كما تلقيته، ولا تُحلّله ولا تستنتج أي شيء من محتوياته، وتوقع أن يعيد تكرار البحث نفسه معرّفات جديدة. اختر المرشح بسرعة بعد البحث، واستخدم registration_number عندما تحتاج إلى معرّف ثابت للشركة نفسها.

مستوى البحث

يحدد tier مستوى السجل الذي تعمل عليه سلسلة المزوّدين للبحث: basic (الافتراضي، وهو سلسلة Lite)، أو shareholders، أو ubo. تأتي قائمة المرشحين من سلسلة ذلك المستوى، وهي ليست دائماً المصدر الذي يقرأ منه بحث Lite، لذلك فإن بحث Lite الفارغ لا يُثبت أن السجل لا يحتوي على الشركة. ابحث مرة أخرى بالمستوى الذي تحتاجه. عندما لا توفّر الدولة المستوى الذي حددته، يعمل البحث على أعلى مستوى تتيحه الدولة دون تجاوز ذلك المستوى. الدولة التي لا تتوفر لها بيانات سجل على الإطلاق لا تُتاح لفحوص السجل؛ تابع بإدخال بيانات الشركة يدوياً. ابحث بالمستوى الذي تنوي شراءه، ثم استرجع المرشح من نقطة النهاية التي تبيعه:

search_type

لا يقبل search_type سوى contains، وهي القيمة الافتراضية. تطابق مصادر السجل التي يعتمد عليها البحث اسم الشركة بالاحتواء، لذلك تُرفض القيمتان start_with وfuzzy بالاستجابة 400 ("start_with" is not a valid choice) بدلاً من معاملتهما بصمت على أنهما contains. أرسل registration_number للحصول على تطابق دقيق مع الشركة.

البحث المستضاف والبحث المستقل

POST /v1/kyb/search/ هو البحث الذي يُجريه مسار التحقق المستضاف: يُصادَق عليه بجلسة التحقق، ويُعيد 403 عند استخدام مفتاح API، ولا يقبل tier، إذ يحدد إعداد سجل KYB في سير العمل السلسلة المستخدمة. يستدعي التكامل المستقل POST /v2/kyb/search/ أو POST /v3/kyb/search/ مع x-api-key الخاص بك؛ ومدخل tier ونقاط النهاية المتدرجة للاختيار هي الوسيلة التي يصل بها التكامل المستقل إلى المرشحين أنفسهم، بالمستوى الذي يحتاجه.

التعامل مع انقطاعات السجل

إذا كان مزوّد السجل غير متاح مؤقتاً، تُعيد نقطة النهاية الاستجابة 502 مع رمز ثابت يمكن للآلة قراءته:
عند استلام هذا الرمز، اسمح للمستخدم بالمتابعة بإدخال بيانات الشركة يدوياً، أو اطلب منه إعادة المحاولة لاحقاً. وافصل أخطاء التحقق عن هذا: مدخلات البحث غير الصالحة تُعيد 400 ولا تستخدم رمز الانقطاع هذا.

التعامل مع الدول غير المدعومة وحدود البحث

هناك رمزان ثابتان آخران يُخبراك بالتوقف عن إعادة المحاولة والمتابعة بإدخال بيانات الشركة يدوياً: في مسار التحقق المستضاف، تسمح كل خطوة من خطوات السجل بثلاث عمليات بحث على مصدر بيانات شركات مدفوع. وبعد المحاولة الثالثة يُعرض على مقدّم الطلب الإدخال اليدوي. يؤدي اختيار مرشح يمثّل تسجيل علامة تجارية لا شركة إلى استجابة 400 مع code: "kyb_registry_entry_not_a_company". اختر شركة من نتائج البحث بدلاً من ذلك.

التفويضات

x-api-key
string
header
مطلوب

مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console. يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير 404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع https://docs.didit.me/console/api-keys.

الجسم

application/json
country_code
string
مطلوب

رمز ISO 3166-1 alpha-2 للدولة المطلوب البحث في سجل الشركات الخاص بها. على سبيل المثال، GB. عندما تعمل سجلات الشركات على مستوى الولاية أو المقاطعة، ألحق رمز التقسيم الفرعي ISO 3166-2 بصيغة XX-YY: يبحث US-CA في سجل كاليفورنيا. تتطلب عمليات البحث في الولايات المتحدة دائماً التقسيم الفرعي — ويتم رفض إدخال US بمفرده. غير حساس لحالة الأحرف؛ ويتم توحيده إلى أحرف كبيرة.

Maximum string length: 10
مثال:

"GB"

name
string

اسم الشركة المراد البحث عنها. يلزم توفير name أو registration_number.

Maximum string length: 255
مثال:

"Tesco"

registration_number
string

رقم تسجيل السجل المطلوب البحث عنه. يلزم إدخال إما name أو registration_number.

Maximum string length: 100
tier
enum<string>
افتراضي:basic

مستوى السجل الذي تعمل سلسلة المزود الخاصة به في هذا البحث. يبحث basic (الافتراضي) في سلسلة Lite الخاصة بالدولة؛ بينما يبحث shareholders وubo في سلسلة الملكية الخاصة بذلك المستوى، والتي قد تكون مصدراً مختلفاً، لذا فإن بحث Lite الفارغ لا يثبت أن السجل يفتقر إلى الشركة. أما الدولة التي لا توفر المستوى المذكور، فيتم البحث فيها بأعلى مستوى تقدمه حتى ذلك المستوى. استرد المرشح من الـ endpoint التي تبيع المستوى الذي بحثت عنه: POST /v3/kyb/select/ (Lite)، أو POST /v3/kyb/shareholders/، أو POST /v3/kyb/ubo/.

الخيارات المتاحة:
basic,
shareholders,
ubo
مثال:

"basic"

search_type
enum<string>
افتراضي:contains

استراتيجية مطابقة الأسماء المطبقة بواسطة بحث السجل. contains هي القيمة الوحيدة المقبولة: لا يوجد أي مصدر سجل خلف البحث يوفّر وضع البادئة أو المطابقة التقريبية، لذا يُرفض استخدام start_with وfuzzy مع إرجاع 400 (not a valid choice).

الخيارات المتاحة:
contains
vendor_data
string

المعرّف الخاص بك لعملية البحث هذه؛ تتم إعادته وتضمينه في استدعاء webhook.

metadata
object | null

كائن JSON بصيغة حرة؛ تتم إعادته في الاستجابة وتضمينه في استدعاء webhook.

webhook_url
string<uri>

يحوّل البحث إلى الوضع غير المتزامن: تستجيب API على الفور وتُرسل طلب POST لـ callback غير موقّع من نوع kyb.registry_search.resolved إلى عنوان URL هذا عندما تصبح قائمة المرشحين جاهزة.

Maximum string length: 500

الاستجابة

تم قبول البحث. يُرجع الوضع المتزامن قائمة المرشحين النهائية؛ بينما يُرجع وضع webhook الاستجابة فوراً (غالباً search_status: "pending") ويسلّم القائمة النهائية عبر استدعاء kyb.registry_search.resolved.

request_id
string<uuid>

مع webhook_url: معرّف طلب البحث الدائم، ويُعاد كـ request_id في رد الاستدعاء kyb.registry_search.resolved. بدون webhook_url: معرّف UUID ارتباطي مؤقت (لا يتم تخزين البحث).

kyb_registry
object
vendor_data
string | null

تكرار لقيمة vendor_data التي أرسلتها.

metadata
object | null

نسخة مطابقة من metadata التي أرسلتها.

created_at
string<date-time>
آخر تعديل في ٧ نوفمبر ٢٠٢٦