> ## 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. # واجهة Document AI: استخراج بيانات المستندات المخصصة > استخرج Didit الحقول التي تحددها من أي PDF أو صورة عبر POST /v3/document-ai/ من خادم إلى خادم، مع مطابقة الأسماء وفحوصات التلاعب. $0.20 لكل مستند. أرسل مستنداً واحداً وقائمة الحقول التي تريد قراءتها منه. يشغّل Didit نموذج الاستخراج الافتراضي على الملف، ويعيد كل حقل مع نوعه (`text` أو `number` أو `date` بصيغة `YYYY-MM-DD`)، ويكتشف رموز QR والباركود المدعومة ويفك ترميزها، ويفحص الملف بحثاً عن التلاعب، ويقارن اختيارياً الاسم الوارد في المستند بالشخص أو الشركة التي تتوقعها. استخدمه لإثبات الأموال، وكشوف الرواتب، وكشوف الحسابات البنكية، والمستندات الضريبية، والفواتير، أو أي مستند لا يتطابق مع قالب ثابت. هذه هي النسخة من خادم إلى خادم لخطوة [Document AI المستضافة](https://docs.didit.me/ar/core-technology/document-ai/overview.md). الطلب من نوع `multipart/form-data`: يُرسل الملف في `document`، وتُرسل تعريفات الحقول في `fields` كسلسلة نصية واحدة تحتوي على مصفوفة JSON مُرمَّزة. ## تحديد الحقول المراد استخراجها `fields` مصفوفة JSON تضم من 1 إلى 30 عنصراً، وتُرسل كسلسلة واحدة. يحتوي كل عنصر على `key` (أحرف إنجليزية صغيرة وأرقام وشرطات سفلية، وفريدة داخل الطلب)، و`name` مقروء للإنسان، و`instruction` يخبر النموذج بما يبحث عنه، و`type` (`text` أو `number` أو `date`)، وعلمين هما `required` و`is_full_name`. ```json theme={null} [ { "key": "account_holder", "name": "Account holder", "instruction": "Full name of the person or company the account belongs to", "type": "text", "required": true, "is_full_name": true }, { "key": "balance", "name": "Closing balance", "instruction": "Closing balance shown on the statement, as a number without the currency symbol", "type": "number", "required": true }, { "key": "currency", "name": "Currency", "instruction": "Three-letter currency code of the balance", "type": "text" }, { "key": "statement_date", "name": "Statement date", "instruction": "Date the statement was issued", "type": "date", "required": true } ] ``` في طلب multipart تُرسل المصفوفة كلها كقيمة نموذج واحدة: ```bash theme={null} curl -X POST https://verification.didit.me/v3/document-ai/ \ -H "x-api-key: $DIDIT_API_KEY" \ -F "document=@./bank-statement.pdf" \ -F 'fields=[{"key":"account_holder","name":"Account holder","instruction":"Full name of the account holder","type":"text","required":true,"is_full_name":true},{"key":"balance","name":"Closing balance","instruction":"Closing balance as a number","type":"number","required":true}]' \ -F "expected_first_name=Jane" \ -F "expected_last_name=Doe" ``` تعيد الاستجابة `fields` بعد تطبيعها، و`extracted_data` مفهرسة بقيم `key` التي أرسلتها، مع `null` لأي حقل لم يتمكن النموذج من العثور عليه. الحقول `name` و`instruction` و`type` اختيارية في كل عنصر (ويكون `type` افتراضياً `text`)، أما `key` فمطلوب. إرسال `fields` كمفاتيح نموذج على شكل أقواس (`fields[0][key]=...`) أو كأي شيء غير مصفوفة JSON يعيد `400` قبل بدء أي استخراج، فلا يُحتسب أي مبلغ. ## رموز QR والباركود تتضمن كل استجابة ناجحة الحقل `document_ai.detected_codes`. يحتوي كل عنصر فيه على ما يلي: | الحقل | الوصف | | - | - | | `type` | نوع الترميز المكتشف، مثل `QR_CODE` أو `CODE_128` أو `EAN_13` أو `DATA_MATRIX` أو `PDF_417` | | `page_number` | رقم الصفحة مبتدئاً من 1 | | `position` | المضلع المكتشف بالبكسل ضمن الصفحة المُصيَّرة، أو `null` عندما لا يتوفر موقع موثوق | | `x` و`y` و`width` و`height` | المربع المحيط بالبكسل ضمن الصفحة المُصيَّرة، أو `null` عندما لا يتوفر موقع موثوق | | `page_width` و`page_height` | أبعاد الصفحة المُصيَّرة التي استُخدمت لحساب الإحداثيات | | `parsed_payload` | القيمة بعد فك ترميزها، سواء كانت سلسلة نصية أو قيمة مهيكلة، أو `null` عندما يمكن تحديد موقع الرمز فقط دون قراءته | | `raw_payload` | الحمولة الخام كما أعادها فك الترميز، بصيغة base64 عندما تتوفر، وإلا فهي سلسلة فارغة | تغطي المصفوفة كل صفحة معالجة من ملف PDF، وتكون فارغة عندما لا يُعثر على أي رمز مدعوم. لا يخمّن Didit أبداً محتوى الرمز: قد تُعاد رموز QR التالفة مع موقعها و`parsed_payload: null`، ولا يؤدي فشل اكتشاف الرموز إلى فشل طلب Document AI. ## مطابقة الأسماء ضع علامة `is_full_name: true` على حقل واحد كحد أقصى، وأرسل بيانات الشخص أو الشركة التي تتوقع أن يكون المستند عائداً إليها: | ما تتحقق منه | ما تُرسله | يُقارَن الاسم بـ | | - | - | - | | شخص | `expected_first_name` + `expected_last_name` | الاسم الكامل للشخص | | شركة | `expected_company_name` (+ `expected_company_country` اختيارياً، وهو رمز ISO من حرفين) | اسم الشركة | أرسل إحدى المجموعتين، لا كلتيهما. عندما يُستخرج اسم ويكون هناك اسم متوقع، تتضمن الاستجابة `name_match_score` (من 0 إلى 100) و`name_on_document`. إذا انخفضت الدرجة عن `document_ai_name_match_score_threshold` (الافتراضي `80`)، يُصدر تحذير `DOCUMENT_AI_NAME_MISMATCH` ويُطبَّق `document_ai_name_mismatch_action`. وإذا لم يُعلَّم أي حقل بـ`is_full_name`، يلجأ Didit إلى أول حقل نصي يشبه اسماً في مفتاحه (`name` أو `holder` أو `full_name` أو `account_holder`). علّم الحقل صراحةً عندما تريد التحكم في القيمة التي تُقارَن. وعندما لا يمكن العثور على قيمة اسم في المستند، أو لا يُرسَل أي اسم متوقع، يُتخطى فحص الاسم ويكون `name_match_score` مساوياً لـ`null`. ## المخاطر والإجراءات يرتبط كل خطر من المخاطر التالية بمعامل إجراء يمكنك ضبطه لكل طلب: `DECLINE` أو `REVIEW` أو `NO_ACTION`. الإجراء الأشد من بين الإجراءات الناتجة عن المخاطر المُشغَّلة هو الذي يحدد `document_ai.status` (`Declined` > `In Review` > `Approved`، أي مرفوضة > قيد المراجعة > مقبولة)، وتُدرج كل المخاطر التي تم تشغيلها في `document_ai.warnings`. تطابق القيم الافتراضية خطوة سير العمل المستضافة؛ راجع [قواعد Document AI والتحذيرات](https://docs.didit.me/ar/core-technology/document-ai/warnings-document-ai.md) لمعرفة كيفية اكتشاف كل خطر. | الخطر | المعامل | الافتراضي | | - | - | - | | `DOCUMENT_AI_UNREADABLE_DOCUMENT` | `document_ai_unreadable_document_action` | `REVIEW` | | `DOCUMENT_AI_MISSING_REQUIRED_FIELDS` | `document_ai_missing_required_fields_action` | `REVIEW` | | `DOCUMENT_AI_SUSPECTED_MANIPULATION` | `document_ai_document_tampering_action` | `DECLINE` | | `DOCUMENT_AI_NAME_MISMATCH` | `document_ai_name_mismatch_action` | `NO_ACTION` | | `DOCUMENT_AI_UNSUPPORTED_FILE` | `document_ai_unsupported_file_action` | `REVIEW` | ## الملفات والحفظ والفوترة * **الملفات المقبولة:** PDF (يدعم المستندات متعددة الصفحات)، وJPG وJPEG وPNG وTIFF وWebP، أو ملف ZIP يحتوي على المستند، بحجم يصل إلى 30 MB. ملفات PDF المشفّرة تعيد `400`؛ ارفع نسخة PDF غير مشفّرة أو صورة فوتوغرافية بدلاً منها. * **`save_api_request`** (الافتراضي `true`): يظهر الطلب والحقول المستخرجة والرموز المكتشفة في Business Console ضمن **الفحوصات اليدوية**، حيث يستطيع فريقك مراجعتها. اضبطه على `false` لتخطي الحفظ. * **`vendor_data`** و**`metadata`** تُعادان دون تغيير في الاستجابة، لتتمكن من ربط النتيجة بسجلاتك الخاصة. * **السعر:** \$0.20 لكل مستند، ويُحتسب عند معالجة المستند وإرجاع حالة. يُطبَّق خصم خطتك. راجع [الأسعار](https://docs.didit.me/ar/getting-started/pricing.md#أسعار-الواجهات-البرمجية-المستقلة-من-خادم-إلى-خادم). > [!NOTE] > > هل تحتاج إلى أن يرفع المستخدم المستند بنفسه، أو جمع ما يصل إلى 3 مستندات في تدفق واحد، أو الترجمة التلقائية لشاشة الرفع، أو مقارنة الحقول المستخرجة ببيانات الهوية أو الاستبيان؟ استخدم بدلاً من ذلك [خطوة سير عمل Document AI المستضافة](https://docs.didit.me/ar/core-technology/document-ai/overview.md). ## OpenAPI ````yaml ar/openapi-25.json POST /v3/document-ai/ 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/document-ai/: post: tags: - Standalone APIs summary: Document AI (استخراج الحقول المخصصة + عمليات التحقق من التلاعب) description: >- استخرج الحقول التي تحددها **أنت** من أي مستند داعم — قسائم الرواتب، وإثبات الأموال، وخطابات مصدر الثروة، والبيانات الضريبية، والعقود، والفواتير — في استدعاء واحد. أرسل الملف بالإضافة إلى تعريف `fields` (المفتاح، والاسم، وتعليمات الاستخراج، والنوع) واحصل على قيم ذات نوع محدد (`text`، أو `number`، أو `date` بتنسيق `YYYY-MM-DD`)، ودرجة تطابق اسم اختيارية مقابل الشخص أو الشركة المتوقعة، وإشارات التلاعب في PDF/EXIF، و`status` بقيمة `Approved`/`Declined`/`In Review`، وقائمة `warnings` توضح كل مشكلة تم العثور عليها. هذا هو المقابل من خادم إلى خادم لخطوة سير العمل المستضافة Document AI (راجع `/core-technology/document-ai/overview`)؛ حيث يستخدم نموذج الاستخراج الافتراضي الخاص بـ Didit ولا يتيح اختيار مزود الخدمة. **زمن الاستجابة.** يعتمد الاستخراج على LLM: تستغرق الاستدعاءات النموذجية **5–15 ثانية**، وتصل في ملفات PDF متعددة الصفحات إلى **~30 ثانية**. اضبط مهلة العميل على **45 ثانية على الأقل** ولا تُعد المحاولة قبل اكتمال الاستدعاء. **تنسيق الطلب.** `multipart/form-data` فقط. `fields` هو **سلسلة مصفوفة واحدة مرمزة بتنسيق JSON** (من 1 إلى 30 عنصرًا، بحد أقصى 16 KB)؛ ويتم رفض مصفوفات النماذج ذات نمط الأقواس بالرمز `400`. كل عنصر هو `{key, name, instruction, type, required, is_full_name}` — حيث يمثل `key` مفتاح JSON الذي تستلمه (`^[a-z0-9_]{1,64}$`، فريد)، ويوضح `instruction` للنموذج ما يجب قراءته، و`type` هو `text` (افتراضي) | `number` | `date`، ويؤدي `required` إلى إطلاق `DOCUMENT_AI_MISSING_REQUIRED_FIELDS` عندما يتعذر قراءة القيمة، ويمكن لحقل واحد على الأكثر تعيين `is_full_name: true` لتمييز القيمة التي ستتم مقارنتها بالاسم المتوقع. **مطابقة الاسم.** مرّر `expected_first_name` + `expected_last_name` (شخص) **أو** `expected_company_name` (+ `expected_company_country` اختياريًا) — وليس كلاهما. تتم مقارنة قيمة الحقل `is_full_name` (أو، في حال عدم تحديد أي حقل، أول حقل نصي يبدو مفتاحه كاسم) بشكل تقريبي؛ ويتم دائمًا إرجاع `name_match_score` (0–100) و`name_on_document` عندما يتوفر كلا الطرفين، كما تؤدي أي درجة أقل من `document_ai_name_match_score_threshold` (الافتراضي 80) إلى إضافة `DOCUMENT_AI_NAME_MISMATCH`، وتخضع لـ `document_ai_name_mismatch_action`. **منطق القرار.** ترتبط كل حالة مخاطر بإجراء قابل للتكوين: `DECLINE` → `status: "Declined"`، و`REVIEW` → `status: "In Review"`، و`NO_ACTION` → لأغراض إعلامية فقط. تعكس الإعدادات الافتراضية خطوة سير العمل: مستند غير مقروء `REVIEW`، وحقول مطلوبة مفقودة `REVIEW`، واشتباه في التلاعب `DECLINE`، وعدم تطابق الاسم `NO_ACTION`، وملف غير مدعوم `REVIEW`. إذا تعذر معالجة المستند على الإطلاق، يُرجع الطلب `400`؛ أما المستند المقروء الذي يحتوي على مشكلات فيُرجع `200` مع `Declined`/`In Review` — تحقق دائمًا من `document_ai.status` و`document_ai.warnings`، وليس رمز HTTP فقط. **الفوترة.** تستهلك كل استجابة `200` رصيد API واحدًا لـ Document AI — **$0.20 لكل مستند** بحسب السعر المعلن، يُدفع من رصيد خطتك أو رصيد شحن الرصيد. عندما يتعذر على رصيد المؤسسة تغطية الاستدعاء، يُرجع الـ endpoint الرمز `403` قبل إجراء أي معالجة. تُرجع مفاتيح API الخاصة بالبيئة التجريبية استجابة تجريبية حتمية ولا تخضع لأي رسوم. **الحفظ الدائم.** عند تعيين `save_api_request=true` (افتراضيًا)، يتم تخزين الاستدعاء كجلسة من نوع API: حيث يتم الاحتفاظ بالمستند والقيم المستخرجة وتعاريف الحقول ولقطة مطابقة الاسم، وتظهر الجلسة في Business Console، ويعمل `request_id` مع `GET /v3/session/{sessionId}/decision/`. operationId: post_v3document-ai requestBody: required: true content: multipart/form-data: schema: type: object required: - document - fields properties: document: type: string format: binary description: >- المستند المراد قراءته. الامتدادات المسموح بها: `tiff`، `jpg`، `jpeg`، `png`، `pdf`، `webp`، `zip`. الحد الأقصى لحجم الرفع: **30 MB** (تُرفض الملفات الأكبر حجماً بالرمز `400`). ملفات PDF متعددة الصفحات مدعومة (توقّع زمن استجابة أعلى)؛ تُرفض ملفات PDF المشفرة بالرمز `400`. تُضغط الصور تلقائياً قبل المعالجة. fields: type: string description: >- سلسلة مصفوفة واحدة بترميز JSON تحتوي على **1–30** من تعريفات الحقول (بحد أقصى 16 كيلوبايت). كل عنصر: `key` (مطلوب، `^[a-z0-9_]{1,64}$`، فريد — المفتاح المُرجع في `extracted_data`)، و`name` (≤100 حرف، يظهر في الرسائل)، و`instruction` (≤500 حرف، ما يجب على النموذج قراءته)، و`type` (`text` افتراضي | `number` | `date`)، و`required` (منطقي، افتراضياً `false`)، و`is_full_name` (منطقي، افتراضياً `false`، واحد على الأكثر لكل طلب). تُرجع مصفوفات النماذج بنمط الأقواس، أو JSON غير الصالح، أو المفاتيح المكررة، أو وجود أكثر من `is_full_name` واحد الخطأ `400` قبل أي معالجة أو فوترة. example: >- [{"key": "employer_name", "name": "Employer name", "instruction": "The employer or company issuing the payslip.", "type": "text", "required": true, "is_full_name": false}, {"key": "employee_name", "name": "Employee name", "instruction": "The full name of the employee as printed on the payslip.", "type": "text", "required": true, "is_full_name": true}, {"key": "net_pay", "name": "Net pay", "instruction": "The net amount paid to the employee for the period.", "type": "number", "required": true, "is_full_name": false}, {"key": "pay_date", "name": "Pay date", "instruction": "The payment date shown on the payslip.", "type": "date", "required": false, "is_full_name": false}] expected_first_name: type: string description: >- الاسم الأول للتحقق منه ومطابقته مع حقل الاسم في المستند (مطابقة تقريبية، تأخذ في الاعتبار الترجمة الصوتية). يُستخدم مع `expected_last_name`؛ ولا يمكن دمجه مع `expected_company_name`. example: Sophia expected_last_name: type: string description: >- اسم العائلة للتحقق منه مقابل حقل الاسم في المستند، مدمجاً مع `expected_first_name` لاحتساب `name_match_score`. example: Martinez expected_company_name: type: string description: >- اسم الشركة للتحقق منه بمطابقته مع حقل الاسم في المستند (لمستندات الشركات). لا يمكن دمجه مع `expected_first_name` / `expected_last_name` (لا توجد قيمة توضيحية عن قصد — عينة الطلب المنشأة تستخدم حقول الأشخاص؛ استبدلها بهذا الحقل عند التحقق من مستند شركة). expected_company_country: type: string description: >- رمز دولة اختياري وفق معيار ISO 3166-1 alpha-2 (حرفان بتنسيق ASCII، مثل `FR`) يضبط معايير تطبيع اسم الشركة لـ `expected_company_name`. يُستخدم فقط مع `expected_company_name`. document_ai_name_match_score_threshold: type: integer minimum: 0 maximum: 100 default: 80 description: >- الحد الأدنى لـ `name_match_score` (من 0 إلى 100) لاعتبار الاسم متطابقًا. تؤدي الدرجة الأقل إلى إضافة `DOCUMENT_AI_NAME_MISMATCH`، ويحكمها `document_ai_name_mismatch_action`. example: 80 document_ai_unreadable_document_action: type: string enum: - DECLINE - REVIEW - NO_ACTION default: REVIEW description: >- الإجراء المتبع عندما يتعذر قراءة أي حقل من المستند (`DOCUMENT_AI_UNREADABLE_DOCUMENT`). document_ai_missing_required_fields_action: type: string enum: - DECLINE - REVIEW - NO_ACTION default: REVIEW description: >- الإجراء المتبع عندما يتعذر قراءة حقل واحد على الأقل من الحقول المطلوبة `required` (`DOCUMENT_AI_MISSING_REQUIRED_FIELDS`؛ وتسردهم `additional_data.missing_fields`). document_ai_document_tampering_action: type: string enum: - DECLINE - REVIEW - NO_ACTION default: DECLINE description: >- الإجراء المتبع عند الاشتباه في تلاعب عبر التحليل الجنائي لـ PDF/EXIF — تعديل بعد التوقيع الرقمي، أو محرر PDF معروف، أو تلاعب بنصوص متراكبة، أو إعادة تصدير مريبة، أو شذوذ في الصورة (`DOCUMENT_AI_SUSPECTED_MANIPULATION`). document_ai_name_mismatch_action: type: string enum: - DECLINE - REVIEW - NO_ACTION default: NO_ACTION description: >- الإجراء المتبع عندما يكون `name_match_score` أقل من الحد الأدنى (`DOCUMENT_AI_NAME_MISMATCH`). document_ai_unsupported_file_action: type: string enum: - DECLINE - REVIEW - NO_ACTION default: REVIEW description: >- الإجراء المتخذ عندما يكون الملف المرفوع فارغاً أو غير قابل للمعالجة (`DOCUMENT_AI_UNSUPPORTED_FILE`). save_api_request: type: boolean default: true description: >- عندما تكون القيمة `true` (الافتراضية)، يتم حفظ الاستدعاء كجلسة من نوع API — مرئية في Business Console، ويمكن استرجاعها عبر `GET /v3/session/{sessionId}/decision/` باستخدام `request_id` المُرجع، مع تخزين المستند المرفوع والقيم المستخرجة وتعاريف الحقول ولقطة مطابقة الاسم. عندما تكون القيمة `false`، لا يتم تخزين أي شيء ويكون `request_id` عبارة عن معرّف UUID مؤقت للربط بالاستجابة فقط؛ مع استمرار فوترة الاستدعاء. 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 responses: '200': description: >- تمت معالجة المستند. تكون قيمة `document_ai.status` إما `Approved` أو `Declined` أو `In Review`؛ وتُفصّل كل مشكلة تم اكتشافها في `document_ai.warnings`. المستند الذي يحتوي على مشاكل سيظل يُرجع `200` — افحص نص الاستجابة، وليس فقط رمز HTTP. عندما تكون `save_api_request=true`، يكون `request_id` هو معرّف الجلسة المحفوظ. content: application/json: examples: Approved: summary: تمت قراءة قسيمة الراتب بنجاح، وتطابق الاسم value: request_id: 9d6a3b1e-2f0c-4a8e-9b7d-1c2e3f4a5b6c document_ai: status: Approved extracted_data: employer_name: Acme Payments Ltd employee_name: Sophia Martinez net_pay: 3120.5 pay_date: '2026-07-31' detected_codes: - type: CODE_128 page_number: 1 position: - - 96 - 456 - - 96 - 616 - - 1012 - 611 - - 1015 - 456 x: 96 'y': 456 width: 919 height: 160 page_width: 1200 page_height: 1700 raw_payload: SU5WLTIwMjYtMDA0Mg== parsed_payload: INV-2026-0042 fields: - key: employer_name name: Employer name instruction: The employer or company issuing the payslip. type: text required: true is_full_name: false - key: employee_name name: Employee name instruction: >- The full name of the employee as printed on the payslip. type: text required: true is_full_name: true - key: net_pay name: Net pay instruction: The net amount paid to the employee for the period. type: number required: true is_full_name: false - key: pay_date name: Pay date instruction: The payment date shown on the payslip. type: date required: false is_full_name: false name_match_score: 100 name_on_document: Sophia Martinez warnings: [] vendor_data: user-123 metadata: flow: onboarding created_at: '2026-08-19T16:40:12.318Z' In Review — missing required field: summary: تعذرت قراءة `net_pay`؛ الإجراء الافتراضي هو REVIEW value: request_id: 3f2a9c7b-5d4e-4b1a-8c6f-0e9d8c7b6a5f document_ai: status: In Review extracted_data: employer_name: Acme Payments Ltd employee_name: Sophia Martinez net_pay: null pay_date: '2026-07-31' detected_codes: [] fields: - key: employer_name name: Employer name instruction: The employer or company issuing the payslip. type: text required: true is_full_name: false - key: employee_name name: Employee name instruction: >- The full name of the employee as printed on the payslip. type: text required: true is_full_name: true - key: net_pay name: Net pay instruction: The net amount paid to the employee for the period. type: number required: true is_full_name: false - key: pay_date name: Pay date instruction: The payment date shown on the payslip. type: date required: false is_full_name: false name_match_score: 100 name_on_document: Sophia Martinez warnings: - risk: DOCUMENT_AI_MISSING_REQUIRED_FIELDS feature: DOCUMENT_AI additional_data: missing_fields: - Net pay log_type: warning short_description: Required fields could not be extracted long_description: >- One or more fields configured as required could not be extracted from the uploaded document. vendor_data: null metadata: null created_at: '2026-08-19T16:41:05.002Z' Declined — suspected manipulation: summary: >- التحليل الجنائي لملف PDF رصد محررًا معروفًا؛ الإجراء الافتراضي هو DECLINE value: request_id: 7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f document_ai: status: Declined extracted_data: employer_name: Acme Payments Ltd employee_name: Sophia Martinez net_pay: 3120.5 pay_date: '2026-07-31' detected_codes: [] fields: - key: employer_name name: Employer name instruction: The employer or company issuing the payslip. type: text required: true is_full_name: false - key: employee_name name: Employee name instruction: >- The full name of the employee as printed on the payslip. type: text required: true is_full_name: true - key: net_pay name: Net pay instruction: The net amount paid to the employee for the period. type: number required: true is_full_name: false - key: pay_date name: Pay date instruction: The payment date shown on the payslip. type: date required: false is_full_name: false name_match_score: null name_on_document: Sophia Martinez warnings: - risk: DOCUMENT_AI_SUSPECTED_MANIPULATION feature: DOCUMENT_AI additional_data: detection_method: known_editor processed_by_known_editor: ilovepdf log_type: error short_description: Suspected document manipulation long_description: >- The system detected signs of potential manipulation or editing in the uploaded document. vendor_data: null metadata: null created_at: '2026-08-19T16:42:40.771Z' schema: type: object properties: request_id: type: string format: uuid description: >- معرّف الجلسة المحفوظة عندما تكون `save_api_request=true` (يمكن استخدامه مع `GET /v3/session/{sessionId}/decision/`)؛ وإلا فسيكون UUID ارتباط مؤقت. document_ai: type: object properties: status: type: string enum: - Approved - Declined - In Review description: >- `Approved` عندما لا يؤدي أي تحذير إلى الرفض أو المراجعة؛ و`Declined` عندما يؤدي خطر واحد على الأقل إلى `DECLINE`؛ وخلاف ذلك `In Review` عندما يؤدي خطر واحد على الأقل إلى `REVIEW`. توضح قائمة `warnings` السبب. extracted_data: type: object additionalProperties: true description: >- إدخال واحد لكل مفتاح حقل مطلوب. تُكتب القيم بنوع البيانات الخاص بالحقل `type` — نصوص لـ `text`، وأرقام لـ `number`، ونصوص بصيغة `YYYY-MM-DD` لـ `date` — أو `null` إذا تعذرت قراءة القيمة. example: employer_name: Acme Payments Ltd employee_name: Sophia Martinez net_pay: 3120.5 pay_date: '2026-07-31' detected_codes: type: array description: >- رموز QR والرموز الشريطية المكتشفة في كل صفحة تمت معالجتها. تكون فارغة عند عدم العثور على أي منها. رمز QR الذي تم تحديد مكانه ولكن تعذر فك تشفيره يحتوي على `parsed_payload: null`. items: $ref: '#/components/schemas/DocumentAIDetectedCode' fields: type: array description: >- تعريفات الحقول الموحّدة التي استُخدمت لعملية الاستخراج هذه، وتتم إعادتها كاستجابة (كما تُخزّن مع الجلسة عندما تكون `save_api_request=true`). items: type: object properties: key: type: string name: type: string instruction: type: string type: type: string enum: - text - number - date required: type: boolean is_full_name: type: boolean name_match_score: type: number nullable: true minimum: 0 maximum: 100 description: >- التشابه التقريبي (0–100) بين `name_on_document` واسم الشخص/الشركة المتوقع. يتم إرجاعه كلما توفرت قيمة الاسم والاسم المتوقع معاً — في حالات التطابق **و**عدم التطابق؛ ويكون `null` خلاف ذلك. example: 96 name_on_document: type: string nullable: true description: >- قيمة الاسم المأخوذة من المستند (الحقل `is_full_name`، أو أول حقل نصي يشبه الاسم) التي تمت مقارنتها بالاسم المتوقع. تكون `null` عندما لا تتوفر أي قيمة للاسم. example: Sophia Martinez warnings: type: array description: >- فارغ عند الموافقة السليمة. يوضح كل إدخال خطراً واحداً تم اكتشافه؛ تُعيّن الإدخالات ذات `log_type: "error"` الـ `status` إلى `Declined`، وتُعيّنه الإدخالات ذات `log_type: "warning"` إلى `In Review`. items: type: object properties: risk: type: string enum: - DOCUMENT_AI_UNREADABLE_DOCUMENT - DOCUMENT_AI_MISSING_REQUIRED_FIELDS - DOCUMENT_AI_SUSPECTED_MANIPULATION - DOCUMENT_AI_NAME_MISMATCH - DOCUMENT_AI_UNSUPPORTED_FILE description: >- رمز مخاطر مقروء آلياً. يخضع كل منها لخيار الطلب `document_ai_*_action` المطابق له. example: DOCUMENT_AI_MISSING_REQUIRED_FIELDS feature: type: string enum: - DOCUMENT_AI description: >- الميزة التي أصدرت التحذير. دائماً `DOCUMENT_AI` في هذا الـ endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- سياق إضافي للمخاطر: `{"missing_fields": ["Net pay"]}` للحقول المطلوبة المفقودة، و`{"name_on_document", "score", "threshold"}` لعدم تطابق الاسم، والاستنتاج الجنائي (`detection_method`، وتفاصيل المُنشئ/المُحرر) في حالات الاشتباه في التلاعب. ويكون `null` عند عدم وجود ما يمكن إضافته. example: missing_fields: - Net pay log_type: type: string enum: - error - warning - information description: >- مستوى الخطورة المشتق من الإجراء المُهيّأ: `error` (DECLINE)، و`warning` (REVIEW)، و`information` (NO_ACTION). short_description: type: string description: عبارة من سطر واحد مقروءة للبشر تصف المخاطر. example: Required fields could not be extracted long_description: type: string description: >- تفسير سهل القراءة، مع دمج `additional_data` عند الاقتضاء. 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: متى تمت معالجة الطلب (UTC، ISO 8601). '400': description: >- خطأ في التحقق أو المعالجة. تُرجع المشكلات على مستوى الحقول غلاف DRF القياسي (مصفوفة واحدة من الرسائل لكل حقل مخالف). وتُرجع المستندات المشفرة أو غير القابلة للقراءة وإخفاقات الاستخراج `{"error": ...}`. content: application/json: examples: Missing document: summary: '`document` غير مدرج في بيانات النموذج' value: document: - No file was submitted. Invalid fields payload: summary: '`fields` ليست سلسلة واحدة لمصفوفة بترميز JSON' value: fields: - fields must be a valid JSON array string. Duplicate field keys: summary: عنصران يشتركان في نفس الـ `key` value: fields: - Every fields item must have a unique key. Conflicting expectations: summary: تم إرسال توقعات الشخص والشركة معاً value: non_field_errors: - >- Provide either person expected-name fields or expected_company_name, not both. Invalid metadata: summary: '`metadata` ليس كائن JSON (أو يحتوي على حرف NUL)' value: metadata: - Metadata must be a JSON object. Oversized vendor_data: summary: تجاوز `vendor_data` الحد الأقصى البالغ 2,000 بايت value: vendor_data: - vendor_data is too long (maximum 2000 bytes). Encrypted PDF: summary: ملف PDF محمي بكلمة مرور value: error: >- The PDF is encrypted. Please upload a decrypted PDF or a photo instead. Extraction failed: summary: تعذر على مسار الاستخراج معالجة المستند value: error: - Error extracting Document AI information schema: type: object additionalProperties: true '403': description: >- تم رفض الإذن. يُرجع عند فقدان الرأس `x-api-key`، وأيضاً عندما لا يتمكن رصيد المؤسسة الطالبة من تغطية الاستدعاء؛ ويُرجع المفتاح الخاطئ أو الملغى أو منتهي الصلاحية `401`. يؤدي المفتاح المفقود إلى إرجاع `403` مع `{"detail": ...}`؛ ويؤدي المفتاح الخاطئ أو الملغى أو منتهي الصلاحية إلى إرجاع `401`. يؤدي نقص الرصيد — والمؤسسات التي تتم فوترتها بموجب عقد ولا يتضمن جدول الأسعار الخاص بها بنداً لـ API Document AI — إلى إرجاع `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 Contract rate missing: summary: >- مؤسسة مفوترة بموجب عقد لا يحتوي جدول الأسعار الخاص بها على بند Document AI API value: error: >- Document AI API is not included in your contract rate card. Contact support@didit.me to enable it. schema: type: object properties: detail: type: string error: type: string '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: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.document_ai.analyze( document=open("document.pdf", "rb"), fields="[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]", ) 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.documentAi.analyze({ document: await fileFromPath("document.pdf"), fields: "[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.DocumentAi.Analyze(ctx, didit.DocumentAiAnalyzeParams{\n\tDocument: didit.FileFromPath(\"document.pdf\"),\n\tFields: \"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\",\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 me.didit.Didit; import me.didit.types.DocumentAiAnalyzeParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.documentAi().analyze(DocumentAiAnalyzeParams.builder() .document(Path.of("document.pdf")) .fields("[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]") .build()); System.out.println(result); - lang: php label: PHP source: |- documentAi->analyze([ 'document' => File::fromPath('document.pdf'), 'fields' => '[{"key": "employer_name", "name": "Employer name", "instruction": "The employer or company issuing the payslip.", "type": "text", "required": true, "is_full_name": false}, {"key": "employee_name", "name": "Employee name", "instruction": "The full name of the employee as printed on the payslip.", "type": "text", "required": true, "is_full_name": true}, {"key": "net_pay", "name": "Net pay", "instruction": "The net amount paid to the employee for the period.", "type": "number", "required": true, "is_full_name": false}, {"key": "pay_date", "name": "Pay date", "instruction": "The payment date shown on the payslip.", "type": "date", "required": false, "is_full_name": false}]', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.document_ai.analyze( document: Pathname("document.pdf"), fields: "[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]" ) 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.DocumentAi.AnalyzeAsync(new DocumentAiAnalyzeParams { Document = FileUpload.FromPath("document.pdf"), Fields = "[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: DocumentAIDetectedCode: type: object required: - type - page_number - position - x - 'y' - width - height - page_width - page_height - raw_payload - parsed_payload properties: type: type: string description: >- الترميز المكتشف، على سبيل المثال `QR_CODE`، أو `CODE_128`، أو `EAN_13`، أو `DATA_MATRIX`، أو `PDF_417`. page_number: type: integer minimum: 1 description: رقم الصفحة (بدءاً من 1). position: type: array nullable: true description: >- المضلع المكتشف بإحداثيات البكسل للصفحة المعروضة. يكون `null` عند عدم توفر موقع موثوق. items: type: array minItems: 2 maxItems: 2 items: type: integer x: type: integer nullable: true description: الحافة اليسرى للمربع المحيط بوحدات البكسل في الصفحة المعروضة. 'y': type: integer nullable: true description: الحافة العلوية لمربع الإحاطة بوحدات البكسل الخاصة بالصفحة المعروضة. width: type: integer nullable: true description: عرض المربع المحيط ببكسلات الصفحة المعروضة. height: type: integer nullable: true description: ارتفاع المربع المحيط ببكسلات الصفحة المعروضة. page_width: type: integer description: عرض الصفحة المعروضة بالبكسل. page_height: type: integer description: ارتفاع الصفحة المعروضة بالبكسل. raw_payload: type: string description: >- payload الخام الخاص بأداة فك الترميز في شكل سلسلة base64 عند توفره؛ وإلا فسيكون سلسلة فارغة. parsed_payload: nullable: true description: >- سلسلة نصية مفكوكة الترميز أو قيمة مهيكلة. `null` عندما تم تحديد موقع الرمز ولكن تعذر فك ترميزه. 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.