تحديث بيانات الجلسة API: تصحيح حقول KYC وKYB

قد يخطئ التعرف الضوئي على الحروف (OCR) أحيانًا في قراءة هوية أو فاتورة خدمات أو مدخل في سجل الشركات. يوفّر Didit ثلاثة endpoint من نوع PATCH يمكنك استدعاؤها لتصحيح البيانات المستخرجة دون إعادة تشغيل عملية التحقق كاملة.

endpoint	استخدمها عندما
`PATCH /v3/session/{id}/update-data/`	تصحيح القيم المستخرجة من وثيقة الهوية في جلسة التحقق من المستخدمين (KYC)
`PATCH /v3/session/{id}/update-poa-data/`	تصحيح القيم المستخرجة من فاتورة خدمات أو كشف حساب بنكي أو عقد إيجار في جلسة التحقق من المستخدمين (KYC)
`PATCH /v3/session/{id}/kyb/{company_uuid}/update-data/`	تصحيح الحقول المستخرجة من السجل في جلسة التحقق من الشركات (KYB)
`PATCH /v3/session/{id}/kyb/parties/{party_uuid}/`	إعفاء طرف من الأشخاص الرئيسيين من التحقق عندما لم يعد قادرًا على إكمال فحصه الخاص

تقبل جميع الـendpoints الأربعة مفتاح API الخاص بالعميل أو ترويسة تفويض المستخدم، وترسل جميعها webhook بالحدث data.updated عند النجاح، حتى يبقى نظامك والتحليلات اللاحقة متزامنين.

المتطلبات المشتركة

التفويض: مفتاح API الخاص بالعميل (بالترويسة القياسية x-api-key أو Authorization بصيغة bearer)، أو رمز مصادقة المستخدم.
الصلاحية:
- KYC وPOA: write:sessions
- شركة KYB وطرف الأشخاص الرئيسيين: write:businesses
حالة الجلسة (لـ KYC وPOA فقط): يجب أن تكون إحدى القيم APPROVED أو DECLINED أو IN_REVIEW أو KYC_EXPIRED. لا يمكن تعديل الجلسات التي لم تصل بعد إلى حالة قابلة للمراجعة. تحديثات شركة KYB لا تخضع لشرط على الحالة.
يجب أن يكون سجل الميزة موجودًا: لا يمكنك تعديل حقول KYC إلا إذا كانت الجلسة قد سجّلت ميزة KYC، ولا تعديل حقول POA إلا إذا كانت قد سجّلت ميزة POA، ولا تعديل بيانات شركة KYB إلا إذا كانت الجلسة تتضمن فحص سجل.
التحديثات الجزئية: لا يتغير إلا الحقول التي تُرسلها. أغفل الحقل لإبقائه كما هو. أرسل null لمسح مفتاح من extra_fields.
webhook: عند نجاح التحديث يُطلق الحدث data.updated مع session_kind: "user" أو "business"، ويسجّل سجل تدقيق الجلسة الحقول المحددة التي تغيّرت ومن غيّرها.

تحديث بيانات هوية KYC

PATCH /v3/session/{sessionId}/update-data/ عدّل أي حقل مستخرج من وثيقة الهوية. يدعم سير عمل متعدد المثيلات يعتمد على المخطط عبر معامل الاستعلام الاختياري node_id أو حقل في نص الطلب، لاستهداف سجل KYC محدد عندما تحتوي الجلسة الواحدة على عدة خطوات KYC.

الحقول القابلة للتعديل

الحقل	ملاحظات
`document_type`	رمز الوثيقة وفق ISO: `P` (جواز سفر)، `ID`، `DL`، `RP`.
`document_number`	رقم الوثيقة المطبوع.
`personal_number`	الرقم الشخصي أو الرقم الضريبي عند طباعته على الوثيقة.
`date_of_birth`	تاريخ بصيغة ISO 8601.
`date_of_issue` / `expiration_date`	تواريخ بصيغة ISO 8601.
`issuing_state`	دولة الإصدار، بصيغة ISO 3166-1 alpha-3.
`first_name` / `last_name`	يُعاد حساب `full_name` تلقائيًا من هذين الحقلين.
`gender`	`M` أو `F` أو `X` عند وجوده.
`nationality`	نص حر.
`marital_status`	نص حر.
`place_of_birth`	نص حر.
`address`	العنوان النصي من الوثيقة. يؤدي إلى إعادة تحديد الإحداثيات الجغرافية.
`parsed_address`	عنوان منظّم، انظر الشكل المتداخل أدناه.
`extra_fields`	حقول إضافية مخصصة من وثيقة الهوية (مثل `blood_group` و`municipality`). أرسل `null` لمفتاح لإزالته.

يقبل parsed_address مفاتيح متداخلة محددة فقط: address_type، city، region، street_1، street_2، postal_code، country (بصيغة ISO 3166-1 alpha-2).

مثال

curl -X PATCH "https://verification.didit.me/v3/session/4c5c7f3a.../update-data/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-01-01",
    "issuing_state": "ESP",
    "extra_fields": { "municipality": "Madrid" }
  }'

في سير عمل متعدد المثيلات يعتمد على المخطط، أضف ?node_id=feature_ocr_2 إلى الرابط (أو مرّر "node_id": "feature_ocr_2" في الجسم) لاستهداف سجل KYC محدد.

تحديث بيانات إثبات العنوان (POA)

PATCH /v3/session/{sessionId}/update-poa-data/ عدّل الحقول المستخرجة من وثيقة إثبات العنوان. تنطبق عليه شروط الحالة نفسها والصلاحية نفسها كتحديثات KYC. ويدعم أيضًا node_id لسير العمل متعدد المثيلات.

الحقول القابلة للتعديل

الحقل	ملاحظات
`issuing_state`	الدولة التي أصدرت الوثيقة، بصيغة ISO 3166-1 alpha-3.
`document_type`	مثل `utility_bill` و`bank_statement` و`lease_agreement`.
`document_language`	لغة الوثيقة بصيغة ISO 639-1.
`issuer`	شركة الخدمات أو البنك أو المؤجر وغيرها.
`issue_date`	تاريخ بصيغة ISO 8601.
`poa_address`	العنوان كما هو مطبوع على الوثيقة (نص حر). يؤدي إلى إعادة تحديد الإحداثيات الجغرافية.
`name_on_document`	الاسم الكامل المطبوع على الوثيقة.
`poa_parsed_address`	عنوان منظّم، بالشكل المتداخل نفسه لـ `parsed_address` في KYC.
`extra_fields`	حقول خاصة بالوثيقة: تفاصيل البنك (`bank_account_number`، `bank_iban`، `bank_sort_code`، `bank_routing_number`، `bank_swift_bic`، `bank_branch_name`، `bank_branch_address`)، و`document_phone_number`، و`additional_names` (قائمة أو `null`).

مثال

curl -X PATCH "https://verification.didit.me/v3/session/4c5c7f3a.../update-poa-data/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "utility_bill",
    "issuer": "Iberdrola",
    "issue_date": "2026-03-15",
    "name_on_document": "Jane Doe",
    "poa_parsed_address": {
      "street_1": "Calle Mayor 10",
      "city": "Madrid",
      "postal_code": "28013",
      "country": "ES"
    }
  }'

تحديث بيانات الشركة في KYB

PATCH /v3/session/{sessionId}/kyb/{companyUuid}/update-data/ صحّح الحقول المستخرجة من السجل التجاري لشركة في KYB. يعدّل الـ endpoint الأعمدة القياسية لبيانات الشركة وregistry_data معاً، فيعكس عرض “المستخرج من السجل” في الكونسول تصحيحاتك. لا يُعدَّل user_provided_data (ما أكّده المستخدم النهائي في الصفحة المستضافة). يُسجَّل last_console_edit_at، ويُطلق webhook من نوع data.updated مع trigger: "console_registry_edit".

المتطلبات

الصلاحية: write:businesses (تختلف عن صلاحية KYC / POA).
يجب أن ينتمي companyUuid في العنوان إلى sessionId المحدد، وإلا ستحصل على 404.
لا يوجد شرط على حالة الجلسة، إذ يمكن تصحيح بيانات شركة KYB في أي وقت.

الحقول القابلة للتعديل

الحقل	ملاحظات
`company_name`	الاسم القانوني.
`registration_number`	رقم التسجيل الرسمي.
`country_code`	دولة التأسيس، بتنسيق ISO 3166-1 alpha-3.
`incorporation_date` / `registration_date` / `dissolution_date`	تواريخ بصيغة ISO 8601.
`tax_number`	الرقم الضريبي.
`legal_address`	اسم بديل لـ `registered_address`، ويُحفظ في العمود القياسي `registered_address`.
`company_type`	Ltd / LLC / PLC / SA / GmbH / SL وغيرها.
`registry_status`	القيم مثل `active` و`dissolved` و`struck_off` و`inactive` وغيرها.
`verification_status`	`verified` أو `failed` أو `unknown`.
`alternative_names`	الأسماء التجارية والأسماء السابقة وأسماء DBA.
`nature_of_business`	وصف موجز لنشاط الشركة.
`registered_capital`	رأس المال المصرّح به أو المُصدَر.
`website`، `email`، `phone`	بيانات الاتصال.
`legal_entity_identifier`	المعرّف القانوني للكيان (LEI).
`location_of_registration`	المدينة أو التقسيم الإداري.
`control_scheme`	نظام الحوكمة عندما يعرضه السجل.

أي حقل لا ترسله يبقى دون تغيير. أي حقل ترسله يُكتب في العمود القياسي (إن وُجد) ويُدمج في registry_data. تُسلسَل التواريخ كسلاسل بصيغة ISO 8601 عند دمجها في registry_data.

مثال

curl -X PATCH "https://verification.didit.me/v3/session/bs-01HJX1.../kyb/f7a9c1b2-4e6d.../update-data/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Corporation Limited",
    "registration_number": "12345678",
    "registry_status": "active",
    "legal_address": "1 Main Street, London EC1A 1AA, United Kingdom",
    "alternative_names": "Acme Ltd, Acme Group"
  }'

الاستجابة: كائن الشركة في KYB كاملاً، بالبنية نفسها لـ registry_checks[].company في قرار الجلسة.

تخطي طرف من الأشخاص الرئيسيين

PATCH /v3/session/{sessionId}/kyb/parties/{partyUuid}/ استثنِ طرفاً من الأشخاص الرئيسيين من التحقق. هذا هو المخرج الاستثنائي لطرف لن يتمكن أبداً من إكمال فحصه. السبب المعتاد هو جلسة فرعية محذوفة: فبمجرد حذف جلسة KYC الفردية المُسنَدة إلى مستفيد حقيقي أو مدير، تتجمد حالتها ولا يمكن حسمها أبداً، فلا يبقى في KYB ما يمكن أن ينقل الطرف خارج الحالة Awaiting User. يؤدي تخطي الطرف إلى إخراجه من تجميع الأشخاص الرئيسيين، فيُعاد احتساب الفحص فوراً، ويمكن للجلسة عندئذٍ أن تُحسم فتُقبل أو تُرفض.

المتطلبات

الصلاحية: write:businesses.
يجب أن ينتمي partyUuid في العنوان إلى sessionId المحدد، وإلا ستحصل على 404.
غير مقيّد بـ allow_skip. يحدد هذا الإعداد للدور ما يمكن لمقدّم الطلب تخطيه أثناء تعبئة شاشة الأشخاص الرئيسيين في الصفحة المستضافة. أما هذه النقطة فهي تجاوز يملكه المشغّل، لذا تعمل حتى على الأدوار التي لم يكن مقدّم الطلب ليتمكن من تخطيها.

نص الطلب

الحقل	النوع	ملاحظات
`is_skipped`	قيمة منطقية (boolean)	القيمة `true` تستثني الطرف، والقيمة `false` تُعيده إلى نطاق التحقق ويعود الفحص إلى انتظاره.

لا يُمسّ الحقل requires_verification عمداً، لذا يظهر الطرف المُتجاوَز بالقيمتين requires_verification: true و is_skipped: true. فالسجل يبيّن أن القواعد طلبت التحقق.

مثال

curl -X PATCH "https://verification.didit.me/v3/session/bs-01HJX1.../kyb/parties/0a3f1e2c-7c2f.../" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_skipped": true }'

الاستجابة: الطرف المحدَّث، بالبنية نفسها لعنصر من key_people_checks[].submitted.parties[] في قرار الجلسة. يُطلق webhook من نوع data.updated مع trigger: "console_key_people_skip".

يُعلَّم الطرف الذي حُذفت جلسته الفرعية في حمولة القرار بالقيمة kyc_session_deleted: true (أو kyb_sub_session_deleted: true للأطراف من الشركات)، ويُعاد kyc_session_url / kyb_sub_session_url الخاص به بالقيمة null لأن الرابط لم يعد يُفتح. حذف جلسة فرعية لا يؤدي، من تلقاء نفسه، إلى قبول الطرف أبداً، إذ ينتقل فحص الأشخاص الرئيسيين إلى الحالة In Review ليتخذ إنسان القرار.

ماذا يحدث بعد التحديث

webhook: يُطلق data.updated على الجلسة، ومعه session_kind الخاص بالجلسة في الحمولة ("user" أو "business"). اشترك مرة واحدة على مستوى الوجهة، ووجّه الأحداث حسب session_kind.
سجل التدقيق: تسجّل الجلسة بدقة الحقول التي تغيّرت، والقيم السابقة والجديدة، و(لاستدعاءات المصادقة للمستخدم) بريد الفاعل الإلكتروني. تظهر هذه السجلات في تبويب الأحداث في الكونسول.
إعادة الترميز الجغرافي للعنوان: بالنسبة لتحديثات KYC وPOA التي تغيّر address أو poa_address، يعيد Didit الترميز الجغرافي في الخلفية. تُتجاهل الأخطاء، فلا يفشل التحديث أبداً بسبب مشكلة في الترميز الجغرافي.
إعادة تقييم AML: قد تعيد تحديثات KYC التي تغيّر الاسم أو تاريخ الميلاد أو الجنسية تشغيل فحص AML إذا لم يكن قد انتهى في الجلسة. وتظهر النتائج في قرار الجلسة.

متى لا تستخدم هذه الـ endpoints

إعادة تشغيل التحقق كاملاً: إذا كان على العميل إعادة التقاط صورة هويته أو إعادة رفع مستند، فاستخدم update-status لنقل الجلسة إلى Resubmitted بدلاً من ذلك.
تغيير حقول الملف الشخصي لكيان المستخدم أو الشركة: استخدم PATCH /v3/users/{vendor_data}/ أو PATCH /v3/businesses/{vendor_data}/، فهذه الـ endpoints تحدّث بيانات على مستوى الكيان لا على مستوى الجلسة.
تعديل تفاصيل الأشخاص الرئيسيين: لا توجد واجهة API عامة لتعديل اسم الطرف أو أدواره أو ملكيته، إذ تُرسل هذه البيانات عبر الصفحة المستضافة. الحقل الوحيد القابل للتعديل هو is_skipped (انظر تخطي طرف من الأشخاص الرئيسيين).

الأخطاء

الحالة	المعنى
`401`	بيانات الاعتماد مفقودة أو غير صالحة.
`403`	المستدعي لا يملك الصلاحية المطلوبة (`write:sessions` أو `write:businesses`).
`404`	الجلسة غير موجودة، أو أنها لا تحتوي على السجل الذي تحاول تعديله (لا توجد بيانات KYC، أو POA، أو شركة مطابقة، أو طرف مطابق، أو طرف يتبع جلسة أخرى).
`400`	خطأ في التحقق: رمز دولة غير صالح، أو مفتاح غير معروف في `parsed_address`، أو `extra_fields` ليس كائنًا، وغير ذلك.

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

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

استرجع القرار الكامل لمعاينة الحقول المحدَّثة.

تحديث الحالة

قبول الجلسة أو رفضها أو إعادة فتحها بعد تصحيح البيانات.

webhook

اشترك في أحداث data.updated.

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

​المتطلبات المشتركة

​تحديث بيانات هوية KYC

​الحقول القابلة للتعديل

​مثال

​تحديث بيانات إثبات العنوان (POA)

​الحقول القابلة للتعديل

​مثال

​تحديث بيانات الشركة في KYB

​المتطلبات

​الحقول القابلة للتعديل

​مثال

​تخطي طرف من الأشخاص الرئيسيين

​المتطلبات

​نص الطلب

​مثال

​ماذا يحدث بعد التحديث

​متى لا تستخدم هذه الـ endpoints

​الأخطاء

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

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

تحديث الحالة

webhook

المتطلبات المشتركة

تحديث بيانات هوية KYC

الحقول القابلة للتعديل

مثال

تحديث بيانات إثبات العنوان (POA)

الحقول القابلة للتعديل

مثال

تحديث بيانات الشركة في KYB

المتطلبات

الحقول القابلة للتعديل

مثال

تخطي طرف من الأشخاص الرئيسيين

المتطلبات

نص الطلب

مثال

ماذا يحدث بعد التحديث

متى لا تستخدم هذه الـ endpoints

الأخطاء

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