الانتقال إلى المحتوى الرئيسي
POST
cURL

التفويضات

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.

الجسم

multipart/form-data
document
file
مطلوب

مستند إثبات العنوان. الامتدادات المسموح بها: tiff، وjpg، وjpeg، وpng، وpdf، وwebp. الحد الأقصى لحجم الرفع: 15 MB (يتم رفض الملفات الأكبر حجماً بالرمز 400). ملفات PDF متعددة الصفحات مدعومة (توقع استجابة أبطأ)؛ وتتطلب ملفات PDF المشفرة document_password. يتم ضغط الصور تلقائياً قبل معالجتها.

document_password
string
write-only

كلمة المرور لفك تشفير document عندما يكون ملف PDF مشفراً. إرسال ملف PDF مشفر بدون كلمة مرور (أو بكلمة مرور خاطئة) يُرجع الرمز 400.

expected_address
string

العنوان المراد التحقق منه مقابل المستند. يتم تحديد موقعه الجغرافي ومقارنته بالعنوان المستخرج؛ وأي عدم تطابق (أو عنوان متوقع يتعذر تحديد موقعه الجغرافي/التحقق منه) يضيف ADDRESS_MISMATCH_WITH_PROVIDED، الخاضع لـ poa_address_mismatch_action. وتتم إعادة إرسال الصيغة المحددة جغرافياً في expected_details_formatted_address / expected_details_parsed_address.

مثال:

"Av. Monseñor Tavella 1291, Salta, Argentina"

expected_country
string

الدولة المراد التحقق منها مقابل المستند (رمز ISO 3166-1، مثل ARG أو AR). يضيف عدم التطابق مع دولة المستند POA_COUNTRY_MISMATCH_WITH_PROVIDED، وتتحكم به poa_address_mismatch_action.

مثال:

"ARG"

expected_first_name
string

الاسم الأول للتحقق منه ومطابقته مع name_on_document (مطابقة تقريبية، تأخذ في الاعتبار الترجمة الصوتية). الدرجة الأقل من حد المطابقة تضيف NAME_MISMATCH_WITH_PROVIDED، وتخضع لـ poa_address_mismatch_action.

مثال:

"Sophia"

expected_last_name
string

اسم العائلة للتحقق منه مقابل name_on_document، مدمجاً مع expected_first_name لاحتساب درجة التطابق.

مثال:

"Martinez"

poa_languages_allowed
string

قائمة مفصولة بفواصل بلغات المستندات المقبولة كرموز ISO 639-1 (مثل en,es,fr). عند إغفالها أو تركها فارغة، يتم قبول جميع اللغات المدعومة البالغ عددها 51 لغة. يضيف المستند المكتوب بلغة خارج القائمة UNSUPPORTED_DOCUMENT_LANGUAGE (تخضع لـ poa_unsupported_language_action)؛ ويعيد الرمز غير المعروف في القائمة 400 مع المجموعة الكاملة من الرموز المدعومة.

مثال:

"en,es"

poa_document_age_months
string

أزواج key:value مفصولة بفواصل تحدد الحد الأقصى لعمر المستند بالأشهر لكل نوع مستند — المفاتيح: utility_bill، bank_statement، government_issued_document، other_poa_document؛ القيم: من 1 إلى 120، أو -1 لغير محدود (بدون فحص العمر). القيم الافتراضية عند الإغفال: utility_bill:3,bank_statement:3,government_issued_document:12,other_poa_document:12. يُرفض المستند الأقدم من حده مع POA_DOCUMENT_EXPIRED. تنبيه: عند تقديم هذا الحقل، اذكر كل نوع تقبله — يتم التعامل مع الأنواع المُغفلة على أنها غير مقبولة (إشعار POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION) ويتم تخطي فحص العمر الخاص بها.

مثال:

"utility_bill:3,bank_statement:6"

poa_name_mismatch_action
enum<string>
افتراضي:DECLINE

مقبول ولكن لا يتم تطبيقه حاليًا — تتبع تحذيرات عدم تطابق الأسماء (NAME_MISMATCH_WITH_PROVIDED) الإجراء poa_address_mismatch_action بدلاً من ذلك. قم بتعيين poa_address_mismatch_action للتحكم في سلوك عدم تطابق كل من الاسم والعنوان.

الخيارات المتاحة:
DECLINE,
NO_ACTION
poa_document_issues_action
enum<string>
افتراضي:DECLINE

الإجراء المتبع عند وجود مشكلات في سلامة الملف — عملياً ينتج فقط DOCUMENT_METADATA_MISMATCH عن هذا الـ endpoint.

الخيارات المتاحة:
DECLINE,
NO_ACTION
poa_document_authenticity_action
enum<string>
افتراضي:DECLINE

الإجراء المتبع عند الاشتباه في تلاعب بالمستند (SUSPECTED_DOCUMENT_MANIPULATION) — كأن يتم تعديل ملف PDF بعد التوقيع الرقمي، أو معالجته بمحرر PDF معروف، أو إظهار تلاعب بنصوص متراكبة، أو وجود تواريخ EXIF غير متسقة. يحكم أيضاً POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT (حقل نصي أعيدت كتابته ولا يمكن للملف إثبات تغييره أو عدمه): DECLINE يرفضه أيضاً، وNO_ACTION يبقيه كتحذير.

الخيارات المتاحة:
DECLINE,
NO_ACTION
poa_unsupported_language_action
enum<string>
افتراضي:DECLINE

الإجراء المتخذ عندما تكون لغة المستند خارج poa_languages_allowed (UNSUPPORTED_DOCUMENT_LANGUAGE).

الخيارات المتاحة:
DECLINE,
NO_ACTION
poa_address_mismatch_action
enum<string>
افتراضي:DECLINE

الإجراء المتخذ عندما تتعارض التفاصيل المستخرجة مع حقول expected_*: تتبع جميع حالات ADDRESS_MISMATCH_WITH_PROVIDED وNAME_MISMATCH_WITH_PROVIDED وPOA_COUNTRY_MISMATCH_WITH_PROVIDED هذا الإجراء.

الخيارات المتاحة:
DECLINE,
NO_ACTION
poa_issuer_not_identified_action
enum<string>
افتراضي:DECLINE

الإجراء المتبع عند تعذر تحديد الشركة/المؤسسة المصدرة على المستند (ISSUER_NOT_IDENTIFIED).

الخيارات المتاحة:
DECLINE,
NO_ACTION
save_api_request
boolean
افتراضي:true

عندما تكون القيمة true (الافتراضية)، يتم حفظ الاستدعاء كجلسة من نوع API — مرئية في Business Console، ويمكن استرجاعها عبر GET /v3/session/{sessionId}/decision/ باستخدام request_id المُرجع، ويتم الإشعار بها عبر webhook لحدث status.updated، مع تخزين المستند المرفوع. عندما تكون القيمة false، لا يتم تخزين أي شيء ويكون request_id عبارة عن معرّف UUID مؤقت للربط بالاستجابة فقط.

مثال:

true

vendor_data
string

سلسلة نصية مبهمة اختيارية (معرّف المستخدم الداخلي لديك، البريد الإلكتروني، UUID...) تُخزَّن في الجلسة المحفوظة وتُعاد في الاستجابة. استخدمها لربط استدعاءات API بسجلاتك الخاصة ولتصفية الجلسات لاحقاً.

مثال:

"user-123"

metadata
object

كائن JSON اختياري يُخزن مع الجلسة (عندما يكون save_api_request=true) ويُعاد في الاستجابة. في طلبات multipart، أرسله كحقل سلسلة نصية بترميز JSON (مثل metadata={"flow":"onboarding"}) — حيث يتم تحليله إلى كائن.

مثال:

الاستجابة

تمت معالجة المستند. تكون قيمة poa.status إما Approved أو Declined؛ وتُفصّل كل مشكلة تم اكتشافها في poa.warnings. المستند منتهي الصلاحية أو غير المتطابق أو المشبوه سيظل يُرجع 200 مع status: "Declined" — افحص نص الاستجابة، وليس فقط رمز HTTP. عندما تكون save_api_request=true، يكون request_id هو معرّف الجلسة المحفوظ.

request_id
string<uuid>

معرّف الجلسة المحفوظة عندما تكون save_api_request=true (يمكن استخدامه مع GET /v3/session/{sessionId}/decision/)؛ وإلا فسيكون UUID ارتباط مؤقت.

poa
object
vendor_data
string | null

نسخة مطابقة من vendor_data التي أرسلتها، أو null.

metadata
object | null

نسخة مطابقة من كائن metadata الذي أرسلته، أو null.

created_at
string<date-time>

طابع زمني بتنسيق ISO 8601 (بالتوقيت العالمي المنسق UTC) لوقت إنشاء الاستجابة.

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