الانتقال إلى المحتوى الرئيسي
PATCH
curl

دعم KYC وKYB

يعمل هذا endpoint بالطريقة نفسها مع جلسات التحقق من المستخدم (KYC) والتحقق من الشركات (KYB). يحلّ Didit قيمة session_id ضمن كلا نوعَي الجلسات، والتحقق من انتقالات الحالة واحد في الحالتين، إذ تنطبق قائمة الحالات نفسها على النوعين. لا تتضمن الاستجابة سوى session_id. اقرأ session_kind من استرجاع الجلسة عندما يحتاج منطقك اللاحق إلى التفريق بين النوعين.

الانتقالات المسموحة

يمكنك نقل الجلسة إلى Approved أو Declined أو Resubmitted. أي قيمة أخرى لـ new_status، بما فيها In Review، تعيد 400. يجب أن تكون الحالة الحالية للجلسة واحدة من Approved أو Declined أو In Review أو Kyc Expired أو Abandoned أو Resubmitted، وإلا أعادت الواجهة 400. تعيين Approved أو Declined على جلسة لها هذه الحالة بالفعل لا يُحدِث أي تغيير: تعيد الواجهة 200 ولا تغيّر شيئًا، ولا تُطلق أي webhook ولا ترسل أي بريد إلكتروني. تعيين Resubmitted على جلسة هي Resubmitted بالفعل يعيد 400 (The new status is the same as the current status.). تُنفَّذ إعادة التقديم التي تحتوي nodes_to_resubmit فيها على ميزات خلفية فقط (AML وDATABASE_VALIDATION وIP_ANALYSIS) تلقائيًا، وتعيد الجلسة إلى حالة حُسم فيها القرار دون أي تفاعل من المستخدم. تكرار إعادة التقديم هذه خلال 30 ثانية يعيد 429 Too Many Requests مع الترويسة Retry-After، لأن التكرار الفوري لا يمكن أن يعطي نتيجة مختلفة. لا تُعِد التقديم تلقائيًا من معالج webhook كلما وصلتك حالة In Review، بل راجِع النتيجة أو غيّر البيانات الأساسية أولًا.

معاينة البريد الإلكتروني أولًا

عند ضبط send_email: true، ترسل Approved وDeclined إلى الشخص بريد القرار الخاص به، وترسل Resubmitted إليه رابطًا جديدًا مع الأسباب. يمكنك الاطلاع على هذا البريد قبل أن تغيّر أي شيء:
  1. استدعِ معاينة بريد القرار الإلكتروني للحالة Approved أو Declined، أو معاينة بريد إعادة التقديم الإلكتروني للحالة Resubmitted.
  2. تحقّق من subject وhtml المعروضين، وrecipient، وقيمتي will_be_sent / not_sent_reason.
  3. استدعِ هذه الواجهة بالقيمة new_status نفسها (وبالقيمة nodes_to_resubmit نفسها في حالة إعادة التقديم)، مع send_email: true، وemail_address مضبوطًا على recipient، وemail_language بالقيمة التي عاينتها، وemail_preview_token مضبوطًا على preview_token.
لا تغيّر أيٌّ من المعاينتين الجلسة ولا ترسل شيئًا. ثم يرسل التحديث البريد الذي عاينته تمامًا. تنتهي صلاحية الإيصال بعد 15 دقيقة. إذا تغيّر المستلم أو اللغة أو حالة الجلسة أو المُرسِل أو البريد منذ المعاينة، يعيد التحديث 409 قبل أن يتغيّر أي شيء؛ أعِد المعاينة وأكّد باستخدام الإيصال الجديد. إرسال email_preview_token دون send_email: true يعيد 400. خطوة المعاينة اختيارية: يمكن للتكاملات القائمة أن تواصل استدعاء هذا endpoint دونها.

أمثلة

الإذن

يتطلب الإذن write:sessions. ويغطي الإذن نفسه النوعين معًا.

ذو صلة

التفويضات

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.

معلمات المسار

sessionId
string<uuid>
مطلوب

معرّف UUID لجلسة التحقق المطلوب تحديثها. يقبل معرّفات جلسات المستخدمين (KYC) والشركات (KYB) — يطابق الخادم المعرّف عبر كلا نوعي الجلسات.

مثال:

"11111111-2222-3333-4444-555555555555"

الجسم

application/json
new_status
enum<string>
مطلوب

الحالة المستهدفة. تسجّل Approved وDeclined قراراً يدوياً نهائياً (يمكن لكل منهما أيضاً نقض الآخر). تمسح Resubmitted الخطوات المحددة وتُعيد الجلسة إلى المستخدم. تُرجع أي قيمة أخرى الرمز 400.

الخيارات المتاحة:
Approved,
Declined,
Resubmitted
مثال:

"Approved"

comment
string

سبب التغيير بنص حر، يُخزَّن في مسار مراجعة الجلسة ويُعاد في مصفوفة reviews ضمن Get Decision. على سبيل المثال Duplicated user.

مثال:

"All checks passed manual review"

nodes_to_resubmit
object[]

خطوات سير العمل التي يجب على المستخدم إعادتها. يتم تطبيقها فقط عندما تكون قيمة new_status هي Resubmitted. بالنسبة للحالتين Approved/Declined، يظل التحقق من صحة المدخلات وفقاً للمخطط سارياً (أي قيمة غير صالحة لـ feature تُرجع 400) ولكن المدخلات الصالحة وفقاً للمخطط يتم تجاهلها دلالياً. في حال حذفها، يحدد الخادم تلقائياً المحاولات الحالية لـ OCR وكشف الحيوية ومطابقة الوجه وPOA ورقم الهاتف والبريد الإلكتروني وفحص AML والتحقق من قواعد البيانات والاستبيانات التي تكون حالتها Declined أو In Review أو Not Finished أو Expired (لا يتم تحديد محاولات NFC وتحليل IP وتقدير العمر والبحث بالوجه ومستندات KYB تلقائياً على الإطلاق؛ ويتم تحديد محاولات الوجه بخلاف مطابقة الوجه كـ LIVENESS) — الميزات التي لم يحاول المستخدم إجراؤها مطلقاً (لا توجد محاولة مسجلة) لن يتم تحديدها، وبالتالي فإن الجلسة التي تحتوي على صفر من المحاولات تُرجع 400 ("No features found that need resubmission") على الرغم من عدم قبول أي شيء؛ مرّر nodes_to_resubmit صراحة في هذه الحالة. يتم تنفيذ الخطوات وفقاً لترتيب مخطط سير العمل بغض النظر عن الترتيب الذي ترسله بها. يتم رفض KYB_REGISTRY وKYB_KEY_PEOPLE والاسم البديل KYB بالرمز 400 — تُعاد حوسبة عمليات التحقق الرئيسية تلك من جلسات KYC الفرعية الخاصة بها.

send_email
boolean
افتراضي:false

ما إذا كان سيتم إرسال بريد إلكتروني إلى المستخدم بشأن التغيير. يتطلب email_address. بالنسبة إلى Approved/Declined، يتلقى المستخدم إشعاراً بالحالة؛ وبالنسبة إلى Resubmitted، يتضمن البريد الإلكتروني رابط التحقق وأسباب إعادة الإرسال لكل خطوة.

مثال:

false

email_address
string<email>

المستلم لبريد الإشعار الإلكتروني. مطلوب عندما يكون send_email بقيمة true — يؤدي حذفه إلى إرجاع 400.

مثال:

"user@example.com"

email_language
string
افتراضي:en

لغة البريد الإلكتروني للإشعار. يقبل أي سلسلة نصية على مستوى المخطط؛ تعود الرموز غير المدعومة تلقائياً وبصمت إلى اللغة الإنجليزية (en).

مثال:

"en"

email_preview_token
string
write-only

إيصال اختياري من معاينة بريد القرار الإلكتروني (لـ Approved و Declined) أو معاينة بريد إعادة التقديم الإلكتروني (لـ Resubmitted): رمز preview_token الخاص به. صالح فقط مع send_email: true؛ بدونه يُرجع الطلب 400. يجب أن يظل المستلم واللغة وحالة الجلسة والمرسل والبريد الإلكتروني (والخطوات المحددة، في حالة إعادة التقديم) متطابقة مع المعاينة، وتنتهي صلاحية الإيصال بعد 15 دقيقة. وإلا فإن الطلب يُرجع 409 قبل تغيير الجلسة أو إرسال بريد إلكتروني. يجوز لعمليات التكامل الحالية إغفال هذا الحقل.

Required string length: 1 - 512

الاستجابة

تم تحديث الحالة. تحتوي الاستجابة فقط على session_id؛ يمكنك جلب الجلسة المحدثة عبر Get Decision. يتم تشغيل webhook الخاص بـ status.updated بمجرد تطبيق التغيير. يؤدي تكرار Approved أو Declined إلى إرجاع نفس نص الاستجابة دون تغيير أي شيء.

session_id
string<uuid>

معرّف UUID للجلسة المحدّثة.

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