> ## 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. # واجهة التحقق من قواعد البيانات: مطابقة الهوية الوطنية > تحقق من بيانات الهوية عبر POST /v3/database-validation/ مع Didit: أكثر من 100+ مصدر وطني وعالمي، ومطابقة شلالية 1x1 و2x2. الدفع لكل استدعاء. ## الخدمات القائمة على العنوان بالنسبة إلى الخدمات التي تتحقق من عنوان سكني أو عنوان خدمات المرافق، يمكنك إرسال قيمة `address` واحدة، وستقوم Didit بتقسيمها قبل تنفيذ الفحص. للحصول على أفضل معدل تطابق، أرسل حقول العنوان المنظمة الخاصة بـ Didit مباشرةً: | الحقل | المعنى | | - | - | | `address_element_1` | عنوان الشارع، بما في ذلك رقم المبنى ونوع الشارع | | `address_element_2` | الوحدة أو المبنى أو الطابق أو أي سطر عنوان إضافي (اختياري) | | `address_element_3` | الحي أو المنطقة أو المجاورة | | `address_element_4` | المدينة أو البلدة أو الولاية أو المحافظة أو الإقليم | | `address_element_5` | الرمز البريدي | تُعطى الحقول المنظمة الأولوية على قيمة `address` المفردة. يُقبل `postal_code` كاسم بديل للحقل `address_element_5`. ## الموافقة تتطلب بعض خدمات قواعد البيانات موافقةً صريحةً من المستخدم النهائي قبل إمكانية الاستعلام من المزوّد. يضع كتالوج الخدمات علامة `requires_consent=true` على هذه الصفوف. أرسل `consent=true` عندما تنطبق موافقة المستخدم على الخدمات المحددة. ترفض Didit الطلب قبل أي استدعاء للمزوّد أو أي حدث فوترة، إذا كانت إحدى الخدمات المحددة تتطلب الموافقة ولم ترسلها. ## تحميل الملفات يستخدم التحقق من قواعد البيانات الصيغة `multipart/form-data`. تعرض خدمات القياسات الحيوية التي تتطلب `selfie` هذا الحقل كحقل لتحميل ملف في واجهة تجربة API، فيمكنك اختيار صورة مباشرةً بدلاً من لصق مسار أو سلسلة base64. في الشيفرة، حمّل الملف باستخدام صيغة multipart المعتادة: ```bash theme={null} -F "selfie=@./selfie.jpg" ``` ## أخطاء التحقق تتحقق Didit من الحقول المطلوبة وبنية العنوان والصيغ الخاصة بكل خدمة، قبل استدعاء المزوّد. على سبيل المثال، تتوقع خدمات السجلات الصينية مثل `chn_national_id` و`chn_passport_verification` أن يكون `full_name` بالكتابة الصينية الأصلية، ويتطلب `chn_national_id` أيضاً رقم هوية وطنية صينياً صالحاً من 15 أو 18 خانة مع مجموع تحقق صحيح. إذا تعذّر تنفيذ الطلب، تُعيد الواجهة أخطاء حقول صريحة ولا تتم فوترة أي استخدام. وإذا فشل المزوّد بعد التحقق المسبق، تتضمن الاستجابة `validation_errors`، وتحفظ طلبات API المحفوظة هذه الأخطاء في نتيجة التحقق من قواعد البيانات. ## المدخلات المرفوضة والنتائج غير المتاحة عندما لا تُعيد أي خدمة نتيجةً قابلةً للاستخدام، افحص كل عنصر في `validation_errors` قبل أن تقرر إعادة المحاولة. رمز حالة HTTP وحده لا يحدد ما إذا كانت إعادة المحاولة مناسبةً. تعني الاستجابة `400` مع `code: "provider_rejected_input"` و`retryable: false` أن كل محاولة لم تُجَب قد رفضت المدخلات صراحةً. صحّح البيانات المرسلة قبل المحاولة مرة أخرى. لا تتم فوترة هذه المحاولات. تعني الاستجابة `502` مع `code: "empty_provider_response"` و`retryable: true` أن الخدمة لم تتمكن من إنتاج نتيجة قابلة للاستخدام لسبب آخر. ويشمل ذلك حالة رفض المدخلات متبوعةً ببديل غير متاح، أو ببديل لا يقدم أي تفسير. أعد المحاولة لاحقاً؛ فالاستجابة لا تثبت أن المدخلات خاطئة. إذا استمر فشل قاعدة بيانات، ترسل Didit بريداً إلكترونياً إلى المؤسسات التي استخدمتها مؤخراً مرة واحدة عند استمرار الانقطاع، ومرة أخرى عندما تؤكد الفحوصات الفعلية أنها تستجيب. راجع [إشعارات التوفر](https://docs.didit.me/ar/core-technology/database-validation/overview.md#إشعارات-التوفر). عندما يفشل بعض الخدمات المحددة فقط، ينجح الطلب بدلاً من ذلك: تكون الاستجابة `200`، وتُدرج الخدمات الفاشلة ضمن `database_validation.errors[]`، ولكل منها الحقلان `code` و`retryable` نفسهما. عندئذٍ تتبع `database_validation.status` الخدمات التي أجابت، ويمكن أن تكون `Approved`، لذا افحص `errors[]` في كل استجابة، لا في الاستجابات `4xx` أو `5xx` فقط. الخدمة المُبلَّغ عنها هناك لا تظهر في `validations` ولا في `services_used`، ولا تتم فوترة هذه الخدمة، فأعد المحاولة لتلك الخدمة وحدها. قد تتطلب أخطاء `502` الأخرى تصحيح المدخلات. على سبيل المثال، يصف `provider_invalid_input` و`provider_validation_error` مدخلات رفضها المصدر، ولا يجوز إعادة إرسالها دون تغيير، حتى عندما تُغفل الاستجابة القديمة الحقل `retryable`. لا تنطبق إرشادات إعادة المحاولة الخاصة بـ `empty_provider_response` على هذه الرموز. النتيجة النهائية التي تدل على عدم وجود تطابق هي فحص مكتمل، وليست فشلاً في التوفر. ## OpenAPI ````yaml ar/openapi-25.json POST /v3/database-validation/ 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/database-validation/: post: tags: - Standalone APIs summary: التحقق من قواعد البيانات (مستقل) description: >- التحقق من بيانات هوية الشخص مقابل المصادر الحكومية ومصادر السجلات الرسمية — CPF في البرازيل، وRENAPER في الأرجنتين، وسجلات DNI في إسبانيا وبيرو، وINE في المكسيك، و100+ خدمة أخرى عبر 60+ دولة. **اختيار الخدمة.** تتيح كل دولة خدمة واحدة أو أكثر من خدمات الدليل المحددة بواسطة `service_id` (مثل `bra_cpf`، و`arg_renaper`، و`pan_cedula_sib`). حدد الخدمات التي تريدها باستخدام مصفوفة `services` — وإذا حذفتها، فسيتم تشغيل خدمة افتراضية **واحدة** فقط (الخدمة المباشرة الأقدم في تلك الدولة). يؤدي إرسال `services` أيضًا إلى تبديل الاستجابة إلى الشكل الموسع مع `services_used` و`match_score`. استكشف الخدمات، وحقولها المطلوبة، وأسعارها عبر `GET /v1/organization/database-validation-countries/` (وهو endpoint للدليل غير موثق في هذه المواصفات) أو محرر سير العمل في Business Console. تُميز بعض الخدمات بعلامة `requires_consent=true` في الدليل وتتطلب `consent=true`؛ بينما تتطلب خدمات أخرى التسجيل لمؤسستك قبل أن تتمكن من استدعائها. **حقول الإدخال.** يُعد `identification_number` حقلاً عامًا يتم تعيينه إلى الحقل المناسب الخاص بالدولة تلقائيًا (راجع وصفه). يتم فرض قواعد تنسيق الدولة قبل استدعاء أي مزود (على سبيل المثال، يجب أن يتكون BRA CPF من 11 رقمًا بالضبط)، ولا تتم فوترة حالات فشل التنسيق أبدًا. تحتاج الخدمات البيومترية إلى تحميل `selfie` (بتنسيق multipart فقط)؛ وتتطلب خدمة RENAPER في الأرجنتين حقل `gender` بالإضافة إلى ذلك. **النتائج.** تُرجع كل خدمة خريطة `validation` لكل حقل بالإضافة إلى `outcome_code` محايد بالنسبة للمزودين (`MATCH`، `PARTIAL_MATCH`، `NO_MATCH`، `DOCUMENT_NOT_FOUND`، `INVALID_DOCUMENT_FORMAT`، `INVALID_INPUT`، `MINOR_BLOCKED`، `DECEASED`، `BIOMETRIC_NO_MATCH`، `BIOMETRIC_IMAGE_UNUSABLE`، `INCONCLUSIVE`، `DOCUMENT_SUPERSEDED`، `REGISTRY_UNAVAILABLE`، `REGISTRY_ERROR`). لاحِظ الفروق: `NO_MATCH` هو عدم تطابق قاطع، و`INCONCLUSIVE` يعني أن السجل لم يتمكن من التأكيد بأي من الطريقتين (مراجعة، وليس رفضًا)، و`BIOMETRIC_IMAGE_UNUSABLE` مشكلة فنية في الصورة السيلفي (إعادة التقاط)، بخلاف `BIOMETRIC_NO_MATCH` القاطع. يجمع `match_type` الإجمالي عبر الخدمات (أي تطابق كامل → `full_match`، وإلا فإن أي تطابق جزئي → `partial_match`، وإلا `no_match`) ويقوم `no_match_action`/`partial_match_action` بترجمته إلى `status` النهائي. يتم اشتقاق `validation_type`: `two_by_two` عندما تسفر خدمتان مميزتان أو أكثر عن تطابق كامل (على رقم الهوية، أو على الاسم الكامل + تاريخ الميلاد معًا، أو على العنوان دون تناقضات)، وإلا يكون `one_by_one`. **الاحتفاظ بالبيانات.** القيمة الافتراضية لـ `save_api_request` هي **true**: يتم تخزين النتيجة كجلسة (يعمل `request_id` مع `GET /v3/session/{sessionId}/decision/`)، وتظهر في لوحة التحكم، وتُطلق حدث webhook من نوع `status.updated`. كما يتحكم أيضًا في شكل `validations` — كائنات لكل خدمة عند الحفظ، وخريطة `{field: match}` مدمجة عند عدم الحفظ. **الفوترة.** لكل خدمة: يتم تحصيل سعر الدليل الخاص بكل خدمة تُرجع نتيجة قابلة للفوترة. لا تتم فوترة الخدمات الفاشلة أو التي تم تخطيها، ولا تترتب أي تكلفة على الطلبات المرفوضة برمز `400`. يغطي فحص الرصيد المسبق مجموع أسعار الخدمات المحددة (ويُرجع `403` في حالة عدم الكفاية). **حالات الفشل.** عندما لا تُرجع أي خدمة محددة نتيجة قابلة للاستخدام، تُرجع واجهة API الرمز `400` مع `validation_errors` إذا كانت كل محاولة لم تتم الإجابة عليها قد رفضت المدخلات صراحة (`provider_rejected_input`، `retryable: false`). صحح المدخلات قبل المحاولة مرة أخرى. وإلا فإنها تُرجع `502` مع `validation_errors` (`empty_provider_response`، `retryable: true`)، بما في ذلك المحاولات التي تجمع بين رفض المدخلات وعدم توفر خيارات التراجع الاحتياطية؛ ولا تتم فوترة أي شيء (تظل الجلسة مسجلة بالحالة `Not Finished` عندما يكون `save_api_request=true`). وعندما تفشل بعض الخدمات فقط، تتضمن الاستجابة `200` حالات الفشل هذه في `database_validation.errors`. **البيئة التجريبية.** تتخطى المفاتيح الخاصة بتطبيقات البيئة التجريبية استدعاءات السجلات والفوترة وتُرجع استجابة `full_match` ثابتة — يتضمن payload البيئة التجريبية دائمًا `services_used` و`match_score: 100` بغض النظر عن كيفية إرسال `services`، لذا لا تتحقق من منطق تفعيل الشكل الموسع في بيئة الإنتاج أو من كون `match_score` كسرًا يتراوح بين 0.0 و1.0 مقابل استجابات البيئة التجريبية. أرسل الطلب بتنسيق `application/json`، أو كـ `multipart/form-data` عند تحميل `selfie`. operationId: post_v3database-validation parameters: [] requestBody: required: true content: application/json: schema: type: object required: - issuing_state properties: issuing_state: type: string description: >- رمز الدولة وفقاً لـ ISO 3166-1 **alpha-3** للسجل المراد التحقق منه (مثل `BRA`، `ESP`، `COL`). يحدد الخدمات المتاحة. الرموز غير المدعومة تُرجع `400` مع القائمة الكاملة للخيارات الصالحة. example: BRA services: type: array items: type: string description: >- معرّفات `service_id` من الدليل لتشغيلها لهذه الدولة (مثل `["bra_cpf"]`). يقبل أيضاً سلسلة نصية مفردة أو سلسلة مفصولة بفواصل/مرمزة بتنسيق JSON. **إذا تم حذفه أو تُرك فارغاً، فسيتم تشغيل خدمة افتراضية واحدة فقط** — وهي الخدمة العاملة الأقدم للدولة؛ أما الخدمات الأحدث والبيومترية وخدمات الدفع حسب الاستخدام فيجب تحديدها صراحةً. إرسال `services` يغيّر شكل الاستجابة إلى الشكل الموسع (يضيف `services_used` و`match_score`). يجب أن يكون كل معرّف موجوداً ونشطاً في `issuing_state`؛ والخدمات التي تتطلب التسجيل تُرجع الرمز `400` حتى يتم تفعيلها لمؤسستك. يمكنك استكشاف الخدمات المتاحة لكل دولة عبر `GET /v1/organization/database-validation-countries/` (وهو endpoint للدليل غير موثق في هذه المواصفة) أو عبر محرر سير العمل في Business Console. example: - bra_cpf validation_type: type: string deprecated: true description: >- مهمل. يُقبل للتوافق مع الإصدارات السابقة ولكن يتم تجاهله — يُشتق `validation_type` في الاستجابة الآن من عدد الخدمات التي تطابقت بالكامل. استخدم `services` لتحديد خدمات معينة. consent: type: boolean default: false description: >- يُضبط على `true` عندما يوافق المستخدم النهائي صراحةً على خدمات التحقق المحددة. مطلوب للخدمات التي تحمل العلامة `requires_consent=true` في الدليل — وبدونه تُرجع هذه الخدمات رمز `400` مع `services_requiring_consent`. identification_number: type: string description: >- رقم التعريف الشامل — يتم تعيينه تلقائيًا إلى الحقل المخصص للدولة الصحيحة، لذا يمكنك استخدامه بدلاً من `personal_number`/`tax_number`/`document_number`: ARG→document_number (DNI)، BOL→document_number (CI)، BRA→tax_number (CPF، 11 رقماً)، CHL→personal_number (RUT)، COL→personal_number (Cédula)، CRI→personal_number (Cédula)، DOM→personal_number (Cédula، 11 رقماً)، ECU→personal_number (Cédula، 10 أرقام)، ESP→personal_number (DNI/NIE)، GTM→document_number (DPI)، HND→document_number (DNI)، MEX→personal_number (CURP، 18 حرفاً)، PAN→personal_number (Cédula)، PER→personal_number (DNI، 8 أرقام)، PRY→document_number (CI)، SLV→document_number (DUI)، URY→personal_number (CI)، VEN→document_number (Cédula). لا يتجاوز أبدًا أي حقل مخصص للدولة تم تقديمه صراحةً. first_name: type: string description: الاسم الأول للفرد. مطلوب في بعض الخدمات/الدول. example: John last_name: type: string description: اسم العائلة للفرد. مطلوب في بعض الخدمات/الدول. example: Doe middle_name: type: string description: >- الاسم الأوسط، يُستخدم بواسطة خدمات بعض الدول (أستراليا، نيوزيلندا، ...). full_name: type: string description: >- الاسم الكامل — تقبل بعض الخدمات هذا بدلاً من الاسم الأول/اسم العائلة (مثل خدمات CHN، التي تطابق الاسم بنظام الكتابة الأصلي). date_of_birth: type: string format: date description: تاريخ الميلاد، `YYYY-MM-DD`. مطلوب من قبل العديد من الخدمات. example: '1980-01-01' personal_number: type: string description: >- معرّف شخصي فريد صادر عن الحكومة. يُستخدم في: CHL (RUT)، COL (Cédula)، CRI، DOM، ECU، ESP (DNI/NIE)، MEX (CURP)، PAN (Cédula)، PER (DNI)، URY. يُفضَّل استخدام `identification_number` بدلاً منه. tax_number: type: string description: >- الرقم الضريبي. يُستخدم من قبل: BRA (CPF، مكون من 11 رقماً). فكّر في استخدام `identification_number` بدلاً منه. document_number: type: string description: >- رقم المستند. يُستخدم بواسطة: ARG (DNI)، وBOL (CI)، وGTM (DPI)، وHND (DNI)، وPRY (CI)، وSLV (DUI)، وVEN (Cédula). فكّر في استخدام `identification_number` بدلاً من ذلك. document_type: type: string enum: - P - DL - ID - RP - SSC - HIC - WP - TC - VISA - PSC - BC - OTHER description: >- نوع المستند الذي يتم التحقق منه: `P` جواز سفر، `DL` رخصة قيادة، `ID` بطاقة هوية وطنية، `RP` تصريح إقامة (بالإضافة إلى `SSC`، `HIC`، `WP`، `TC`، `VISA`، `PSC`، `BC`، `OTHER`). مطلوب لبعض الخدمات (مثل ESP). expiration_date: type: string format: date description: >- تاريخ انتهاء المستند، `YYYY-MM-DD`. مطلوب للتحقق في إسبانيا (ESP). example: '2030-01-15' date_of_issue: type: string format: date description: >- تاريخ إصدار المستند، `YYYY-MM-DD` (fecha de expedición). مطلوب للتحقق من cédula في كولومبيا (COL). example: '2015-06-20' nationality: type: string description: >- الجنسية وفق معيار ISO 3166-1 alpha-3. مطلوبة من قِبل بعض الخدمات. gender: type: string enum: - M - F - X description: >- الجنس: `M`، أو `F`، أو `X` (آخر/غير معروف). مطلوب للتحقق من RENAPER في الأرجنتين (`arg_renaper`). address: description: >- عنوان السكن. يُفضّل الكائن المهيكل `{"street_1":"123 Main St","street_2":"Apt 4B","city":"Springfield","region":"IL","postal_code":"62701","country":"US"}`؛ لا تزال السلسلة النصية الكاملة في سطر واحد مقبولة. مطلوب لخدمات التحقق من العنوان؛ وعندما تحدد الخدمة متطلبات العنوان، فإن الأجزاء المفقودة تُرجع `400` مع `address_fields_required_by`. oneOf: - type: object properties: street_1: type: string street_2: type: string city: type: string region: type: string postal_code: type: string country: type: string - type: string description: العنوان الكامل في سطر واحد (قديم). address_element_1: type: string description: >- عنوان الشارع بما في ذلك رقم الشارع ونوعه. إذا تم حذفه، فسيتم استنتاجه من `address`. address_element_2: type: string description: >- شقة، وحدة، مبنى، طابق، أو سطر عنوان إضافي. أرسله فقط عندما يتوفر لديك بشكل صريح. address_element_3: type: string description: >- المدينة، أو الضاحية، أو الحي، أو المنطقة، أو المجاورة. إذا تم حذفه، فسيتم استنتاجه من `address`. address_element_4: type: string description: >- الولاية أو المقاطعة أو المنطقة أو البلدة. إذا تم حذفه، يُستنتج من `address`. address_element_5: type: string description: الرمز البريدي. يُقبل `postal_code` كاسم بديل. postal_code: type: string description: >- الرمز البريدي للخدمات المعتمدة على العنوان (اسم بديل لـ `address_element_5`). driver_license_number: type: string description: >- رقم رخصة القيادة لخدمات التحقق من المستندات الحكومية (AUS، NZL، IND). driver_license_card_number: type: string description: >- رقم بطاقة رخصة القيادة الفعلية، حيث يُطلب بشكل منفصل عن رقم الرخصة (أستراليا). driver_license_state: type: string description: ولاية أو إقليم إصدار رخصة القيادة (AUS). driver_license_version: type: string description: رمز إصدار رخصة القيادة (NZL). passport_number: type: string description: >- رقم جواز السفر لخدمات التحقق الحكومية من جوازات السفر (AUS وNZL وIND وCHN). passport_expiration_date: type: string format: date description: >- تاريخ انتهاء جواز السفر، بصيغة `YYYY-MM-DD`، لخدمات التحقق من جوازات السفر. passport_file_number: type: string description: رقم ملف جواز السفر (IND). passport_issue_country: type: string description: >- دولة إصدار جواز السفر (ISO 3166-1 alpha-3) لخدمات التحقق من جوازات السفر. medicare_card_number: type: string description: رقم بطاقة Medicare (أستراليا). immi_card_number: type: string description: رقم بطاقة ImmiCard الأسترالية. immi_card_expiry_date: type: string format: date description: تاريخ انتهاء بطاقة ImmiCard الأسترالية. citizenship_certificate_number: type: string description: رقم شهادة المواطنة (أستراليا). birth_registration_number: type: string description: رقم تسجيل شهادة الميلاد (أستراليا). birth_registration_date: type: string format: date description: تاريخ تسجيل شهادة الميلاد (أستراليا). birth_registration_state: type: string description: ولاية تسجيل شهادة الميلاد (أستراليا). marriage_certificate_number: type: string description: رقم شهادة الزواج (أستراليا). change_of_name_certificate_number: type: string description: رقم شهادة تغيير الاسم (AUS). first_partner_name: type: string description: الاسم الأول للشريك في عقد الزواج (أستراليا). last_partner_name: type: string description: اسم العائلة للشريك في وثيقة الزواج (AUS). voter_id: type: string description: رقم تسجيل الناخب (IND EPIC، IRL). epic_card: type: string description: رقم بطاقة الناخب EPIC للهند. pan: type: string description: 'الهند: رقم الحساب الدائم (PAN).' national_id: type: string description: رقم الهوية الوطنية (CHN، وMYS، وKEN، وKHM، وNGA، وZAF، و…). cic: type: string description: >- رمز تعريف بطاقة الهوية (CIC) التابع لـ INE/IFE المكسيكي، 9 أرقام. يُستخدم بواسطة خدمة صلاحية بيانات اعتماد MEX INE (`mex_ine_vigencia`). identificador_ciudadano: type: string description: >- مُعرّف المواطن (Identificador del Ciudadano) للمعهد الانتخابي الوطني المكسيكي INE (9 أرقام). يُستخدم مع `cic` لنماذج INE الحديثة (E/F/G/H) في `mex_ine_vigencia`. ocr: type: string description: >- رقم OCR للمعهد الانتخابي الوطني المكسيكي INE (13 رقمًا، ظهر البطاقة). يُستخدم مع `cic` للنموذج D في `mex_ine_vigencia`. voter_number: type: string description: >- مفتاح الناخب (Clave de Elector) للمعهد الانتخابي الوطني المكسيكي INE (18 حرفًا). يُستخدم مع `emission_number` لنماذج IFE القديمة (A/B/C) في `mex_ine_vigencia`. emission_number: type: string description: >- رقم الإصدار (Número de Emisión) للمعهد الانتخابي الوطني المكسيكي INE. يُستخدم مع `voter_number` لنماذج IFE القديمة (A/B/C) في `mex_ine_vigencia`. bvn: type: string description: رقم التحقق المصرفي النيجيري. bank_card_number: type: string description: رقم البطاقة البنكية (التحقق من البطاقة البنكية في CHN). company_registration_number: type: string description: >- رقم تسجيل الشركة الصادر عن سجل الشركات: مثل CNPJ في البرازيل (على سبيل المثال `11222333000181`)، ورقم التسجيل في جنوب إفريقيا (على سبيل المثال `1936/007721/06`). مطلوب لخدمات سجل الشركات ومديري الشركات (`bra_company_registry`، `bra_company_directors`، `zaf_company_registry`، `zaf_company_directors`). company_name: type: string description: >- اسم الشركة المسجل، بعد مطابقته مع قيد السجل. اختياري لـ `zaf_company_registry`. initials: type: string description: >- الأحرف الأولى من اسم الشخص كما هي مطبوعة على المستند. مطلوبة لـ `zaf_drivers_license`؛ ومقبولة لـ `zaf_bank_account_holder`. licence_number: type: string description: >- رقم رخصة القيادة كما هو مطبوع على البطاقة، لـ `zaf_drivers_license`. عند حذفه، يُستخدم `document_number`. refugee_file_number: type: string description: >- رقم ملف اللاجئ الصادر عن وزارة الشؤون الداخلية في جنوب أفريقيا. مطلوب لـ `zaf_refugee`. bank_name: type: string description: >- اسم البنك الذي يحتفظ بالحساب. يتطلبه `zaf_bank_account_holder`. bank_account_number: type: string description: >- رقم الحساب البنكي. مطلوب بواسطة `zaf_bank_account_holder`؛ ومقبول بواسطة `zaf_fraud_prevention`. account_type: type: string description: >- نوع الحساب البنكي لـ `zaf_bank_account_holder`: `current`، أو `savings`، أو `transmission`، أو `subscriptionShare`، أو `notKnown`، دون حساسية لحالة الأحرف. تُرجع أي قيمة أخرى `400`. احذفه عندما لا تعرف النوع: سيتم بعد ذلك الإبلاغ عن التحقق المتبادل من نوع الحساب بأنه غير مؤكد. phone_number: type: string description: >- رقم الهاتف المحمول للتواصل، للخدمات التي تتحقق من إمكانية التواصل (`zaf_bank_account_holder`، `zaf_fraud_prevention`، `zaf_refugee`). right_thumb: type: string description: >- بصمة الإبهام الأيمن بترميز Base64 لـ `zaf_dha_fingerprint_match`، مع `left_thumb` أو بمفردها. left_thumb: type: string description: >- بصمة الإبهام الأيسر بترميز Base64 لـ `zaf_dha_fingerprint_match`، مع `right_thumb` أو بمفردها. score_level: type: integer description: >- الحد الأدنى لمستوى الدرجة البيومترية لـ `zaf_criminal_face_screening`. القيمة الافتراضية هي `3`. max_matches: type: integer description: >- الحد الأقصى لعدد التطابقات المرشحة التي يرجعها `zaf_criminal_face_screening`. القيمة الافتراضية هي `1`. vehicle_register_number: type: string description: >- رقم تسجيل المركبة. مطلوب، مع `vehicle_licence_plate` و`vin`، بواسطة `zaf_vehicle_ownership`. vehicle_licence_plate: type: string description: >- رقم لوحة ترخيص المركبة. مطلوب، مع `vehicle_register_number` و`vin`، بواسطة `zaf_vehicle_ownership`. vin: type: string description: >- رقم تعريف المركبة (VIN أو رقم الشاسيه). مطلوب، مع `vehicle_register_number` و`vehicle_licence_plate`، بواسطة `zaf_vehicle_ownership`. ssn: type: string description: رقم الضمان الاجتماعي (الولايات المتحدة الأمريكية). phone: type: string description: رقم الهاتف لخدمات التحقق من رقم الهاتف. landline: type: string description: رقم الهاتف الأرضي لخدمات التحقق من رقم الهاتف. email: type: string format: email description: عنوان البريد الإلكتروني لخدمات التحقق من الهوية. country_of_residence: type: string description: >- دولة الإقامة وفق المعيار ISO 3166-1 alpha-2. تُستخدم بواسطة خدمات إثراء الهوية العالمية (مثل `glb_identity_enrichment`) لتركيز البحث. example: US partial_match_action: type: string enum: - DECLINE - NO_ACTION default: NO_ACTION description: >- ما يفعله `partial_match` بحالة `database_validation.status`. القيمة الافتراضية هي `NO_ACTION` (تبقى الحالة `Approved`، مع تحذير). no_match_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- ما يفعله `no_match` بحالة `database_validation.status`. القيمة الافتراضية هي `DECLINE`. save_api_request: type: boolean default: true description: >- حفظ التحقق كجلسة (الظهور في لوحة التحكم، endpoint القرار، webhook الخاص بـ `status.updated`). يُغيّر أيضاً شكل استجابة `validations`: كائنات لكل خدمة عندما تكون القيمة `true` (افتراضياً)، وخريطة حقول مدمجة عندما تكون `false`. vendor_data: type: string description: >- المعرّف الخاص بك للمستخدم الذي تم التحقق منه؛ تتم إعادته وتخزينه مع الجلسة. metadata: type: object nullable: true description: كائن JSON بصيغة حرة يُخزن مع الطلب وتتم إعادته في الاستجابة. example: issuing_state: BRA services: - bra_cpf identification_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' vendor_data: user-1234 multipart/form-data: schema: type: object required: - issuing_state properties: issuing_state: type: string description: >- رمز الدولة وفقاً لـ ISO 3166-1 **alpha-3** للسجل المراد التحقق منه (مثل `BRA`، `ESP`، `COL`). يحدد الخدمات المتاحة. الرموز غير المدعومة تُرجع `400` مع القائمة الكاملة للخيارات الصالحة. example: BRA services: type: array items: type: string description: >- معرّفات `service_id` من الدليل لتشغيلها لهذه الدولة (مثل `["bra_cpf"]`). يقبل أيضاً سلسلة نصية مفردة أو سلسلة مفصولة بفواصل/مرمزة بتنسيق JSON. **إذا تم حذفه أو تُرك فارغاً، فسيتم تشغيل خدمة افتراضية واحدة فقط** — وهي الخدمة العاملة الأقدم للدولة؛ أما الخدمات الأحدث والبيومترية وخدمات الدفع حسب الاستخدام فيجب تحديدها صراحةً. إرسال `services` يغيّر شكل الاستجابة إلى الشكل الموسع (يضيف `services_used` و`match_score`). يجب أن يكون كل معرّف موجوداً ونشطاً في `issuing_state`؛ والخدمات التي تتطلب التسجيل تُرجع الرمز `400` حتى يتم تفعيلها لمؤسستك. يمكنك استكشاف الخدمات المتاحة لكل دولة عبر `GET /v1/organization/database-validation-countries/` (وهو endpoint للدليل غير موثق في هذه المواصفة) أو عبر محرر سير العمل في Business Console. example: - bra_cpf validation_type: type: string deprecated: true description: >- مهمل. يُقبل للتوافق مع الإصدارات السابقة ولكن يتم تجاهله — يُشتق `validation_type` في الاستجابة الآن من عدد الخدمات التي تطابقت بالكامل. استخدم `services` لتحديد خدمات معينة. consent: type: boolean default: false description: >- يُضبط على `true` عندما يوافق المستخدم النهائي صراحةً على خدمات التحقق المحددة. مطلوب للخدمات التي تحمل العلامة `requires_consent=true` في الدليل — وبدونه تُرجع هذه الخدمات رمز `400` مع `services_requiring_consent`. identification_number: type: string description: >- رقم التعريف الشامل — يتم تعيينه تلقائيًا إلى الحقل المخصص للدولة الصحيحة، لذا يمكنك استخدامه بدلاً من `personal_number`/`tax_number`/`document_number`: ARG→document_number (DNI)، BOL→document_number (CI)، BRA→tax_number (CPF، 11 رقماً)، CHL→personal_number (RUT)، COL→personal_number (Cédula)، CRI→personal_number (Cédula)، DOM→personal_number (Cédula، 11 رقماً)، ECU→personal_number (Cédula، 10 أرقام)، ESP→personal_number (DNI/NIE)، GTM→document_number (DPI)، HND→document_number (DNI)، MEX→personal_number (CURP، 18 حرفاً)، PAN→personal_number (Cédula)، PER→personal_number (DNI، 8 أرقام)، PRY→document_number (CI)، SLV→document_number (DUI)، URY→personal_number (CI)، VEN→document_number (Cédula). لا يتجاوز أبدًا أي حقل مخصص للدولة تم تقديمه صراحةً. first_name: type: string description: الاسم الأول للفرد. مطلوب في بعض الخدمات/الدول. example: John last_name: type: string description: اسم العائلة للفرد. مطلوب في بعض الخدمات/الدول. example: Doe middle_name: type: string description: >- الاسم الأوسط، يُستخدم بواسطة خدمات بعض الدول (أستراليا، نيوزيلندا، ...). full_name: type: string description: >- الاسم الكامل — تقبل بعض الخدمات هذا بدلاً من الاسم الأول/اسم العائلة (مثل خدمات CHN، التي تطابق الاسم بنظام الكتابة الأصلي). date_of_birth: type: string format: date description: تاريخ الميلاد، `YYYY-MM-DD`. مطلوب من قبل العديد من الخدمات. example: '1980-01-01' personal_number: type: string description: >- معرّف شخصي فريد صادر عن الحكومة. يُستخدم في: CHL (RUT)، COL (Cédula)، CRI، DOM، ECU، ESP (DNI/NIE)، MEX (CURP)، PAN (Cédula)، PER (DNI)، URY. يُفضَّل استخدام `identification_number` بدلاً منه. tax_number: type: string description: >- الرقم الضريبي. يُستخدم من قبل: BRA (CPF، مكون من 11 رقماً). فكّر في استخدام `identification_number` بدلاً منه. document_number: type: string description: >- رقم المستند. يُستخدم بواسطة: ARG (DNI)، وBOL (CI)، وGTM (DPI)، وHND (DNI)، وPRY (CI)، وSLV (DUI)، وVEN (Cédula). فكّر في استخدام `identification_number` بدلاً من ذلك. document_type: type: string enum: - P - DL - ID - RP - SSC - HIC - WP - TC - VISA - PSC - BC - OTHER description: >- نوع المستند الذي يتم التحقق منه: `P` جواز سفر، `DL` رخصة قيادة، `ID` بطاقة هوية وطنية، `RP` تصريح إقامة (بالإضافة إلى `SSC`، `HIC`، `WP`، `TC`، `VISA`، `PSC`، `BC`، `OTHER`). مطلوب لبعض الخدمات (مثل ESP). expiration_date: type: string format: date description: >- تاريخ انتهاء المستند، `YYYY-MM-DD`. مطلوب للتحقق في إسبانيا (ESP). example: '2030-01-15' date_of_issue: type: string format: date description: >- تاريخ إصدار المستند، `YYYY-MM-DD` (fecha de expedición). مطلوب للتحقق من cédula في كولومبيا (COL). example: '2015-06-20' nationality: type: string description: >- الجنسية وفق معيار ISO 3166-1 alpha-3. مطلوبة من قِبل بعض الخدمات. gender: type: string enum: - M - F - X description: >- الجنس: `M`، أو `F`، أو `X` (آخر/غير معروف). مطلوب للتحقق من RENAPER في الأرجنتين (`arg_renaper`). address: description: >- عنوان السكن. يُفضّل الكائن المهيكل `{"street_1":"123 Main St","street_2":"Apt 4B","city":"Springfield","region":"IL","postal_code":"62701","country":"US"}`؛ لا تزال السلسلة النصية الكاملة في سطر واحد مقبولة. مطلوب لخدمات التحقق من العنوان؛ وعندما تحدد الخدمة متطلبات العنوان، فإن الأجزاء المفقودة تُرجع `400` مع `address_fields_required_by`. oneOf: - type: object properties: street_1: type: string street_2: type: string city: type: string region: type: string postal_code: type: string country: type: string - type: string description: العنوان الكامل في سطر واحد (قديم). address_element_1: type: string description: >- عنوان الشارع بما في ذلك رقم الشارع ونوعه. إذا تم حذفه، فسيتم استنتاجه من `address`. address_element_2: type: string description: >- شقة، وحدة، مبنى، طابق، أو سطر عنوان إضافي. أرسله فقط عندما يتوفر لديك بشكل صريح. address_element_3: type: string description: >- المدينة، أو الضاحية، أو الحي، أو المنطقة، أو المجاورة. إذا تم حذفه، فسيتم استنتاجه من `address`. address_element_4: type: string description: >- الولاية أو المقاطعة أو المنطقة أو البلدة. إذا تم حذفه، يُستنتج من `address`. address_element_5: type: string description: الرمز البريدي. يُقبل `postal_code` كاسم بديل. postal_code: type: string description: >- الرمز البريدي للخدمات المعتمدة على العنوان (اسم بديل لـ `address_element_5`). driver_license_number: type: string description: >- رقم رخصة القيادة لخدمات التحقق من المستندات الحكومية (AUS، NZL، IND). driver_license_card_number: type: string description: >- رقم بطاقة رخصة القيادة الفعلية، حيث يُطلب بشكل منفصل عن رقم الرخصة (أستراليا). driver_license_state: type: string description: ولاية أو إقليم إصدار رخصة القيادة (AUS). driver_license_version: type: string description: رمز إصدار رخصة القيادة (NZL). passport_number: type: string description: >- رقم جواز السفر لخدمات التحقق الحكومية من جوازات السفر (AUS وNZL وIND وCHN). passport_expiration_date: type: string format: date description: >- تاريخ انتهاء جواز السفر، بصيغة `YYYY-MM-DD`، لخدمات التحقق من جوازات السفر. passport_file_number: type: string description: رقم ملف جواز السفر (IND). passport_issue_country: type: string description: >- دولة إصدار جواز السفر (ISO 3166-1 alpha-3) لخدمات التحقق من جوازات السفر. medicare_card_number: type: string description: رقم بطاقة Medicare (أستراليا). immi_card_number: type: string description: رقم بطاقة ImmiCard الأسترالية. immi_card_expiry_date: type: string format: date description: تاريخ انتهاء بطاقة ImmiCard الأسترالية. citizenship_certificate_number: type: string description: رقم شهادة المواطنة (أستراليا). birth_registration_number: type: string description: رقم تسجيل شهادة الميلاد (أستراليا). birth_registration_date: type: string format: date description: تاريخ تسجيل شهادة الميلاد (أستراليا). birth_registration_state: type: string description: ولاية تسجيل شهادة الميلاد (أستراليا). marriage_certificate_number: type: string description: رقم شهادة الزواج (أستراليا). change_of_name_certificate_number: type: string description: رقم شهادة تغيير الاسم (AUS). first_partner_name: type: string description: الاسم الأول للشريك في عقد الزواج (أستراليا). last_partner_name: type: string description: اسم العائلة للشريك في وثيقة الزواج (AUS). voter_id: type: string description: رقم تسجيل الناخب (IND EPIC، IRL). epic_card: type: string description: رقم بطاقة الناخب EPIC للهند. pan: type: string description: 'الهند: رقم الحساب الدائم (PAN).' national_id: type: string description: رقم الهوية الوطنية (CHN، وMYS، وKEN، وKHM، وNGA، وZAF، و…). cic: type: string description: >- رمز تعريف بطاقة الهوية (CIC) التابع لـ INE/IFE المكسيكي، 9 أرقام. يُستخدم بواسطة خدمة صلاحية بيانات اعتماد MEX INE (`mex_ine_vigencia`). identificador_ciudadano: type: string description: >- مُعرّف المواطن (Identificador del Ciudadano) للمعهد الانتخابي الوطني المكسيكي INE (9 أرقام). يُستخدم مع `cic` لنماذج INE الحديثة (E/F/G/H) في `mex_ine_vigencia`. ocr: type: string description: >- رقم OCR للمعهد الانتخابي الوطني المكسيكي INE (13 رقمًا، ظهر البطاقة). يُستخدم مع `cic` للنموذج D في `mex_ine_vigencia`. voter_number: type: string description: >- مفتاح الناخب (Clave de Elector) للمعهد الانتخابي الوطني المكسيكي INE (18 حرفًا). يُستخدم مع `emission_number` لنماذج IFE القديمة (A/B/C) في `mex_ine_vigencia`. emission_number: type: string description: >- رقم الإصدار (Número de Emisión) للمعهد الانتخابي الوطني المكسيكي INE. يُستخدم مع `voter_number` لنماذج IFE القديمة (A/B/C) في `mex_ine_vigencia`. bvn: type: string description: رقم التحقق المصرفي النيجيري. bank_card_number: type: string description: رقم البطاقة البنكية (التحقق من البطاقة البنكية في CHN). company_registration_number: type: string description: >- رقم تسجيل الشركة الصادر عن سجل الشركات: مثل CNPJ في البرازيل (على سبيل المثال `11222333000181`)، ورقم التسجيل في جنوب إفريقيا (على سبيل المثال `1936/007721/06`). مطلوب لخدمات سجل الشركات ومديري الشركات (`bra_company_registry`، `bra_company_directors`، `zaf_company_registry`، `zaf_company_directors`). company_name: type: string description: >- اسم الشركة المسجل، بعد مطابقته مع قيد السجل. اختياري لـ `zaf_company_registry`. initials: type: string description: >- الأحرف الأولى من اسم الشخص كما هي مطبوعة على المستند. مطلوبة لـ `zaf_drivers_license`؛ ومقبولة لـ `zaf_bank_account_holder`. licence_number: type: string description: >- رقم رخصة القيادة كما هو مطبوع على البطاقة، لـ `zaf_drivers_license`. عند حذفه، يُستخدم `document_number`. refugee_file_number: type: string description: >- رقم ملف اللاجئ الصادر عن وزارة الشؤون الداخلية في جنوب أفريقيا. مطلوب لـ `zaf_refugee`. bank_name: type: string description: >- اسم البنك الذي يحتفظ بالحساب. يتطلبه `zaf_bank_account_holder`. bank_account_number: type: string description: >- رقم الحساب البنكي. مطلوب بواسطة `zaf_bank_account_holder`؛ ومقبول بواسطة `zaf_fraud_prevention`. account_type: type: string description: >- نوع الحساب البنكي لـ `zaf_bank_account_holder`: `current`، أو `savings`، أو `transmission`، أو `subscriptionShare`، أو `notKnown`، دون حساسية لحالة الأحرف. تُرجع أي قيمة أخرى `400`. احذفه عندما لا تعرف النوع: سيتم بعد ذلك الإبلاغ عن التحقق المتبادل من نوع الحساب بأنه غير مؤكد. phone_number: type: string description: >- رقم الهاتف المحمول للتواصل، للخدمات التي تتحقق من إمكانية التواصل (`zaf_bank_account_holder`، `zaf_fraud_prevention`، `zaf_refugee`). right_thumb: type: string description: >- بصمة الإبهام الأيمن بترميز Base64 لـ `zaf_dha_fingerprint_match`، مع `left_thumb` أو بمفردها. left_thumb: type: string description: >- بصمة الإبهام الأيسر بترميز Base64 لـ `zaf_dha_fingerprint_match`، مع `right_thumb` أو بمفردها. score_level: type: integer description: >- الحد الأدنى لمستوى الدرجة البيومترية لـ `zaf_criminal_face_screening`. القيمة الافتراضية هي `3`. max_matches: type: integer description: >- الحد الأقصى لعدد التطابقات المرشحة التي يرجعها `zaf_criminal_face_screening`. القيمة الافتراضية هي `1`. vehicle_register_number: type: string description: >- رقم تسجيل المركبة. مطلوب، مع `vehicle_licence_plate` و`vin`، بواسطة `zaf_vehicle_ownership`. vehicle_licence_plate: type: string description: >- رقم لوحة ترخيص المركبة. مطلوب، مع `vehicle_register_number` و`vin`، بواسطة `zaf_vehicle_ownership`. vin: type: string description: >- رقم تعريف المركبة (VIN أو رقم الشاسيه). مطلوب، مع `vehicle_register_number` و`vehicle_licence_plate`، بواسطة `zaf_vehicle_ownership`. ssn: type: string description: رقم الضمان الاجتماعي (الولايات المتحدة الأمريكية). phone: type: string description: رقم الهاتف لخدمات التحقق من رقم الهاتف. landline: type: string description: رقم الهاتف الأرضي لخدمات التحقق من رقم الهاتف. email: type: string format: email description: عنوان البريد الإلكتروني لخدمات التحقق من الهوية. country_of_residence: type: string description: >- دولة الإقامة وفق المعيار ISO 3166-1 alpha-2. تُستخدم بواسطة خدمات إثراء الهوية العالمية (مثل `glb_identity_enrichment`) لتركيز البحث. example: US partial_match_action: type: string enum: - DECLINE - NO_ACTION default: NO_ACTION description: >- ما يفعله `partial_match` بحالة `database_validation.status`. القيمة الافتراضية هي `NO_ACTION` (تبقى الحالة `Approved`، مع تحذير). no_match_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- ما يفعله `no_match` بحالة `database_validation.status`. القيمة الافتراضية هي `DECLINE`. save_api_request: type: boolean default: true description: >- حفظ التحقق كجلسة (الظهور في لوحة التحكم، endpoint القرار، webhook الخاص بـ `status.updated`). يُغيّر أيضاً شكل استجابة `validations`: كائنات لكل خدمة عندما تكون القيمة `true` (افتراضياً)، وخريطة حقول مدمجة عندما تكون `false`. vendor_data: type: string description: >- المعرّف الخاص بك للمستخدم الذي تم التحقق منه؛ تتم إعادته وتخزينه مع الجلسة. metadata: type: object nullable: true description: كائن JSON بصيغة حرة يُخزن مع الطلب وتتم إعادته في الاستجابة. selfie: type: string format: binary description: >- صورة سيلفي (`jpg` و`jpeg` و`png` و`webp`؛ بحد أقصى 2 MB — يتم ضغط الصور إلى ~1.5 MB قبل الرفع إلى السجل) لخدمات التحقق البيومتري، مثل RENAPER في الأرجنتين (`arg_renaper`) وSIB في بنما (`pan_cedula_sib` و`pan_cedula_sib_plus`). مطلوبة عندما تُدرجها الخدمة المحددة كحقل مطلوب. متاحة فقط عبر `multipart/form-data`. responses: '200': description: >- اكتمل التحقق — أرجعت خدمة واحدة محددة على الأقل نتيجة قابلة للاستخدام. افحص `database_validation.match_type` لمعرفة النتيجة الإجمالية، و`validations` لمقارنات الحقول و`outcome_code`s لكل خدمة، و`errors` (عند وجودها) للخدمات التي تعذر تشغيلها. content: application/json: schema: type: object properties: request_id: type: string format: uuid description: >- معرّف الجلسة المحفوظة عندما تكون `save_api_request=true` (يمكن استخدامه مع `GET /v3/session/{sessionId}/decision/`)؛ وإلا فسيكون UUID ارتباط مؤقت. database_validation: type: object properties: status: type: string enum: - Approved - Declined - In Review description: >- `Declined` عندما يُشغّل `match_type` الإجمالي إجراء `DECLINE` (القيمة الافتراضية لـ `no_match_action` هي `DECLINE`، ولـ `partial_match_action` هي `NO_ACTION`)؛ و`In Review` عندما لا تُنتج أي خدمة مقارنة قابلة للاستخدام، على سبيل المثال عندما تعود الخدمة الوحيدة المحددة بـ `REGISTRY_UNAVAILABLE` أو `INCONCLUSIVE`؛ و`Approved` خلاف ذلك. يمكن أن يكون الطلب الذي حدد خدمات متعددة `Approved` بناءً على تطابق خدمة واحدة بينما كانت خدمة أخرى غير متاحة، لذا تحقق من `errors` و`outcome_code` الخاصة بكل خدمة أيضاً. issuing_state: type: string description: >- نسخة مطابقة لدولة ISO 3166-1 alpha-3 التي تم التحقق مقابلها. example: BRA validation_type: type: string enum: - one_by_one - two_by_two description: >- مستمدة من النتائج: `two_by_two` عندما تُسفر خدمتان متميزتان أو أكثر عن تطابق كامل (على رقم التعريف، أو على الاسم الكامل + تاريخ الميلاد معاً، أو على العنوان دون أي تعارضات)؛ و`one_by_one` في الحالات الأخرى. (حقل الطلب الذي يحمل الاسم نفسه قديم ولم يعد مستخدماً ويتم تجاهله). screened_data: type: object description: >- تكرار لحقول الإدخال التي تم إرسالها إلى الخدمات المحددة (تتم تسوية التواريخ إلى `YYYY-MM-DD`؛ وعند إرسال `selfie`، يتم إرجاعها كرابط URL موقّع مسبقاً؛ وتتم إضافة `consent_obtained: true` عند تقديم الموافقة). match_type: type: string nullable: true enum: - full_match - partial_match - no_match description: >- النتيجة الإجمالية المجمعة عبر الخدمات مع مقارنات على مستوى الحقول: أي `full_match` ← `full_match`؛ وإلا أي `partial_match` ← `partial_match`؛ وإلا `no_match`. يمكن للخدمات التي تعتمد على النتيجة فقط، مثل الفحص الجنائي البيومتري، إرجاع `null`؛ افحص كل عنصر في `validations` لمعرفة `outcome_code` الخاص به. validations: description: >- يعتمد الشكل على `save_api_request`. **`true` (افتراضي):** مصفوفة من الكائنات الخاصة بكل خدمة (`service_id`، و`service_name`، و`validation`، و`outcome_code`، و`outcome_detail`، و`source_data`). **`false`:** كائن أحادي مسطح يدمج نتائج جميع الخدمات على مستوى الحقول (`{"full_name": "full_match", ...}`). oneOf: - type: array items: type: object description: >- نتيجة التحقق لكل خدمة (تُرجع عندما يكون `save_api_request=true`، وهو الإعداد الافتراضي). properties: service_id: type: string description: >- معرّف الدليل للخدمة التي أنتجت هذه النتيجة (مثل `bra_cpf`). example: bra_cpf service_name: type: string description: اسم الكتالوج السهل القراءة للخدمة. example: Brazil - CPF status check validation: type: object description: >- مقارنة حقل بحقل بين مدخلاتك والسجل الرسمي. المفاتيح هي أسماء الحقول القياسية (`full_name`، `date_of_birth`، `identification_number`، `address`، …)؛ والقيم هي `full_match`، أو `partial_match`، أو `no_match`. additionalProperties: type: string enum: - full_match - partial_match - no_match outcome_code: type: string enum: - MATCH - PARTIAL_MATCH - NO_MATCH - DOCUMENT_NOT_FOUND - INVALID_DOCUMENT_FORMAT - INVALID_INPUT - MINOR_BLOCKED - DECEASED - BIOMETRIC_NO_MATCH - BIOMETRIC_IMAGE_UNUSABLE - INCONCLUSIVE - DOCUMENT_SUPERSEDED - REGISTRY_UNAVAILABLE - REGISTRY_ERROR description: >- النتيجة المحايدة للمزود لعملية البحث في السجل. تصف `MATCH`/`PARTIAL_MATCH`/`NO_MATCH` المقارنة؛ وتعني `DOCUMENT_NOT_FOUND` أن المعرّف غير موجود في السجل؛ وتعني `INCONCLUSIVE` أن السجل لم يتمكن من التأكيد بأي من الاتجاهين (تم توجيهها للمراجعة — وليست عدم تطابق)؛ و`BIOMETRIC_NO_MATCH` هي عدم تطابق مؤكد للوجه بينما `BIOMETRIC_IMAGE_UNUSABLE` هي مشكلة تقنية في الصورة (أعد التقاط صورة سيلفي)؛ و`DECEASED`/`MINOR_BLOCKED` هي نتائج لسياسات السجل؛ وتعني `DOCUMENT_SUPERSEDED` أن الهوية متطابقة ولكن إصدار المستند المقدم ليس هو المحفوظ في الملف (تم إصدار نسخة أحدث)؛ وتعني `INVALID_DOCUMENT_FORMAT`/`INVALID_INPUT` أن السجل نفسه رفض البيانات المرسلة إليه؛ وتشير `REGISTRY_UNAVAILABLE`/`REGISTRY_ERROR` إلى إخفاقات في المصدر الأساسي. outcome_detail: type: string nullable: true description: >- تفاصيل الحالة الخام من المصدر التي تدعم رمز النتيجة (مثل رمز حالة HTTP أو رمز حالة السجل). source_data: type: object nullable: true description: >- عرض مُنقّى ومُطبّع لسجل الشركة باستخدام أسماء الحقول القياسية (`identification_number`، و`first_name`، و`last_name`، و`date_of_birth`، بالإضافة إلى العلامات الخاصة بالسجل). يتم إرجاع حقول الصور، عند وجودها، كروابط URL موقّعة مسبقاً. - type: object additionalProperties: type: string enum: - full_match - partial_match - no_match description: >- نتائج مدمجة على مستوى الحقل (بصيغة عديمة الحالة `save_api_request=false`). warnings: type: array items: type: object properties: feature: type: string description: الميزة التي أصدرت التحذير. risk: type: string description: معرّف مخاطر مقروء آلياً. additional_data: type: object nullable: true description: سياق إضافي للتحذير، عند توفره. log_type: type: string description: >- `warning` أو `information` أو `error` — كيف أثر الخطر على النتيجة. short_description: type: string description: ملخص مقروء للبشر في سطر واحد. long_description: type: string description: تفسير كامل مفهوم للبشر. description: >- `DATABASE_VALIDATION_NO_MATCH` أو `DATABASE_VALIDATION_PARTIAL_MATCH` عند الانطباق؛ وفارغ في حالة التطابق التام. errors: type: array description: >- موجود فقط عند فشل بعض الخدمات المحددة (وليس كلها). يحمل كل إدخال `service_id` و `code` و `message` و `retryable`. الخدمة المُبلغ عنها هنا تكون غائبة عن `validations` و `services_used`، ولا تتم فوترتها. هذه المصفوفة هي المكان الوحيد الذي تظهر فيه، لذا تحقق منها حتى عندما تكون `status` هي `Approved`. items: type: object properties: service_id: type: string code: type: string example: empty_provider_response message: type: string retryable: type: boolean description: >- تكون `true` عندما لا تصدر الخدمة أي إجابة ويمكن أن تنجح إعادة المحاولة لاحقاً؛ وتكون `false` عندما يرفض المصدر البيانات المرسلة إليه ويجب تصحيح الإدخال أولاً. example: true services_used: type: array items: type: string description: >- معرّفات الدليل للخدمات التي أرجعت نتيجة خاضعة للفوترة. **موجودة فقط عندما يُرسل الطلب `services` بشكل صريح.** match_score: type: number description: >- نسبة (0.0–1.0) من الخدمات التي جرت محاولتها وأسفرت عن تطابق كامل (في رقم الهوية، أو في الاسم الكامل + تاريخ الميلاد معاً، أو في العنوان دون أي تناقضات). **تكون موجودة فقط عندما يرسل الطلب `services` صراحة.** vendor_data: type: string nullable: true description: تكرار لقيمة `vendor_data` التي أرسلتها. metadata: type: object nullable: true description: نسخة مطابقة من `metadata` التي أرسلتها. created_at: type: string format: date-time examples: Full match (Approved): summary: >- الافتراضي save_api_request=true — كائنات `validations` لكل خدمة value: request_id: 7f9a1c0e-1f2b-4f6e-9d3a-2b1c0e7f9a1c database_validation: status: Approved issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: full_match validations: - validation: full_name: full_match date_of_birth: full_match identification_number: full_match outcome_code: MATCH outcome_detail: '200' service_id: bra_cpf service_name: Brazil - CPF status check source_data: identification_number: '12345678900' first_name: JOHN last_name: DOE date_of_birth: '1980-01-01' lgpd_minor: false minor_under_16: false minor_under_18: false warnings: [] vendor_data: user-1234 metadata: null created_at: '2026-06-11T10:30:00.000000+00:00' Explicit services (extended shape): summary: >- الطلب أرسل `services` — تضيف الاستجابة `services_used` و`match_score` value: request_id: b3e7c1a2-9d4f-4f0b-8a6c-5e2d1f0a9b3e database_validation: status: Approved issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: full_match validations: - validation: full_name: full_match date_of_birth: full_match identification_number: full_match outcome_code: MATCH outcome_detail: '200' service_id: bra_cpf service_name: Brazil - CPF status check source_data: identification_number: '12345678900' first_name: JOHN last_name: DOE date_of_birth: '1980-01-01' lgpd_minor: false minor_under_16: false minor_under_18: false warnings: [] services_used: - bra_cpf match_score: 1 vendor_data: user-1234 metadata: null created_at: '2026-06-11T10:30:00.000000+00:00' No match (Declined): summary: >- بيانات السجل التجاري لا تتطابق — القيمة الافتراضية `no_match_action=DECLINE` value: request_id: 0a1b2c3d-4e5f-6789-abcd-ef0123456789 database_validation: status: Declined issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: no_match validations: - validation: full_name: no_match date_of_birth: no_match identification_number: no_match outcome_code: NO_MATCH outcome_detail: '200' service_id: bra_cpf service_name: Brazil - CPF status check source_data: identification_number: '00987654321' first_name: TOTALLY last_name: DIFFERENT NAME date_of_birth: '1999-01-01' lgpd_minor: false minor_under_16: false minor_under_18: false warnings: - feature: DATABASE_VALIDATION risk: DATABASE_VALIDATION_NO_MATCH additional_data: null log_type: error short_description: Database validation no match long_description: >- The system identified a no match in the database validation, requiring further investigation. vendor_data: null metadata: null created_at: '2026-06-11T10:31:00.000000+00:00' Stateless (save_api_request=false): summary: تندمج `validations` في خريطة حقول مدمجة؛ لا يتم تخزين أي شيء value: request_id: c4d5e6f7-8901-2345-6789-abcdef012345 database_validation: status: Approved issuing_state: BRA validation_type: one_by_one screened_data: tax_number: '12345678900' first_name: John last_name: Doe date_of_birth: '1980-01-01' match_type: full_match validations: full_name: full_match date_of_birth: full_match identification_number: full_match warnings: [] vendor_data: null metadata: null created_at: '2026-06-11T10:32:00.000000+00:00' '400': description: >- خطأ في التحقق من الصحة - لا تتم فوترة أي شيء. تحدث أخطاء حقول الفحص الأولي قبل أي استدعاء خارجي. إذا رفضت كل محاولة لم تتم الإجابة عنها المدخلات صراحةً، فإن الاستجابة تتضمن بدلاً من ذلك `validation_errors` مع `code: provider_rejected_input` و`retryable: false`؛ قم بتصحيح المدخلات قبل إعادة المحاولة. تستخدم المشاكل على مستوى الحقول غلاف DRF القياسي؛ وتعيد مشاكل الكتالوج مصفوفة `services` (بالإضافة إلى `requires_onboarding` أو `services_requiring_consent` عند الاقتضاء)؛ وتتضمن أخطاء الحقول المفقودة `fields_required_by` لربط كل حقل مفقود بالخدمات التي تتطلبه؛ أما الخدمات التي تحتاج إلى معرّف إضافي واحد على الأقل (مثل `usa_states_credit_bureau`، والتي لا يمكنها التحقق من الاسم بمفرده) فتعيد `any_field_required_by` لربط كل خدمة بالحقول التي يجب توفر واحد منها على الأقل؛ وتعيد مشاكل التنسيق التي يتم فحصها لكل خدمة `invalid_fields_by_service`. content: application/json: examples: Invalid issuing_state: summary: الدولة غير مدعومة — تسرد الرسالة كل رمز alpha-3 صالح value: error: - >- Invalid issuing state. Valid options are: ARE, ARG, AUS, AUT, BEL, BGD, BOL, BRA, CAN, CHE, CHL, CHN, CIV, COL, CRI, CZE, DEU, DNK, DOM, ECU, ESP, FIN, FRA, GBR, GHA, GLB, GRC, GTM, HKG, HND, IDN, IND, IRL, ITA, KEN, KHM, MAR, MEX, MYS, NGA, NLD, NOR, NZL, OMN, PAN, PER, PHL, POL, PRT, PRY, QAT, SGP, SLV, SVK, SWE, THA, UGA, URY, USA, VEN, ZAF, ZMB, ZWE Missing required fields: summary: >- اتحاد الحقول المطلوبة عبر الخدمات المحددة، مع تلميح الحقل الشامل value: error: - >- Missing required fields: tax_number (or use 'identification_number' which maps to 'tax_number' for BRA) fields_required_by: tax_number: - bra_cpf Unknown service id: summary: '`services` يحتوي على معرّف غير موجود في الدليل' value: services: - 'Unknown service_id(s): [''bogus_service'']' Service not live for country: summary: '`services` يحدد خدمة من دولة أخرى (أو إدخالاً وهمياً)' value: services: - >- Services not currently live for PER: ['bra_cpf']. Available services: ['per_dni', 'per_residential', 'per_tax_registration'] Service requires onboarding: summary: الخدمة موجودة ولكن لم يتم تفعيلها لمؤسستك بعد value: services: - >- Services require onboarding before they can be enabled for AUS: ['aus_australia_driver_licence']. Contact Didit support to activate them. requires_onboarding: - aus_australia_driver_licence Consent missing: summary: >- خدمة محددة تم تمييزها بـ requires_consent=true ولم تكن `consent` بقيمة `true` value: consent: - >- Explicit end-user consent is required for these database validation services: ['chn_national_id']. Send `consent=true`. services_requiring_consent: - chn_national_id Country format rule violation: summary: >- المعرّف لا يستوفي قاعدة تنسيق الدولة (الطول/الأرقام/التعبير النمطي) value: tax_number: - >- Invalid tax number for BRA: Brazilian CPF (exactly 11 digits). Must be exactly 11 characters long (got 10). Service-specific format violation: summary: فشل حقل في تلبية متطلبات التنسيق الخاصة بالخدمة المحددة value: error: - >- One or more fields do not match the format required by the selected service. invalid_fields_by_service: chn_national_id: - national_id_format Input refused by every attempt: summary: صحح المدخلات قبل إعادة المحاولة value: error: >- The source refused to run this query with the supplied input. validation_errors: - service_id: bra_cpf code: provider_rejected_input message: >- The source refused to run this query with the supplied input. retryable: false schema: type: object additionalProperties: true properties: error: description: توضيح على مستوى الطلب أو أخطاء الفحص الأولي للحقول. oneOf: - type: string - type: array items: type: string validation_errors: type: array description: >- موجود عندما ترفض كل محاولة لم تتم الإجابة عنها البيانات المُدخلة بعد الفحص المسبق. items: type: object properties: service_id: type: string code: type: string message: type: string retryable: type: boolean description: >- ما إذا كانت إعادة المحاولة لاحقاً يمكن أن تحل فشل الخدمة هذا. تعني القيمة False تصحيح المدخلات المقدمة أولاً. '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 '502': description: >- لم تُرجع أي خدمة محددة نتيجة صالحة للاستخدام. افحص كل إدخال في validation_errors قبل إعادة المحاولة؛ رمز HTTP 502 وحده لا يثبت وجود فشل مؤقت. يشير empty_provider_response مع retryable: true إلى نتائج غير متاحة أو غير مفسرة، بما في ذلك رفض المزوّد الأساسي متبوعاً بمزوّد بديل غير متاح. في المقابل، تتطلب إدخالات provider_invalid_input وprovider_validation_error القديمة إدخالاً مصححاً وقد تحذف retryable. لا تتم فوترة أي شيء. عندما تكون save_api_request=true، تُسجّل المحاولة الفاشلة كجلسة بالحالة «غير مكتملة». ترجع حالات الفشل الجزئي الرمز 200 مع database_validation.errors. content: application/json: schema: type: object properties: error: type: string validation_errors: type: array items: type: object properties: service_id: type: string code: type: string message: type: string retryable: type: boolean description: >- ما إذا كانت إعادة المحاولة لاحقاً يمكن أن تحل فشل الخدمة هذا. تعني القيمة False تصحيح المدخلات المقدمة أولاً. examples: Provider returned no result: summary: فشلت كل خدمة محددة value: error: >- Database validation could not be performed. The external validation service did not return a result. Please try again later. validation_errors: - service_id: bra_cpf code: empty_provider_response message: >- The provider did not return a database validation result. retryable: true security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/database-validation/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "issuing_state": "BRA", "services": ["bra_cpf"], "identification_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01", "vendor_data": "user-1234" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.database_validation.validate( issuing_state="BRA", services=["bra_cpf"], identification_number="12345678900", first_name="John", last_name="Doe", date_of_birth="1980-01-01", vendor_data="user-1234", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.databaseValidation.validate({ issuing_state: "BRA", services: ["bra_cpf"], identification_number: "12345678900", first_name: "John", last_name: "Doe", date_of_birth: "1980-01-01", vendor_data: "user-1234", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.DatabaseValidation.Validate(ctx, didit.DatabaseValidationValidateParams{\n\tIssuingState: \"BRA\",\n\tServices: didit.Some([]string{\"bra_cpf\"}),\n\tIdentificationNumber: didit.String(\"12345678900\"),\n\tFirstName: didit.String(\"John\"),\n\tLastName: didit.String(\"Doe\"),\n\tDateOfBirth: didit.String(\"1980-01-01\"),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.time.LocalDate; import java.util.List; import me.didit.Didit; import me.didit.types.DatabaseValidationValidateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.databaseValidation().validate(DatabaseValidationValidateParams.builder() .issuingState("BRA") .services(List.of("bra_cpf")) .identificationNumber("12345678900") .firstName("John") .lastName("Doe") .dateOfBirth(LocalDate.parse("1980-01-01")) .vendorData("user-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- databaseValidation->validate([ 'issuing_state' => 'BRA', 'services' => ['bra_cpf'], 'identification_number' => '12345678900', 'first_name' => 'John', 'last_name' => 'Doe', 'date_of_birth' => '1980-01-01', 'vendor_data' => 'user-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.database_validation.validate( issuing_state: "BRA", services: ["bra_cpf"], identification_number: "12345678900", first_name: "John", last_name: "Doe", date_of_birth: "1980-01-01", vendor_data: "user-1234" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.DatabaseValidation.ValidateAsync(new DatabaseValidationValidateParams { IssuingState = "BRA", Services = new string[] { "bra_cpf" }, IdentificationNumber = "12345678900", FirstName = "John", LastName = "Doe", DateOfBirth = "1980-01-01", VendorData = "user-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: 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.