مخطط استجابة KYB: مرجع حمولة القرار

تُوثّق هذه الصفحة payload الكامل التي يعيدها GET /v3/session/{id}/decision/ لجلسة التحقق من الشركات (KYB). endpoint موحّد: عند تمرير session_id خاص بشركة، تتضمن الاستجابة session_kind: "business" ومصفوفات الميزات الخاصة بالشركات الواردة أدناه.

بنية المستوى الأعلى

{
  "session_id": "bs_01H...",
  "session_kind": "business",
  "session_number": 89,
  "session_url": "https://verify.didit.me/...",
  "status": "Approved",
  "status_override": null,
  "workflow_id": "wf_kyb_standard",
  "features": ["KYB_REGISTRY", "AML", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE"],
  "vendor_data": "biz-acme-001",
  "metadata": { },
  "callback": null,

  "registry_checks": [ ... ],
  "aml_screenings": [ ... ],
  "document_verifications": [ ... ],
  "key_people_checks": [ ... ],

  "phone_verifications": null,
  "email_verifications": null,
  "questionnaire_responses": null,
  "ip_analyses": null,

  "reviews": [ ],
  "decision_trace": { ... },
  "linked_records": null,
  "contact_details": { ... },
  "expected_details": null,
  "created_at": "...",
  "expires_at": "..."
}

جميع مصفوفات الميزات متعددة المثيلات، إذ يمثل كل عنصر عقدة واحدة في سير عمل بياني. تعني القيمة null أن الميزة لم تكن ضمن سير عمل هذه الجلسة.

الحقول المشتركة على المستوى الأعلى

الحقل	النوع	الوصف
`session_id`	UUID	معرّف الجلسة الفريد
`session_kind`	enum	قيمته دائماً `"business"` لجلسات KYB
`session_number`	int	رقم تسلسلي ضمن التطبيق
`session_url`	URL	رابط التحقق المستضاف
`status`	enum	الحالة الإجمالية للجلسة (راجع الحالات)
`status_override`	كائن أو null	`{ overridden_at, automatic_status }` عندما يضبط المراجِع `status` يدوياً بما يخالف ما كانت المنصة ستضبطه (مثلاً الموافقة على شركة بينما يُرفض التحقق من شخص رئيسي مرتبط بها). تكون `null` عندما تكون الحالة هي الحالة التلقائية. استخدمه للتمييز بين الموافقة اليدوية والموافقة التلقائية
`decision_trace`	كائن	كيفية الوصول إلى القرار: `status`، و`decided_by` (`manual` أو `automatic` أو `investigator`)، و`decided_at`، و`automatic_status`، و`terminal_node_id`، و`actor`، و`warning_counts`، و`status_warnings` (التحذيرات التي حدّدت الحالة)
`linked_records`	كائن أو null	ملخص للسجلات الأخرى المرتبطة بالجلسة. تكون `null` عندما لا يوجد ما يُعرض
`workflow_id`	UUID	سير العمل الذي قاد هذه الجلسة
`features`	مصفوفة من السلاسل النصية	معرّفات الميزات التي نفّذها سير العمل (مثل `KYB_REGISTRY`، و`AML`، و`KYB_DOCUMENTS`، و`KYB_KEY_PEOPLE`، و`PHONE`، و`EMAIL`)
`vendor_data`	نص	معرّفك للشركة
`metadata`	كائن	JSON حر الشكل أرفقته عند إنشاء الجلسة
`callback`	عنوان URL أو null	رابط اختياري لإعادة التوجيه بعد التحقق
`contact_details`	كائن أو null	`{ email, email_lang, send_notification_emails, phone }`، تُضبط عندما يتضمن التدفق إشعارات البريد الإلكتروني أو الهاتف
`expected_details`	كائن أو null	payload بيانات الشركة المتوقعة التي مررتها عند الإنشاء: `company_name`، و`registry_country` (`XX` أو `XX-YY` مع الولاية للسجلات على مستوى الولايات، مثل `US-CA`)، و`registration_number`
`reviews`	مصفوفة	أحدث ملاحظات المراجِع على الجلسة
`created_at`, `expires_at`	طوابع زمنية بتنسيق ISO	-

`registry_checks[]`

يمثل كل عنصر فحصًا واحدًا لسجل الشركات (عادةً واحد لكل جلسة، وأكثر من واحد في سير العمل في المخطط مع KYB متكرر للمستفيدين الحقيقيين على مستوى الشركات).

{
  "status": "Approved",
  "node_id": "feature_kyb_registry",
  "data_resolved": true,
  "company": { ...see below... },
  "ownership_structure": { },
  "warnings": []
}

الحقل	الوصف
`status`	حالة دورة حياة الميزة (`Approved`, `Declined`, `In Review`, `Not Finished`, `Resub Requested`)
`node_id`	معرّف عقدة المخطط لهذا الفحص
`data_resolved`	تكون القيمة `true` عندما يكتمل تحميل بيانات السجل أو عندما يُدخل المستخدم البيانات يدويًا
`company`	payload الكامل لبيانات السجل، انظر كتلة `company` أدناه
`ownership_structure`	جدول الملكية الذي أثبته السجل عند تسليم مستوى الملكية: `shareholders[]` و `beneficial_owners[]`، ولكل عنصر الهوية نفسها في السجل والحصة نفسها الواردة في `company.beneficial_owners[]` (`name`, `entity_type`, `roles`, `ownership_min_shares` / `ownership_max_shares`, …) و `shareholding` القياسية له. تكون القيمة `null` إذا لم يُثبت السجل أي ملكية. اقرأ `company.beneficial_owners` و `company.ownership` للحصول على السجل الحالي
`warnings`	تحذيرات منظمة وإدخالات سجل مرتبطة بفحص السجل هذا. انظر تحذيرات التحقق من الشركات (KYB)

كتلة `company`

يمثل كائن الشركة المتداخل الصورة الكاملة للكيان القانوني كما اشتُقّت من السجل (وقد يعدّلها المستخدم النهائي):

{
  "uuid": "...",
  "node_id": "feature_kyb_registry",
  "status": "Approved",
  "registry_status": "active",
  "data_resolved": true,
  "company_name": "Acme Corporation Limited",
  "registration_number": "12345678",
  "country_code": "GBR",
  "company_type": "Private Limited",
  "incorporation_date": "2010-05-14",
  "registered_address": "1 Main Street, London EC1A 1AA, United Kingdom",
  "tax_number": "SAMPLE-TAX-12345",
  "risk_level": null,
  "verification_status": "verified",
  "is_from_registry": true,
  "fetch_status": "resolved",
  "alternative_names": "Acme Ltd",
  "nature_of_business": "Software publishing",
  "registered_capital": "100000 GBP",
  "website": "https://acme.example",
  "email": "alex.sample@example.com",
  "phone": "+15550101000",
  "legal_entity_identifier": "529900XXXXXXXXXXXXX",
  "location_of_registration": "London",
  "vat_number": "GB980780684",
  "vat_validation_status": "format_valid",
  "vat_validated_number": "GB980780684",
  "vat_validation_source": "format_rules",
  "vat_validated_name": null,
  "vat_validated_address": null,
  "vat_checked_at": "2026-04-16T10:10:00Z",
  "financial_summary": { },
  "officers": [ ... ],
  "beneficial_owners": [ ... ],
  "addresses": [
    {
      "type": "registered",
      "address": "1 Main Street, London EC1A 1AA, United Kingdom",
      "street": "1 Main Street",
      "city": "London",
      "postal_code": "EC1A 1AA",
      "region": null,
      "country_code": "GB",
      "description": null
    }
  ],
  "industries": [
    { "code": "58290", "description": "Other software publishing", "scheme": "UK SIC 2007", "is_primary": true }
  ],
  "accounts": { ... },
  "ownership": {
    "status": "delivered",
    "tier_requested": "ubo",
    "tier_delivered": "ubo",
    "unavailable_reason": null,
    "direct_ownership_complete": true,
    "unresolved": []
  },
  "registry_tier": "ubo",
  "registry_tier_delivered": "ubo",
  "registry_ownership_status": "delivered",
  "registry_monitoring": null,
  "registry_data": { },
  "user_provided_data": { },
  "confirmed_by_user_at": "2026-04-16T10:10:00Z",
  "last_console_edit_at": null,
  "is_editable": false
}

الحقل	الوصف
`registry_status`	الحالة التي يبلغ عنها المزوّد (`active`, `dissolved`, `struck_off`, `inactive`، وغيرها). انظر الحالات
`is_from_registry`	تكون القيمة `true` عندما تأتي البيانات من سجل رسمي، و `false` للإدخال اليدوي
`fetch_status`	`pending` أو `resolved` أو `failed`، وهي حالة البحث في السجل
`verification_status`	`verified` أو `failed` أو `unknown`
`risk_level`	قيمة اختيارية تُمرَّر من مصدر السجل. عادةً تكون `null`، لأن Didit لا تحسب مستوى المخاطر، لذا استخدم `warnings[]` وحالة الجلسة `status` لاتخاذ القرار
`registry_monitoring`	أحدث مراقب للسجل لهذه الشركة، أو `null` إذا لم يوجد أي مراقب. يُملأ فقط عندما تصبح مراقبة السجل متاحة. الحقول: `uuid`, `status`, `unavailable_reason`, `enrolled_at`, `cancelled_at`, `last_bill_date`, `next_bill_date`, `last_event_at`, `events_count`, `watched_fields`
`is_editable`	تكون القيمة `true` ما دام يمكن للمستخدم النهائي تعديل البيانات المأخوذة من السجل
`registry_data`	التفاصيل الموحّدة للسجل لدى Didit: نتيجة الملكية (`ownership_error`, `section_errors`, `ubo_resolution`)، والتصحيحات التي أُجريت عبر update-data، وحقائق السجل التي ليست لها حقول خاصة بها. لا يتضمن هذا الحقل أبدًا سجلَّ المصدر الأصلي. تختلف مفاتيحه باختلاف الشركة، وليس عقدًا ثابتًا: اقرأ الحقول القياسية بدلًا منه
`user_provided_data`	الحقول التي أدخلها المستخدم النهائي أو عدّلها (مفيدة لمقارنة الفروق بقيم السجل لأغراض التدقيق)
`confirmed_by_user_at`	الطابع الزمني لوقت تأكيد المستخدم النهائي بيانات السجل أو تعديلها
`vat_number`	رقم ضريبة القيمة المضافة كما أُرسل، عند جمعه
`vat_validation_status`	نتيجة التحقق من رقم ضريبة القيمة المضافة، أو من `tax_number` عند عدم وجود رقم ضريبة القيمة المضافة: `valid`, `invalid`, `format_valid`, `invalid_format`, `could_not_validate`, أو `not_applicable`. انظر التحقق من ضريبة القيمة المضافة والرقم الضريبي
`vat_validated_number` / `vat_validation_source`	الرقم الذي جرى التحقق منه كما يعرفه المصدر، والمصدر الذي حدّد الحالة (سجل رسمي، أو `format_rules`)
`vat_validated_name` / `vat_validated_address`	الاسم والعنوان المسجلان لدى المصدر، عندما يفصح عنهما
`vat_checked_at`	الطابع الزمني للفحص؛ تكون القيمة `null` عندما لا يُجرى أي فحص
`officers[]`	المسؤولون مع إثراء KYC المضمّن (انظر أدناه)
`beneficial_owners[]`	المستفيدون الحقيقيون مع إثراء KYC المضمّن (انظر أدناه)
`addresses[]`	كل عنوان يذكره السجل، بالشكل القياسي للعنوان أدناه. تكون القيمة `null` إذا لم يذكر السجل أي عنوان
`industries[]`	الأنشطة التي يصنّف السجل الشركة ضمنها، بالشكل القياسي للصناعة أدناه. تكون القيمة `null` إذا لم يذكر السجل أي نشاط
`accounts`	تواريخ الإيداع المؤسسي عندما يبلغ عنها السجل: `last_annual_return_date` و `last_agm_date`. تصف هذه الحقول الإيداعات والاجتماعات، لا القوائم المالية
`ownership`	نتيجة مستوى الملكية (المساهمون / المستفيدون الحقيقيون)، بالشكل القياسي أدناه
`registry_tier` / `registry_tier_delivered` / `registry_ownership_status`	المستوى المطلوب، والمستوى الذي سُلِّم وتمت فوترته، ونتيجة الملكية. القيم نفسها موجودة في `ownership`

شكل واحد لكل دولة ولكل مصدر سجل

تقرأ Didit سجلات الشركات في دول كثيرة عبر عدة مصادر سجل. ينشر كل مصدر تخطيطه الخاص، لكن كتلة company لها دائمًا الشكل نفسه: المفاتيح أدناه حاضرة دائمًا، بالأنواع نفسها، أيًّا كانت الدولة والمصدر اللذان جاءت منهما الشركة. أي حقيقة لا ينشرها السجل تكون null، ولا تحتاج أبدًا إلى التفريع حسب الدولة أو إلى تحليل registry_data. يُعاد الشكل نفسه في القرار، ونقاط endpoint المستقلة لـسجل KYB، وتدفق التحقق المستضاف. العنوان (كل عنصر في addresses)

الحقل	الوصف
`type`	بأحرف صغيرة. تكون القيمة `registered` للمقر المسجَّل؛ وأنواع أخرى كما يسميها السجل (مثل `postal` و `office`). تكون القيمة `null` إذا لم يحدد السجل نوع العنوان
`address`	العنوان الكامل في سطر واحد. يكون حاضرًا دائمًا
`street`, `city`, `postal_code`, `region`	العنوان مقسّمًا إلى أجزاء، عندما ينشرها السجل
`country_code`	ISO 3166-1 alpha-2
`description`	التسمية التي يعطيها السجل للعنوان، عندما يقدمها

الصناعة (كل عنصر في industries)

الحقل	الوصف
`code`	رمز النشاط كما يطبعه السجل
`description`	تسمية النشاط، عندما ينشرها السجل
`scheme`	نظام التصنيف، باسم واحد لكل نظام أيًّا كان المصدر الذي أبلغ عنه (`UK SIC 2007`, `US SIC`, `NACE Rev. 2`, `NACE Rev. 2.1`, `NAF Rev. 2`, `CNAE`, `SBI`, `NOGA 2008`, `CAE Rev. 4`, `Canada SIC 1977`). تحتفظ الأنظمة الوطنية الأخرى باسم السجل نفسه؛ وتكون القيمة `null` إذا لم يذكر السجل اسم النظام
`is_primary`	`true` للنشاط الرئيسي. يكون إدخال واحد بالضبط هو الرئيسي

عندما يذكر السجل الأنشطة دون وصف للنشاط التجاري، يُملأ nature_of_business من تسميات الأنشطة. تُملأ بيانات الاتصال والأسماء البديلة عند توفرها، وتكون التعديلات الصريحة من المستخدم أو المراجع لها الأولوية دائماً. الملكية (ownership)

الحقل	الوصف
`status`	`delivered`؛ و`not_held` عندما يجيب سجل الملكية ولا يُدرج هذه الشركة إطلاقاً، فلا يوجد سجل ملكية لتقديمه؛ و`unavailable` عندما لا تُقدَّم البيانات لأي سبب آخر (سجل لا يسمّي أي مالك، أو قسم الملكية لم يُعَد، أو مزوّد تعذّر الاستعلام منه)؛ و`pending` بينما لا يزال السجل يجلب قسم الملكية؛ و`not_requested` في المستوى الأساسي
`tier_requested` / `tier_delivered`	`basic` أو `shareholders` أو `ubo`. يُسلَّم طلب UBO الذي أُجيب عنه بالمساهمين المباشرين فقط، وتُحتسب فوترته، على أنه `shareholders`
`unavailable_reason`	سبب عدم تقديم مستوى الملكية المطلوب: `no_owners_on_record`، أو `no_natural_person_owner`، أو `ownership_section_unavailable`، أو `company_not_found`، أو `ambiguous_company_match`، أو `missing_registration_number`، أو `entity_type_not_covered`، أو `provider_unavailable`، أو `other`. تكون القيمة `null` عند تقديم الملكية
`direct_ownership_complete`	`true` عندما تبلغ الحصص المعلنة للمساهمين المباشرين 100% (ضمن نقطة مئوية واحدة للتقريب)، و`false` عندما لا تبلغها، و`null` عندما لا تُقدَّم الملكية أو عندما لا تكون إحدى الحصص معلنة
`unresolved[]`	أجزاء سلسلة الملكية التي لم يتمكن السجل من حلّها، بالشكل `{ reason, section }` (مثلاً `no_group_structure_on_record` للقسم `group_structure`: المالكون المباشرون معروفون، أما مجموعة الشركات الأعلى منهم فغير مسجلة)

تفاصيل السجل (registry_data) تفاصيل Didit الخاصة بفحص السجل، وليست سجلاً مصدره السجل نفسه أبداً. كل مفتاح اختياري ولا يظهر إلا عندما تكون للشركة قيمة له، وقد تُضاف مفاتيح جديدة: اقرأ الحقول الأساسية أعلاه لأي معلومة تغطيها.

الحقل	الوصف
معلومات السجل (`legal_address`، و`registered_address`، و`registration_date`، و`dissolution_date`، و`registry_status`، و`verification_status`، و`company_type`، والحقول الأخرى التي يقبلها update-data)	نصوص. التصحيحات التي أُجريت باستخدام update-data، والمعلومات التي يذكرها السجل ولا يوجد لها حقل خاص بها (`registration_date`، و`dissolution_date`)
`ownership_error`	سبب عدم تقديم مستوى الملكية المطلوب، بالرموز نفسها المستخدمة في `ownership.unavailable_reason` (`no_owners_on_record`، و`ownership_section_unavailable`، و`company_not_found`، و`provider_unavailable`، و`other`، وغيرها)
`section_errors`	الأقسام التي لم يُعدها السجل، مفهرسة بالقسم (`officers`، و`shareholders`، و`group_structure`)، وكل منها `{ status_code }`
`ubo_resolution`	كيفية تتبّع مستوى UBO لسلسلة الملكية: `parent_chain[]` و`subsidiaries[]` بالشكل `{ name, country_code, registration_number }`، و`unresolved[]` بالشكل `{ reason, section }`
`lite_enrichment`	الحقول الفارغة في Lite التي ملأتها مصادر سجل أخرى في الدولة: `{ fields[], people_added }`
`registry_metadata`، و`registry_sources[]`، و`previous_names[]`، و`parent_companies[]`، و`documents_available`	لسجلات السجل القديمة فقط: الحقول الخاصة بالسجل، والسجلات الرسمية التي جرى الاطلاع عليها (`{ name, source_type }`، ولا تُذكر إلا السجلات الرسمية)، والأسماء السابقة، وأسماء الشركات الأم، وعدد الملفات المتاحة

شكل عنصر المسؤول (داخل `company.officers`)

{
  "uuid": "...",
  "name": "Jane Doe",
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": null,
  "date_of_birth_year": 1983,
  "date_of_birth_month": 2,
  "address": "1 Example Street, London",
  "appointment_date": "2024-07-01",
  "termination_date": null,
  "designation": "Director",
  "role": "director",
  "nationality": "USA",
  "is_active": true,
  "kyc_status": "Approved",
  "kyc_session_url": "https://verify.didit.me/..."
}

يُملأ date_of_birth فقط عندما يوفر السجل تاريخاً كاملاً. إذا لم يذكر السجل إلا السنة، أو الشهر والسنة، فاستخدم date_of_birth_year وdate_of_birth_month، ولا يُستنتج اليوم الناقص أبداً. تبقى الأسماء وتفاصيل الميلاد والعنوان وتواريخ التعيين متاحة في قائمة مسؤولي الشركة وفي قائمة الأشخاص الرئيسيين في السجل.

شكل عنصر المستفيد الحقيقي (داخل `company.beneficial_owners`)

{
  "uuid": "...",
  "name": "John Doe",
  "first_name": "John",
  "last_name": "Doe",
  "entity_type": "person",
  "date_of_birth": null,
  "country_of_birth": null,
  "email": null,
  "company_name": null,
  "registration_number": null,
  "nationality": null,
  "designation": null,
  "appointment_date": null,
  "voting_min_shares": null,
  "voting_max_shares": null,
  "roles": ["ubo"],
  "ownership_min_shares": "40",
  "ownership_max_shares": "40",
  "is_active": true,
  "kyc_status": "Pending",
  "kyc_session_url": "https://verify.didit.me/...",
  "effective_ownership_percent": 40.0,
  "shareholding": {
    "share_class": "Ordinary",
    "number_of_shares": 40,
    "currency": "GBP",
    "nominal_value": 1,
    "total_value": null,
    "percentage": 40
  }
}

يستخدم kyc_status تمثيلاً آمناً للاستخدام في B2C: Approved أو Declined أو Pending (تُختزل حالات الجلسة الكاملة إلى Pending إلى أن ينتهي KYC). يبيّن shareholding ما يملكه المالك، بالشكل نفسه لكل دولة ولكل مصدر سجل: share_class وnumber_of_shares وcurrency وnominal_value وtotal_value وpercentage (الحصة الدقيقة بأربع منازل عشرية). تكون القيمة null عندما لا يذكر السجل أي ملكية. النطاق، مثل 25-50% لـ UK PSC، ليس حصة: تكون percentage قيمتها null ويبقى النطاق في ownership_min_shares وownership_max_shares. يُدرَج المساهمون والمستفيدون الحقيقيون معاً في beneficial_owners، ويميّز roles بينهم.

`key_people_checks[]`

يمثل هذا فحص التجميع لجميع المسؤولين والمستفيدين الحقيقيين في الجلسة. يوفّر مجموعتين لتتمكن وحدة التحكم من عرض “المستخرَج من السجل” جنباً إلى جنب مع “المقدَّم من الشركة”، بالإضافة إلى ملخص عالي المستوى لـ KYC الخاص بالمستفيدين الحقيقيين.

{
  "status": "Approved",
  "node_id": "feature_kyb_key_people",
  "registry": {
    "officers": [ ...registry-derived officers... ],
    "beneficial_owners": [ ...registry-derived UBOs... ]
  },
  "submitted": {
    "parties": [ ...user-submitted key-people records... ]
  },
  "ubo_kyc_summary": {
    "total": 2,
    "approved": 1,
    "flagged": 0,
    "pending": 1
  },
  "warnings": []
}

registry.officers / registry.beneficial_owners: الأطراف المستخرجة من فحص السجل.
submitted.parties: الأطراف التي أضافها مسؤول الشركة صراحةً أثناء مسار الأشخاص الرئيسيين (السجلات التي تحمل source = "USER").

`registry.officers[]` / `registry.beneficial_owners[]`

تطابق بيانات السجل الواردة في company.officers وcompany.beneficial_owners أعلاه. ويشمل فحص الأشخاص الرئيسيين بالإضافة إلى ذلك حالة AML وربطاً تفصيلياً بالتحقق، مثل kyc_session_id وحقول سير عمل التحقق. تحتفظ قوائم الشركة بحالة KYC المبسّطة ورابط التحقق الحاليين.

`submitted.parties[]`

تحمل الأطراف المقدَّمة من المستخدم ربطها بـ KYC أو بـ KYB الفرعي:

{
  "uuid": "...",
  "entity_type": "person",
  "name": "Alice Chen",
  "first_name": "John",
  "last_name": "Doe",
  "email": "alex.sample@example.com",
  "role": "ubo",
  "ownership_percent": 35.0,
  "nationality": "USA",
  "position": "CEO",
  "date_of_birth": "1990-01-01",
  "phone_number": "+34612345678",
  "source": "USER",
  "requires_verification": true,
  "is_skipped": false,
  "kyc_session_id": "sess-xyz...",
  "kyc_session_status": "Not Started",
  "kyc_session_url": "https://verify.didit.me/...",
  "kyc_session_deleted": false,
  "custom_fields": { }
}

تحمل الأطراف من نوع الشركات (entity_type: "company") أيضاً company_name وregistration_number وkyb_sub_session_id وkyb_sub_session_status وkyb_sub_session_deleted عند تفعيل KYB المتداخل للمستفيدين الحقيقيين من الشركات. تكون قيمة kyc_session_deleted (ونظيرتها للشركات kyb_sub_session_deleted) مساويةً لـ true عند حذف الجلسة الفرعية للطرف. تحتفظ الجلسة الفرعية المحذوفة بالحالة التي كانت عليها وقت حذفها، ولا يمكن أن تُحسم أبداً، لذا اقرأ هذه العلامة بدلاً من الحالة: تُعاد قيمة *_session_url المطابقة كـ null لأن الرابط لم يعد يعمل، وينتقل فحص الأشخاص الرئيسيين إلى In Review بدلاً من الانتظار إلى ما لا نهاية. لا يُعدّ حذف الجلسة الفرعية نجاحاً أبداً. أعفِ الطرف عبر PATCH /v3/session/{id}/kyb/parties/{party_uuid}/ للسماح بحسم KYB.

`ubo_kyc_summary`

تقدّم KYC الإجمالي للمستفيدين الحقيقيين، ومفيد لبطاقة واحدة في لوحة التحكم:

الحقل	المعنى
`total`	عدد المستفيدين الحقيقيين النشطين الذين لديهم جلسة KYC مرتبطة
`approved`	المستفيدون الذين تكون جلسة KYC الخاصة بهم `Approved`
`flagged`	المستفيدون الذين تكون جلسة KYC الخاصة بهم `Declined` أو `In Review`
`pending`	كل من عداهم (لم يكتمل بعد)

تُعيد القيمة null عندما لا يكون لأي مستفيد حقيقي جلسات KYC مرتبطة.

`document_verifications[]`

المستندات مجمّعة حسب العقدة:

{
  "status": "Approved",
  "node_id": "feature_kyb_documents",
  "items": [
    {
      "uuid": "...",
      "document_type": "LEGAL_PRESENCE",
      "document_subtype": "CERTIFICATE_OF_INCORPORATION",
      "document_group": "LEGAL_PRESENCE",
      "status": "Approved",
      "file_url": "https://didit-storage.s3...",
      "document_metadata": {
        "file_size": 246810,
        "content_type": "application/pdf",
        "creation_date": "2024-05-15",
        "modified_date": "2024-05-15",
        "overlay_manipulation": null
      },
      "ocr_data": {
        "company_name": "Acme Corporation Limited",
        "registration_number": "12345678",
        "incorporation_date": "2010-05-14"
      }
    }
  ],
  "groups": {
    "LEGAL_PRESENCE": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 },
    "OWNERSHIP_STRUCTURE": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 }
  },
  "required_groups": ["LEGAL_PRESENCE", "OWNERSHIP_STRUCTURE"],
  "warnings": []
}

الحقل	الوصف
`items[]`	صفوف المستندات الفردية، ولكل صف `status` و`document_type` و`document_group` (المجموعة) و`document_subtype` و`file_url` (موقّع) و`document_metadata` ومستخرج OCR
`groups`	عدادات التقدم لكل مجموعة، مفهرسة بقيمة المجموعة (`LEGAL_PRESENCE` و`COMPANY_DETAILS` و`OWNERSHIP_STRUCTURE` و`REPRESENTATIVES_AUTHORIZATION`، بالإضافة إلى `OTHER` للمستندات غير المصنفة). تحتوي كل مجموعة على `total` و`approved` و`pending` و`declined` و`in_review` و`other` و`missing`. راجع مجموعات مستندات KYB
`required_groups`	المجموعات التي حددها سير العمل كمطلوبة؛ تشترط الموافقة على الجلسة استيفاءها جميعًا

بيانات تعريف مستندات الشركات

بالنسبة إلى مستندات الشركات بصيغة PDF، قد يتضمن items[].document_metadata.overlay_manipulation أدلة جنائية رقمية على الاشتباه في تعديل نص التراكب. عند وجودها، تتضمن ما يلي:

الحقل	الوصف
`analysis_incomplete`	يكون موجودًا و`true` فقط عندما يتعذر فحص الملف كاملًا. ما تم فحصه يحتفظ بنتائجه حيثما أمكن، ويُصدر المستند `KYB_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`.
`detected`	ما إذا كانت قد رُصدت أدلة على تعديل نص التراكب
`analyzed`	ما إذا كان من الممكن تحليل ملف PDF
`signals`	الإشارات الجنائية الرقمية التي تم تفعيلها، مثل `duplicate_font_subset` أو `glyph_fragmentation`
`manipulated_regions`	مستطيلات بإحداثيات الصفحة في ملف PDF تحيط بالنصوص المشتبه في تعديلها: `page` و`x` و`y` و`width` و`height` و`page_width` و`page_height`

يكون الحقل null عندما لا يُعثر على أي أدلة على التراكب، أو عندما لا يكون المستند بصيغة PDF، أو عندما يتعذر تحليل ملف PDF.

`aml_screenings[]`

فحوصات AML على مستوى الشركة، وعلى مستوى الأشخاص أيضاً (عندما يربطها سير العمل).

{
  "node_id": "feature_aml",
  "status": "Approved",
  "total_hits": 0,
  "score": 0,
  "entity_type": "COMPANY",
  "screened_data": {
    "company_name": "Acme Corporation Limited",
    "country_code": "GBR"
  },
  "is_ongoing_monitoring_enabled": true,
  "next_ongoing_monitoring_bill_date": "2027-04-16",
  "last_ongoing_screening_at": "2026-09-12T04:03:11Z",
  "last_ongoing_screening_datasets_updated_at": null,
  "hits": [],
  "warnings": []
}

عندما تكون total_hits > 0، يتضمن كل تطابق درجة التطابق ودرجة المخاطر ومصادر قوائم المراقبة، وحالة مراجعة review_status لكل تطابق يمكنك تحديثها عبر الـ endpoint المسمى update-aml-hit-status. راجع تقرير فحص AML لمعرفة بنية التطابق.

مصفوفات الميزات المشتركة

تستخدم phone_verifications وemail_verifications وquestionnaire_responses وip_analyses هياكل العناصر نفسها المستخدمة في جلسات المستخدم (KYC). وتكون null عندما لا يتضمنها سير العمل. راجع استجابة KYC للاطلاع على مخططات العناصر. يظهر signatures عندما يتضمن سير العمل خطوة التوقيع الإلكتروني. تحتوي جلسة الشركة على عنصر واحد لكل شخص رئيسي يوقّع باسم الشركة، مع signer.capacity: "company" واسم الشركة وأدوار الشخص الرئيسي. راجع تقرير التوقيع الإلكتروني.

مجموعات تحذيرات الميزات

تُجمَّع تحذيرات التحقق من الشركات حسب الميزة التي أنتجتها:

KYB_REGISTRY لمشكلات توفّر السجل والملكية ونشاط الشركة وقيود الدول.
KYB_DOCUMENTS لمشكلات استخراج مستندات الشركات والمطابقة المتقاطعة والبيانات الوصفية والتلاعب والنوع الفرعي والعمر وحدود المحاولات.
AML لمطابقات فحص AML الخاصة بالشركة أو لبيانات الفحص المفقودة.
KYB_KEY_PEOPLE لمشكلات على مستوى الأشخاص المرتبطين بالمديرين والمسؤولين والمستفيدين الحقيقيين أو الممثلين.
PHONE لمخاطر رقم الهاتف والتكرار وقائمة الحظر ومحاولات رمز التحقق.
EMAIL لمخاطر البريد الإلكتروني وقابلية التسليم والتكرار وقائمة الحظر ومحاولات رمز التحقق.
QUESTIONNAIRE لقواعد الحالة المخصصة المدفوعة بإجابات الاستبيانات.
LOCATION لتحليل الجهاز وعنوان IP، ومشكلات الشبكات الخاصة، وقائمة الحظر لعناوين IP، وقائمة الحظر للأجهزة، ومشكلات تكرار الجهاز أو عنوان IP.
SIGNATURE لرفض التوقيع الإلكتروني، وفشل تأكيد الرموز، وعدم تطابق أسماء الموقعين، والموقعين غير الموثّقين، والمستندات المتغيرة، وبيانات الحقول المفقودة. راجع تحذيرات التوقيع الإلكتروني.

راجع تحذيرات التحقق من الشركات للاطلاع على القائمة الكاملة لرموز التحذير.

تصفية الحقول حسب سير العمل

يمكن لسير العمل أن يحدّ من الحقول المتداخلة التي تظهر في كل عنصر من عناصر الميزة عبر response_attributes. تُدرج الحقول التالية دائمًا بغض النظر عن ذلك: status وwarnings وnode_id. تُعيَّن قيمة كل الحقول الأخرى إلى null عندما لا تكون مدرجة في قائمة السماح، ويبقى المفتاح في الاستجابة من أجل ثبات المخطط.

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

الحالات

معنى كل قيمة من قيم الحالة.

تقييم المخاطر

ما الذي يحدد نتيجة KYB.

تقرير AML

مرجع كامل لحمولة تطابقات AML.

الأشخاص الرئيسيون

كيفية انتقال الأطراف من السجل أو من إرسال المستخدم إلى المجموعتين registry وsubmitted.

المستندات

مجموعات المستندات وOCR والإحالات المرجعية.

استرجاع الجلسة

المرجع الكامل لـ endpoint، بما في ذلك أمثلة الاستجابات.

البدء

الميزات

ملفات الشركات

المرجع

Console

مخطط استجابة KYB: مرجع حمولة القرار

بنية المستوى الأعلى

الحقول المشتركة على المستوى الأعلى

`registry_checks[]`

كتلة `company`

شكل واحد لكل دولة ولكل مصدر سجل

شكل عنصر المسؤول (داخل `company.officers`)

شكل عنصر المستفيد الحقيقي (داخل `company.beneficial_owners`)

`key_people_checks[]`

`registry.officers[]` / `registry.beneficial_owners[]`

`submitted.parties[]`

`ubo_kyc_summary`

`document_verifications[]`

بيانات تعريف مستندات الشركات

`aml_screenings[]`

مصفوفات الميزات المشتركة

مجموعات تحذيرات الميزات

تصفية الحقول حسب سير العمل

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

الحالات

تقييم المخاطر

تقرير AML

الأشخاص الرئيسيون

المستندات

استرجاع الجلسة

​بنية المستوى الأعلى

​الحقول المشتركة على المستوى الأعلى

​registry_checks[]

​كتلة company

​شكل واحد لكل دولة ولكل مصدر سجل

​شكل عنصر المسؤول (داخل company.officers)

​شكل عنصر المستفيد الحقيقي (داخل company.beneficial_owners)

​key_people_checks[]

​registry.officers[] / registry.beneficial_owners[]

​submitted.parties[]

​ubo_kyc_summary

​document_verifications[]

​بيانات تعريف مستندات الشركات

​aml_screenings[]

​مصفوفات الميزات المشتركة

​مجموعات تحذيرات الميزات

​تصفية الحقول حسب سير العمل

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

الحالات

تقييم المخاطر

تقرير AML

الأشخاص الرئيسيون

المستندات

استرجاع الجلسة

بنية المستوى الأعلى

الحقول المشتركة على المستوى الأعلى

`registry_checks[]`

كتلة `company`

شكل واحد لكل دولة ولكل مصدر سجل

شكل عنصر المسؤول (داخل `company.officers`)

شكل عنصر المستفيد الحقيقي (داخل `company.beneficial_owners`)

`key_people_checks[]`

`registry.officers[]` / `registry.beneficial_owners[]`

`submitted.parties[]`

`ubo_kyc_summary`

`document_verifications[]`

بيانات تعريف مستندات الشركات

`aml_screenings[]`

مصفوفات الميزات المشتركة

مجموعات تحذيرات الميزات

تصفية الحقول حسب سير العمل

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