> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # واجهة برمجة التحقق من الهوية: OCR والتحقق من الأصالة > تحقّق من مستندات الهوية في أكثر من 220 دولة و14,000+ نوع من المستندات مع Didit: الأصالة وOCR وMRZ، استجابة أقل من ثانيتين، دفع حسب الاستخدام بلا عقود. ## OpenAPI ````yaml ar/openapi-25.json POST /v3/id-verification/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API التحقق من الهوية. قم بالمصادقة باستخدام الرأس x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/id-verification/: post: tags: - Standalone APIs summary: التحقق من الهوية (OCR للمستند + فحوصات الاحتيال) description: >- إجراء قراءة OCR لمستند الهوية وتشغيل عمليات التحقق من الاحتيال في المستندات في استدعاء واحد — يُرجع حقول حامل المستند المستخرجة، وبيانات MRZ المحللة، و`status` بقيمة `Approved` أو `Declined` أو `In Review`، وقائمة `warnings` توضح كل مشكلة تم العثور عليها. يدعم 14,000+ نوع مستند من 220+ دولة وإقليم. **طريقة العمل.** أرسل `front_image` للمستند (مطلوب) و`back_image` للمستندات ذات الوجهين. ارفع صوراً غير مقتصة تظهر فيها جميع زوايا المستند الأربع بوضوح — تكتشف الخدمة المستند وتضبط محاذاته وتقتصّه تلقائياً، لذا لا تقم باقتصاصه مسبقاً. يتم تصنيف المستند تلقائياً (لا تحدد الدولة أو نوع المستند أبداً)، وتتم قراءة المنطقة المرئية باستخدام OCR، وفك تشفير الـ MRZ وأي رموز باركود. بعد ذلك، تتحقق عمليات الفحص المتبادل من التواريخ وصيغ الأرقام وأرقام التحقق في MRZ، وتقارن المنطقة المرئية مع الـ MRZ. عند تعيين `perform_document_liveness=true`، يتم فحص الصور إضافياً للتحقق من إعادة العرض على الشاشات والنسخ المطبوعة والتلاعب بالصورة الشخصية. **منطق القرار.** تكون `status` هي `Approved` ما لم يؤدِّ تحذير واحد على الأقل إلى الرفض. تؤدي مخاطر الاحتيال والفشل الجسيم دائماً إلى الرفض: `DOCUMENT_EXPIRED` و`SCREEN_CAPTURE_DETECTED` و`PRINTED_COPY_DETECTED` و`PORTRAIT_MANIPULATION_DETECTED` و`PUBLIC_DOCUMENT_IMAGE_DETECTED`، بالإضافة إلى إخفاقات الاستخراج (`NAME_NOT_DETECTED` و`DATE_OF_BIRTH_NOT_DETECTED` و`DOCUMENT_NUMBER_NOT_DETECTED`). (تتواجد `PORTRAIT_IMAGE_NOT_DETECTED` و`INVALID_DATE` و`MRZ_NOT_DETECTED` في جلسات سير العمل لكن لا ينتجها هذا الـ endpoint المستقل أبداً. وتُرجع `COULD_NOT_DETECT_DOCUMENT_TYPE` هنا عندما لا تتطابق الصورة الأمامية مع تصميم مستند رسمي معروف بدرجة ثقة عالية، وترفض الطلب.) يمكن تكوين ثلاث مجموعات مخاطر لكل طلب عبر `invalid_mrz_action` و`inconsistent_data_action` و`expiration_date_not_detected_action` (`DECLINE` أو `NO_ACTION`). كافة التحذيرات الأخرى (مثل `POSSIBLE_DUPLICATED_USER`) هي تحذيرات إعلامية ولا تؤدي إلى الرفض بمفردها أبداً. عندما يكون `perform_document_liveness=true` (الافتراضي) ولا يُرجع فحص التزوير أي درجة قابلة للاستخدام — كأن يفشل المزود أو يجيب برمز مختلف عن 200 أو يجيب بـ HTTP 200 مع `status="ERR"` - يُرجع الاستدعاء `200` مع `status: "In Review"` وتحذير `DOCUMENT_LIVENESS_NOT_COMPUTED` (`log_type: "warning"`) بدلاً من `Approved`: فالفحص الذي لم يعمل لا يُعد دليلاً على أن المستند أصلي. هذا التصعيد غير قابل للتكوين ولا يلغي أبداً حالة `Declined`؛ أما مع `perform_document_liveness=false` فيتم تخطي الفحص وتتبع الحالة التحذيرات المتبقية كما في السابق. المستند الذي لا يمكن معالجته على الإطلاق يُرجع `400` مع `{"error": "COULD_NOT_RECOGNIZE_DOCUMENT"}`؛ والمستند القابل للقراءة ولكن به مشكلات يُرجع `200` مع `status: "Declined"` — تحقق دائماً من `id_verification.status` و`id_verification.warnings`، وليس رمز HTTP فقط. **الفوترة.** يستهلك كل رد `200` رصيداً واحداً لـ API التحقق من الهوية (يُدفع من رصيد خطتك أو رصيد الشحن). عندما لا يغطي رصيد المؤسسة تكلفة الاستدعاء، يُرجع الـ endpoint الرمز `403` مع خطأ عدم كفاية الرصيد قبل أي معالجة للصور. **الاحتفاظ بالجلسة (`save_api_request`، الافتراضي `true`).** عند تعيينه على `true`، يتم حفظ الاستدعاء كجلسة من نوع API: يظهر في Business Console، ويكون `request_id` المُرجع معرّف جلسة حقيقياً يمكنك تمريره إلى `GET /v3/session/{sessionId}/decision/`، ويتم تخزين صور المستند/الصورة الشخصية المقتصة وإرجاعها كروابط وسائط قصيرة الأجل (`https:///ocr/...`)، ويتم إرسال webhook لحدث `status.updated` إلى وجهات webhook المكوّنة لديك. عند تعيينه على `false`، لا يتم تخزين أي شيء، ويكون `request_id` عبارة عن معرّف UUID للربط لمرة واحدة فقط، وتُرجع `portrait_image`/`front_image`/`back_image` مضمنة كنصوص JPEG بترميز base64. **البيئة التجريبية.** تتخطى مفاتيح API الخاصة بالبيئة التجريبية كافة عمليات المعالجة والفوترة: بعد التحقق من صحة الطلب (المدخلات غير الصالحة لا تزال تُرجع `400`)، يُرجع الـ endpoint حمولة وهمية ثابتة بحالة `Approved` (بطاقة هوية أمريكية خيالية باسم "Sandbox User")، ولا يتم حفظ أي جلسة، ولا يُستهلك أي رصيد. **المصادقة.** أرسل مفتاح API الخاص بتطبيقك في الرأس `x-api-key`. تُرجع بيانات الاعتماد المفقودة أو غير الصالحة الرمز `403` (`{"detail": "You do not have permission to perform this action."}`) — لا تُرجع هذه الـ API الرمز `401` أبداً. **حد المعدل.** ميزانية كتابة مشتركة تبلغ 300 طلب/دقيقة لكل مفتاح API عبر جميع الـ endpoints الخاصة بـ POST/PATCH/DELETE؛ وتجاوز هذا الحد يُرجع `429`. operationId: post_v3id-verification parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - front_image properties: front_image: type: string format: binary description: >- الوجه الأمامي لمستند الهوية. الامتدادات المسموح بها: `tiff`، `jpg`، `jpeg`، `png`، `webp`، `pdf`. الحد الأقصى لحجم الرفع: **10 MB** (يتم رفض الملفات الأكبر حجماً بالرمز `400`). يتم تحويل ملفات PDF إلى صورة قبل إجراء OCR؛ تتطلب ملفات PDF المشفرة `front_image_password`. يتم ضغط الصور تلقائياً إلى ~0.5 MB تقريباً وتطبيق اتجاه EXIF. ارفع الصورة الملتقطة كاملة وغير مقتطعة مع ظهور جميع الزوايا الأربع للمستند. front_image_password: type: string description: >- كلمة المرور لفك تشفير `front_image` عندما يكون ملف PDF مشفراً. إرسال ملف PDF مشفر بدون كلمة مرور (أو بكلمة مرور خاطئة) يُرجع الرمز `400`. writeOnly: true back_image: type: string format: binary description: >- الجانب الخلفي للمستند — أرسله كلما كان للمستند جانب خلفي (تحمل العديد من بطاقات الهوية منطقة MRZ أو رمزًا شريطيًا على الظهر؛ يؤدي حذفه ببساطة إلى ترك حقول MRZ والجانب الخلفي فارغة في الاستجابة — لا يُطلق هذا الـ endpoint تحذيرًا بشأن فقدان MRZ). ينطبق عليه نفس قيود التنسيق والحجم الخاصة بـ `front_image`. عند حذفه، تكون قيمة `back_image` وحقول الجانب الخلفي `null` في الاستجابة. back_image_password: type: string description: >- كلمة المرور لفك تشفير `back_image` عندما يكون ملف PDF مشفراً. writeOnly: true perform_document_liveness: type: boolean default: true description: >- يفحص كلا الصورتين للكشف عن احتيال العرض: إعادة تشغيل الشاشة (`SCREEN_CAPTURE_DETECTED`)، والنسخ المطبوعة (`PRINTED_COPY_DETECTED`)، والتلاعب بالصورة الشخصية (`PORTRAIT_MANIPULATION_DETECTED`). يؤدي أيٌّ منها إلى الرفض التلقائي. مفعلة افتراضياً؛ اضبطها على `false` لتخطي فحص الاحتيال وتقليل زمن الاستجابة. عند تفعيلها وعدم إرجاع المزود لأي درجة قابلة للاستخدام، تكون الاستجابة `In Review` مع تحذير `DOCUMENT_LIVENESS_NOT_COMPUTED` بدلاً من `Approved`. example: true minimum_age: type: integer nullable: true default: null minimum: 1 maximum: 120 description: >- مقبول ويتم التحقق من صحته (1–120) ولكن **لا يتم تطبيقه حاليًا** بواسطة هذا endpoint — فهو لا يصدر أبدًا تحذير `MINIMUM_AGE_NOT_MET` من هذا الحقل. قم بفرض قواعد العمر بناءً على `date_of_birth`/`age` المُرجعة، أو استخدم سير عمل جلسة تحقق مع قيود العمر. expiration_date_not_detected_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- الإجراء المتبع عند تعذر قراءة تاريخ الانتهاء (`EXPIRATION_DATE_NOT_DETECTED`). القيمة الافتراضية هي `NO_ACTION` لأن العديد من مستندات الهوية لا تطبع تاريخ انتهاء. ملاحظة: تاريخ الانتهاء *المكتشف والمنقضي* يؤدي دائماً إلى الرفض (`DOCUMENT_EXPIRED`)، بغض النظر عن هذا الخيار. invalid_mrz_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- الإجراء المتخذ عندما تفشل منطقة MRZ المستخرجة في التحقق من أرقام التحقق (`MRZ_VALIDATION_FAILED`). لا يؤدي غياب MRZ إلى إطلاق أي تحذير في هذا الـ endpoint. ينطبق فقط على المستندات التي تحتوي على MRZ. الخيار `REVIEW` غير مدعوم في هذا الـ endpoint ويُرجع `400`. inconsistent_data_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- الإجراء المتبع عند وجود عدم اتساق داخلي في البيانات المستخرجة: `DATA_INCONSISTENT`، أو `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` (اختلاف المنطقة المرئية عن MRZ)، أو `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS`. critical_field_occlusion_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- الإجراء المتبع عند تغطية حقل مطبوع مهم فعلياً في الصورة الملتقطة (`CRITICAL_FIELD_OCCLUSION_DETECTED`) - رقم الهوية، أو الاسم، أو تاريخ الميلاد، أو تاريخ الانتهاء. يتم الرفض افتراضياً، مثل مخاطر سلامة المستندات الأخرى في هذا الـ endpoint: فتغطية الأرقام التي تتم مطابقة التقرير معها هي المظهر الذي يبدو عليه المستند الخاضع للحجب. يتم استبعاد القيمة المقروءة للحقل المغطى من الاستخراج في كلتا الحالتين، لذا غالباً ما يرافقه تحذير `*_NOT_DETECTED` المطابق. لا يدعم هذا الـ endpoint القيمة `REVIEW` ويرجع الرمز `400`. document_or_personal_number_format_mismatch_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- الإجراء المتبع عندما لا يطابق رقمٌ التنسيقَ الذي تستخدمه الجهة المصدرة له لنوع المستند هذا (`DOCUMENT_NUMBER_FORMAT_MISMATCH`، و`PERSONAL_NUMBER_FORMAT_MISMATCH`). القيمة الافتراضية هي `NO_ACTION`، والتي تسجل التحذير دون تغيير الحالة. لا يدعم هذا الـ endpoint القيمة `REVIEW` ويرجع الرمز `400`. preferred_characters: type: string enum: - latin - non_latin default: latin description: >- نظام الكتابة المفضل لحقول الاسم/العنوان في المستندات التي تطبع نصوصاً لاتينية وغير لاتينية (العربية، السيريلية، CJK، …). يُرجع `latin` قيماً بالحروف اللاتينية/منسوخة صوتياً؛ ويفضل `non_latin` نظام الكتابة الأصلي. save_api_request: type: boolean default: true description: >- عندما تكون القيمة `true` (الافتراضية)، يتم حفظ الاستدعاء كجلسة من نوع API — مرئية في Business Console، ويمكن استرجاعها عبر `GET /v3/session/{sessionId}/decision/` باستخدام `request_id` المُرجع، ويتم الإشعار بها عبر webhook لحدث `status.updated`، مع إرجاع صور المستندات كروابط URL للوسائط. عندما تكون القيمة `false`، لا يتم تخزين أي شيء، ويكون `request_id` عبارة عن معرّف UUID مؤقت، ويتم إرجاع الصور مضمنة كسلاسل base64 JPEG. example: true vendor_data: type: string description: >- سلسلة نصية مبهمة اختيارية (معرّف المستخدم الداخلي لديك، البريد الإلكتروني، UUID...) تُخزَّن في الجلسة المحفوظة وتُعاد في الاستجابة. استخدمها لربط استدعاءات API بسجلاتك الخاصة ولتصفية الجلسات لاحقاً. example: user-123 metadata: type: object additionalProperties: true description: >- كائن JSON اختياري يُخزن مع الجلسة (عندما يكون `save_api_request=true`) ويُعاد في الاستجابة. في طلبات multipart، أرسله كحقل سلسلة نصية بترميز JSON (مثل `metadata={"flow":"onboarding"}`) — حيث يتم تحليله إلى كائن. example: flow: onboarding example: front_image: (binary JPEG/PNG/PDF of the document front) back_image: (binary JPEG/PNG/PDF of the document back) perform_document_liveness: true save_api_request: true vendor_data: user-123 metadata: flow: onboarding responses: '200': description: >- تمت معالجة المستند. تكون قيمة `id_verification.status` إما `Approved` أو `Declined` أو `In Review`؛ وتُفصّل كل مشكلة تم اكتشافها في `id_verification.warnings`. يتم إرجاع `In Review` عندما لا يسفر فحص حيوية المستند المطلوب عن نتيجة قابلة للاستخدام (`DOCUMENT_LIVENESS_NOT_COMPUTED`). المستند الذي يحتوي على مشاكل سيظل يُرجع `200` مع `status: "Declined"` — افحص نص الاستجابة، وليس فقط رمز HTTP. عندما تكون `save_api_request=true`، يكون `request_id` هو معرّف الجلسة المحفوظ وتكون حقول الصور عبارة عن روابط وسائط قصيرة الأجل؛ ومع `save_api_request=false` تكون سلاسل base64 JPEG مضمنة. content: application/json: examples: Approved: summary: >- تمت قراءة بطاقة الهوية ذات الوجهين بنجاح (تم الحفظ — الصور كروابط وسائط) value: request_id: 11d219ed-d59c-4b1d-8d65-9b933f12d5b8 id_verification: status: Approved document_type: Identity Card document_subtype: ID_CARD_GENERIC document_number: CBX164224 personal_number: 20446581H portrait_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-portrait_image-8c2f.jpg?signature=... front_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-front_image-4a1e.jpg?signature=... back_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-back_image-77b0.jpg?signature=... front_image_camera_front: null back_image_camera_front: null front_image_camera_front_face_match_score: null back_image_camera_front_face_match_score: null front_image_quality_score: focus_score: 78 brightness_score: 83.2 brightness_issue: ok is_document_fully_visible: true resolution_score: 40.7 overall_score: 70.2 back_image_quality_score: focus_score: 100 brightness_score: 95.6 brightness_issue: ok is_document_fully_visible: true resolution_score: 43 overall_score: 84.4 date_of_birth: '1980-01-13' age: 46 expiration_date: '2032-03-31' date_of_issue: '2022-03-31' issuing_state: ESP issuing_state_name: Spain first_name: Julio Francisco last_name: Fores Sena full_name: Julio Francisco Fores Sena gender: M address: >- Brda. Urb. El Cardonal 0052 52 Po3 B,Taco,San Cristobal De La Laguna,Santa Cruz De Tenerife formatted_address: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain place_of_birth: Valencia, Valencia marital_status: UNKNOWN nationality: ESP extra_fields: first_surname: Fores second_surname: Sena mrz: surname: FORES SENA name: JULIO FRANCISCO country: ESP nationality: ESP birth_date: '800113' expiry_date: '320331' sex: M document_type: ID document_number: CBX164224 optional_data: 20446581H optional_data_2: '' birth_date_hash: '9' expiry_date_hash: '8' document_number_hash: '3' final_hash: '3' personal_number: 20446581H warnings: [] errors: [] mrz_type: TD1 mrz_string: |- IDESPCBX164224320446581H<<<<<< 8001139M3203318ESP<<<<<<<<<<<3 FORES- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain raw_results: address_components: - long_name: b short_name: b types: - subpremise - long_name: '52' short_name: '52' types: - street_number - long_name: Avenida el Cardonal short_name: Av. el Cardonal types: - route - long_name: La Laguna short_name: La Laguna types: - locality - political - long_name: Spain short_name: ES types: - country - political - long_name: '38108' short_name: '38108' types: - postal_code formatted_address: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain geometry: location: lat: 28.4501161 lng: -16.3004407 location_type: ROOFTOP types: - street_address - subpremise document_location: latitude: 28.4501161 longitude: -16.3004407 label: Spain Identity Card Address is_verified: true category: Residential warnings: [] barcodes: [] vendor_data: user-123 metadata: flow: onboarding created_at: '2026-06-12T02:21:56.013573+00:00' Declined - expired document: summary: رفع الوجه الأمامي فقط لبطاقة هوية منتهية الصلاحية value: request_id: f61681b8-9422-4378-ac3e-04c6a247fb45 id_verification: status: Declined document_type: Identity Card document_subtype: ID_CARD_GENERIC document_number: BNK123072 personal_number: 21771255F portrait_image: >- https:///ocr/f61681b8-9422-4378-ac3e-04c6a247fb45-portrait_image-1d9a.jpg?signature=... front_image: >- https:///ocr/f61681b8-9422-4378-ac3e-04c6a247fb45-front_image-5c2b.jpg?signature=... back_image: null front_image_camera_front: null back_image_camera_front: null front_image_camera_front_face_match_score: null back_image_camera_front_face_match_score: null front_image_quality_score: focus_score: 100 brightness_score: 95.7 brightness_issue: ok is_document_fully_visible: true resolution_score: 22.2 overall_score: 79.3 back_image_quality_score: null date_of_birth: '1997-01-30' age: 29 expiration_date: '2025-11-26' date_of_issue: null issuing_state: ESP issuing_state_name: Spain first_name: Lucia last_name: Marin Castro full_name: Lucia Marin Castro gender: F address: null formatted_address: null place_of_birth: null marital_status: UNKNOWN nationality: ESP extra_fields: first_surname: Marin second_surname: Castro mrz: {} parsed_address: null warnings: - risk: DOCUMENT_EXPIRED feature: ID_VERIFICATION additional_data: null log_type: error short_description: Document expired long_description: >- The document's expiration date has passed, rendering it no longer valid for use. barcodes: [] vendor_data: user-123 metadata: null created_at: '2026-06-12T02:25:48.117204+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- معرّف الجلسة المحفوظة عندما تكون `save_api_request=true` (يمكن استخدامه مع `GET /v3/session/{sessionId}/decision/`)؛ وإلا فسيكون UUID ارتباط مؤقت. id_verification: type: object properties: status: type: string enum: - Approved - Declined - In Review description: >- `Approved` عندما لا يؤدي أي تحذير إلى الرفض ويُعطي فحص حيوية المستند المطلوب نتيجة قابلة للاستخدام؛ و`In Review` عندما لا يُعطي هذا الفحص المطلوب أي نتيجة قابلة للاستخدام (`DOCUMENT_LIVENESS_NOT_COMPUTED`)؛ و`Declined` عندما يؤدي تحذير إلى الرفض — وتوضح قائمة `warnings` السبب. document_type: type: string nullable: true description: >- الاسم المعروض لنوع المستند المكتشف: `Identity Card`، أو `Passport`، أو `Driver's License`، أو `Residence Permit`، أو `Health Insurance Card`، أو `Tax Card`. يكون `null` عندما يتعذر تصنيف المستند. example: Identity Card document_subtype: type: string nullable: true description: >- النوع الفرعي الأكثر دقة عند توفره (مثل `ID_CARD_GENERIC`، و`EPASSPORT`). example: ID_CARD_GENERIC document_number: type: string nullable: true example: CBX164224 personal_number: type: string nullable: true description: الرقم الشخصي/الوطني الثانوي المطبوع على بعض المستندات. example: 20446581H portrait_image: type: string nullable: true description: >- صورة شخصية مقتصة من المستند. رابط وسائط قصير الأجل (`https:///ocr/...`) عندما تكون قيمة `save_api_request=true` (افتراضياً)؛ أو سلسلة JPEG مضمنة بترميز base64 عندما تكون قيمة `save_api_request=false`. وتكون القيمة `null` في حال عدم اكتشاف أي صورة شخصية. front_image: type: string nullable: true description: >- قص محاذٍ للوجه الأمامي للمستند. رابط وسائط عند الحفظ، أو سلسلة base64 JPEG مضمنة بخلاف ذلك. back_image: type: string nullable: true description: >- قص محاذٍ للوجه الخلفي للمستند. `null` عندما لا يتم تحميل `back_image`. front_image_camera_front: type: string nullable: true description: >- دائماً `null` في هذا الـ endpoint (يتم ملؤه فقط في جلسات التحقق عبر التقاط الكاميرا). back_image_camera_front: type: string nullable: true description: دائماً `null` في هذا الـ endpoint. front_image_camera_front_face_match_score: type: number nullable: true description: دائماً `null` في هذا الـ endpoint. back_image_camera_front_face_match_score: type: number nullable: true description: دائماً `null` في هذا الـ endpoint. front_image_quality_score: type: object nullable: true description: >- بيانات تشخيص جودة الالتقاط للصورة المرفوعة (`null` إذا لم يتم توفير الجانب أو تعذر احتساب الدرجات). جميع الدرجات تتراوح بين 0 و100. properties: focus_score: type: number format: float description: >- حدة الصورة المقتصة من المستند (القيمة الأعلى تعني حدة أكبر). brightness_score: type: number format: float description: جودة التعرض (الأعلى أفضل). brightness_issue: type: string nullable: true description: >- `ok` عندما يكون التعريض الضوئي جيداً، وإلا فستكون المشكلة المكتشفة (مثل: داكن جداً / ساطع جداً). is_document_fully_visible: type: boolean nullable: true description: ما إذا كانت زوايا المستند الأربع كلها داخل الإطار. resolution_score: type: number format: float description: الدقة الفعلية لمنطقة المستند. overall_score: type: number format: float description: درجة الجودة المجمعة. back_image_quality_score: type: object nullable: true description: >- بيانات تشخيص جودة الالتقاط للصورة المرفوعة (`null` إذا لم يتم توفير الجانب أو تعذر احتساب الدرجات). جميع الدرجات تتراوح بين 0 و100. properties: focus_score: type: number format: float description: >- حدة الصورة المقتصة من المستند (القيمة الأعلى تعني حدة أكبر). brightness_score: type: number format: float description: جودة التعرض (الأعلى أفضل). brightness_issue: type: string nullable: true description: >- `ok` عندما يكون التعريض الضوئي جيداً، وإلا فستكون المشكلة المكتشفة (مثل: داكن جداً / ساطع جداً). is_document_fully_visible: type: boolean nullable: true description: ما إذا كانت زوايا المستند الأربع كلها داخل الإطار. resolution_score: type: number format: float description: الدقة الفعلية لمنطقة المستند. overall_score: type: number format: float description: درجة الجودة المجمعة. date_of_birth: type: string format: date nullable: true example: '1980-01-13' age: type: integer nullable: true description: عمر صاحب المستند بالسنوات، محسوباً من `date_of_birth`. example: 46 expiration_date: type: string format: date nullable: true example: '2032-03-31' date_of_issue: type: string format: date nullable: true example: '2022-03-31' issuing_state: type: string nullable: true description: دولة الإصدار (ISO 3166-1 alpha-3). example: ESP issuing_state_name: type: string nullable: true example: Spain first_name: type: string nullable: true example: Julio Francisco last_name: type: string nullable: true example: Fores Sena full_name: type: string nullable: true example: Julio Francisco Fores Sena gender: type: string nullable: true description: '`M` أو `F` أو `null` عندما لا تكون مطبوعة أو مكتشفة.' example: M address: type: string nullable: true description: العنوان تماماً كما هو مطبوع على المستند. formatted_address: type: string nullable: true description: النسخة المحددة جغرافياً والموحدة من `address`. place_of_birth: type: string nullable: true example: Valencia, Valencia marital_status: type: string nullable: true description: '`UNKNOWN` ما لم يطبع المستند الحالة الاجتماعية.' example: UNKNOWN nationality: type: string nullable: true description: جنسية صاحب المستند (ISO 3166-1 alpha-3). example: ESP extra_fields: type: object nullable: true additionalProperties: true description: >- بيانات إضافية خاصة بالمستند ليس لها عمود مخصص (مثل `first_surname`/`second_surname` في بطاقات الهوية الإسبانية، وفئات الترخيص في رخص القيادة). mrz: type: object description: >- منطقة القراءة الآلية المحللة. **كائن فارغ** (`{}`) عندما لا يحتوي المستند على MRZ أو تعذرت قراءتها — تحقق أيضاً من قائمة `warnings` في تلك الحالة. تستخدم التواريخ داخل MRZ التنسيق الخام `YYMMDD`. properties: surname: type: string example: FORES SENA name: type: string example: JULIO FRANCISCO country: type: string description: دولة الإصدار (ISO 3166-1 alpha-3). example: ESP nationality: type: string description: جنسية صاحب المستند (ISO 3166-1 alpha-3). example: ESP birth_date: type: string description: تاريخ الميلاد الخام من MRZ (`YYMMDD`). example: '800113' expiry_date: type: string description: تاريخ الانتهاء الخام من MRZ (`YYMMDD`). example: '320331' sex: type: string example: M document_type: type: string description: رمز نوع المستند في MRZ (مثل `ID`، `P`). example: ID document_number: type: string example: CBX164224 optional_data: type: string nullable: true example: 20446581H optional_data_2: type: string nullable: true example: '' birth_date_hash: type: string description: رقم التحقق من MRZ لتاريخ الميلاد. example: '9' expiry_date_hash: type: string description: رقم التحقق من MRZ لتاريخ الانتهاء. example: '8' document_number_hash: type: string description: رقم التحقق من MRZ لرقم المستند. example: '3' final_hash: type: string description: رقم التحقق المركب لـ MRZ. example: '3' personal_number: type: string nullable: true example: 20446581H warnings: type: array items: type: string description: تحذيرات غير حرجة عند تحليل MRZ. errors: type: array items: type: string description: >- أخطاء رقم التحقق/التحليل في MRZ. تظهر الأخطاء غير الفارغة كتحذير `MRZ_VALIDATION_FAILED`. mrz_type: type: string description: >- تخطيط MRZ: `TD1` (بطاقات الهوية، 3 أسطر)، أو `TD2`، أو `TD3` (جوازات السفر، سطرين). example: TD1 mrz_string: type: string description: >- نص MRZ الخام كما تمت قراءته، مع فصل الأسطر بواسطة `\n`. mrz_key: type: string description: >- مفتاح مركب (رقم المستند + أرقام التحقق) يُستخدم لعمليات الفحص المتقاطع. parsed_address: type: object nullable: true description: >- تفصيل مهيكل ومحدد جغرافياً لـ `address`. تكون قيمته `null` عندما لا يحمل المستند أي عنوان أو يتعذر تحليله. properties: street_1: type: string nullable: true example: Avenida el Cardonal 52 street_2: type: string nullable: true example: b city: type: string nullable: true example: La Laguna region: type: string nullable: true example: Canarias country: type: string nullable: true description: رمز الدولة وفقاً لـ ISO 3166-1 alpha-2. example: ES postal_code: type: string nullable: true example: '38108' address_type: type: string nullable: true example: Avenida formatted_address: type: string nullable: true description: سلسلة عنوان مرمز جغرافياً قياسية. example: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain raw_results: type: object additionalProperties: true description: >- payload الخام الخاص بالترميز الجغرافي (`address_components`، `geometry.location`، `place_id`، …) للمستهلكين المتقدمين. document_location: type: object nullable: true properties: latitude: type: number longitude: type: number description: الإحداثيات الجغرافية لعنوان المستند. label: type: string nullable: true description: أي حقل في المستند تمت قراءة العنوان منه. example: Spain Identity Card Address is_verified: type: boolean description: ما إذا كان الترميز الجغرافي قد أكد وجود العنوان. category: type: string nullable: true description: فئة العنوان (مثل `Residential`، `Commercial`). example: Residential warnings: type: array description: >- فارغ عند الموافقة السليمة. يوضح كل إدخال خطراً واحداً تم اكتشافه؛ تُعيّن الإدخالات ذات `log_type: "error"` الـ `status` إلى `Declined`، بينما يُعيّنه `DOCUMENT_LIVENESS_NOT_COMPUTED` (`log_type: "warning"`) إلى `In Review`. items: type: object properties: risk: type: string description: >- رمز مخاطر مقروء آلياً. مخاطر تؤدي دائماً إلى الرفض: `DOCUMENT_EXPIRED`، و`MINIMUM_AGE_NOT_MET`، و`PORTRAIT_IMAGE_NOT_DETECTED`، و`SCREEN_CAPTURE_DETECTED`، و`PRINTED_COPY_DETECTED`، و`PORTRAIT_MANIPULATION_DETECTED`، و`PUBLIC_DOCUMENT_IMAGE_DETECTED`، و`INVALID_DATE`، و`COULD_NOT_RECOGNIZE_DOCUMENT` (خاص بالرمز 400 فقط، ولا يكون تحذيراً أبداً)، و`DOCUMENT_NUMBER_NOT_DETECTED`، و`COULD_NOT_DETECT_DOCUMENT_TYPE`، و`NAME_NOT_DETECTED`، و`DATE_OF_BIRTH_NOT_DETECTED`. تحكمها خيارات الطلب: `MRZ_NOT_DETECTED` / `MRZ_VALIDATION_FAILED` (`invalid_mrz_action`)، و`DATA_INCONSISTENT` / `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` / `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS` (`inconsistent_data_action`)، و`EXPIRATION_DATE_NOT_DETECTED` (`expiration_date_not_detected_action`). المخاطر الأخرى (مثل `POSSIBLE_DUPLICATED_USER`) هي معلوماتية. يتم إطلاق `DOCUMENT_LIVENESS_NOT_COMPUTED` عندما يكون `perform_document_liveness=true` ولكن فحص التزوير لم يُرجع أي درجة قابلة للاستخدام؛ حيث يُعيّن `status` إلى `In Review`. كما يتم إرجاع `COULD_NOT_DETECT_DOCUMENT_TYPE` عندما لا تتطابق الجهة الأمامية من المستند مع تصميم مستند رسمي معروف بدرجة ثقة عالية، على سبيل المثال مستند معدّل أو مُنشأ بواسطة الكمبيوتر، أو تصميم غير مدعوم بعد. example: DOCUMENT_EXPIRED feature: type: string enum: - ID_VERIFICATION description: >- الميزة التي أصدرت التحذير. دائماً `ID_VERIFICATION` في هذا الـ endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- سياق إضافي لبعض المخاطر (على سبيل المثال، يتضمن `POSSIBLE_DUPLICATED_USER` الحقل `duplicated_session_id`)؛ ويكون `null` لمعظمها. log_type: type: string enum: - error - warning - information description: >- مستوى الخطورة. تحذيرات `error` تنقل `status` إلى `Declined`؛ وتحذيرات `warning` (فقط `DOCUMENT_LIVENESS_NOT_COMPUTED`، عندما لا يُنتج فحص التزوير المطلوب أي درجة صالحة للاستخدام) تنقل `status` إلى `In Review`؛ وإدخالات `information` استشارية ولا تغيّر الحالة أبداً. short_description: type: string description: ملخص للمخاطر في سطر واحد مقروء للبشر. long_description: type: string description: تفسير سهل القراءة للمخاطر. barcodes: type: array description: >- الرموز الشريطية التي تم فك ترميزها من المستند (PDF417، QR، …). فارغة عندما لا يحتوي المستند على أي منها أو يتعذر قراءة أي منها. items: type: object properties: type: type: string description: >- نوع الرمز الشريطي (مثل `PDF417`، و`QR_CODE`، و`UNKNOWN`). position: type: object nullable: true additionalProperties: true description: موقع الباركود في الصورة، عند توفره. data: type: string description: payload مفكوك الترميز. data_raw: type: string description: payload الخام (غير المفكك)، عندما يكون مختلفاً. side: type: string nullable: true description: '`front` أو `back`.' vendor_data: type: string nullable: true description: نسخة مطابقة من `vendor_data` التي أرسلتها، أو `null`. metadata: type: object nullable: true additionalProperties: true description: نسخة مطابقة من كائن `metadata` الذي أرسلته، أو `null`. created_at: type: string format: date-time description: >- طابع زمني بتنسيق ISO 8601 (بالتوقيت العالمي المنسق UTC) لوقت إنشاء الاستجابة. '400': description: >- خطأ في التحقق أو المعالجة. تُرجع المشكلات على مستوى الحقول غلاف DRF القياسي (مصفوفة واحدة من الرسائل لكل حقل مخالف). وتُرجع مشكلات ملفات PDF المشفرة `{"detail": ...}`. وتُرجع صورة المستند التي يتعذر التعرف فيها على أي مستند على الإطلاق `{"error": "COULD_NOT_RECOGNIZE_DOCUMENT"}`. ويمكن أن تفشل عمليات رفع PDF بالإضافة إلى ذلك مع "The submitted PDF file is corrupted or invalid." أو خطأ عدم وجود صفحات. content: application/json: examples: Missing front image: summary: '`front_image` غير مدرجة في بيانات النموذج' value: front_image: - No file was submitted. Unsupported file extension: summary: امتداد الملف خارج tiff/jpg/jpeg/png/webp/pdf value: front_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp, pdf. File too large: summary: يتجاوز الملف المرفوع حد 10 ميجابايت value: front_image: - File size should not exceed 10 MB Invalid option value: summary: تقبل الخيارات DECLINE أو NO_ACTION فقط value: invalid_mrz_action: - '"REVIEW" is not a valid choice.' Encrypted PDF: summary: تم تحميل ملف PDF بدون كلمة المرور المطلوبة value: detail: >- The PDF is encrypted. Please upload a decrypted PDF or a photo instead. Wrong PDF password: summary: >- `front_image_password` / `back_image_password` لا يفك تشفير ملف PDF value: detail: >- The PDF password is incorrect. Please provide the correct password. Document not recognized: summary: تعذر اكتشاف أي مستند هوية في الصورة value: error: COULD_NOT_RECOGNIZE_DOCUMENT PDF conversion failure: summary: تعذر تحويل ملف PDF المرفوع إلى صورة value: error: Failed to convert front image PDF. '403': description: >- تم رفض الإذن. يُرجع عند فقدان الرأس `x-api-key`، وأيضاً عندما لا يتمكن رصيد المؤسسة الطالبة من تغطية الاستدعاء؛ ويُرجع المفتاح الخاطئ أو الملغى أو منتهي الصلاحية `401`. يؤدي المفتاح المفقود إلى إرجاع `403` مع `{"detail": ...}`؛ ويؤدي المفتاح الخاطئ أو الملغى أو منتهي الصلاحية إلى إرجاع `401`. يُرجع نقص الرصيد `403` مع `{"error": ...}` قبل إجراء أي معالجة للصور. content: application/json: examples: Missing or invalid API key: summary: لا يوجد رأس `x-api-key`، أو أن المفتاح غير صالح/ملغى value: detail: You do not have permission to perform this action. Not enough credits: summary: رصيد المؤسسة لا يمكنه تغطية تكلفة الاستدعاء value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- تم تجاوز حد المعدل. تشترك نقاط endpoint الخاصة بـ POST/PATCH/DELETE في ميزانية قدرها 300 طلب كتابة في الدقيقة لكل مفتاح API (إنشاء المعاملات واستيعاب الأحداث لهما ميزانية منفصلة تبلغ 600). تتضمن الاستجابة رؤوس `X-RateLimit-Limit` و`X-RateLimit-Remaining` و`X-RateLimit-Reset` و`Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: أكثر من 300 طلب كتابة في الدقيقة الحالية value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '503': $ref: '#/components/responses/DocumentProcessingBusy' security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/id-verification/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'front_image=@./id_front.jpg' \ -F 'back_image=@./id_back.jpg' \ -F 'perform_document_liveness=true' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.id_verification.verify( front_image=open("front_image.jpg", "rb"), back_image=open("back_image.jpg", "rb"), perform_document_liveness=True, save_api_request=True, vendor_data="user-123", metadata={"flow": "onboarding"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.idVerification.verify({ front_image: await fileFromPath("front_image.jpg"), back_image: await fileFromPath("back_image.jpg"), perform_document_liveness: true, save_api_request: true, vendor_data: "user-123", metadata: { flow: "onboarding" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDVerification.Verify(ctx, didit.IDVerificationVerifyParams{\n\tFrontImage: didit.FileFromPath(\"front_image.jpg\"),\n\tBackImage: didit.Some(didit.FileFromPath(\"back_image.jpg\")),\n\tPerformDocumentLiveness: didit.Bool(true),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"onboarding\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import java.util.Map; import me.didit.Didit; import me.didit.types.IdVerificationVerifyParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.idVerification().verify(IdVerificationVerifyParams.builder() .frontImage(Path.of("front_image.jpg")) .backImage(Path.of("back_image.jpg")) .performDocumentLiveness(true) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "onboarding")) .build()); System.out.println(result); - lang: php label: PHP source: |- idVerification->verify([ 'front_image' => File::fromPath('front_image.jpg'), 'back_image' => File::fromPath('back_image.jpg'), 'perform_document_liveness' => true, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'onboarding'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.id_verification.verify( front_image: Pathname("front_image.jpg"), back_image: Pathname("back_image.jpg"), perform_document_liveness: true, save_api_request: true, vendor_data: "user-123", metadata: { flow: "onboarding" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.IdVerification.VerifyAsync(new IdVerificationVerifyParams { FrontImage = FileUpload.FromPath("front_image.jpg"), BackImage = FileUpload.FromPath("back_image.jpg"), PerformDocumentLiveness = true, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "onboarding" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: responses: DocumentProcessingBusy: description: >- تجري معالجة عدد كبير جداً من المستندات في الوقت الحالي، لذا لم تتم معالجة عملية الرفع هذه: لم يتم تخزين أي شيء ولم تُستهلك أي محاولة. أعد إرسال الملف نفسه بعد انقضاء عدد الثواني المحدد في `Retry-After`. اعتمد في التفريع البرمجي على `code`، وليس على نص الرسالة. headers: Retry-After: description: عدد الثواني للانتظار قبل إرسال الطلب نفسه مرة أخرى. schema: type: integer example: 10 content: application/json: schema: type: object required: - detail - code properties: detail: type: string code: type: string enum: - document_processing_busy example: detail: We are busy processing documents. Please try again in a moment. code: document_processing_busy securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console. يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير 404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.