الانتقال إلى المحتوى الرئيسي
POST
Python
أرسل مستنداً واحداً وقائمة الحقول التي تريد قراءتها منه. يشغّل Didit نموذج الاستخراج الافتراضي على الملف، ويعيد كل حقل مع نوعه (text أو number أو date بصيغة YYYY-MM-DD)، ويكتشف رموز QR والباركود المدعومة ويفك ترميزها، ويفحص الملف بحثاً عن التلاعب، ويقارن اختيارياً الاسم الوارد في المستند بالشخص أو الشركة التي تتوقعها. استخدمه لإثبات الأموال، وكشوف الرواتب، وكشوف الحسابات البنكية، والمستندات الضريبية، والفواتير، أو أي مستند لا يتطابق مع قالب ثابت. هذه هي النسخة من خادم إلى خادم لخطوة Document AI المستضافة. الطلب من نوع multipart/form-data: يُرسل الملف في document، وتُرسل تعريفات الحقول في fields كسلسلة نصية واحدة تحتوي على مصفوفة JSON مُرمَّزة.

تحديد الحقول المراد استخراجها

fields مصفوفة JSON تضم من 1 إلى 30 عنصراً، وتُرسل كسلسلة واحدة. يحتوي كل عنصر على key (أحرف إنجليزية صغيرة وأرقام وشرطات سفلية، وفريدة داخل الطلب)، وname مقروء للإنسان، وinstruction يخبر النموذج بما يبحث عنه، وtype (text أو number أو date)، وعلمين هما required وis_full_name.
في طلب multipart تُرسل المصفوفة كلها كقيمة نموذج واحدة:
تعيد الاستجابة fields بعد تطبيعها، وextracted_data مفهرسة بقيم key التي أرسلتها، مع null لأي حقل لم يتمكن النموذج من العثور عليه. الحقول name وinstruction وtype اختيارية في كل عنصر (ويكون type افتراضياً text)، أما key فمطلوب. إرسال fields كمفاتيح نموذج على شكل أقواس (fields[0][key]=...) أو كأي شيء غير مصفوفة JSON يعيد 400 قبل بدء أي استخراج، فلا يُحتسب أي مبلغ.

رموز QR والباركود

تتضمن كل استجابة ناجحة الحقل document_ai.detected_codes. يحتوي كل عنصر فيه على ما يلي: تغطي المصفوفة كل صفحة معالجة من ملف PDF، وتكون فارغة عندما لا يُعثر على أي رمز مدعوم. لا يخمّن Didit أبداً محتوى الرمز: قد تُعاد رموز QR التالفة مع موقعها وparsed_payload: null، ولا يؤدي فشل اكتشاف الرموز إلى فشل طلب Document AI.

مطابقة الأسماء

ضع علامة is_full_name: true على حقل واحد كحد أقصى، وأرسل بيانات الشخص أو الشركة التي تتوقع أن يكون المستند عائداً إليها: أرسل إحدى المجموعتين، لا كلتيهما. عندما يُستخرج اسم ويكون هناك اسم متوقع، تتضمن الاستجابة 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 والتحذيرات لمعرفة كيفية اكتشاف كل خطر.

الملفات والحفظ والفوترة

  • الملفات المقبولة: PDF (يدعم المستندات متعددة الصفحات)، وJPG وJPEG وPNG وTIFF وWebP، أو ملف ZIP يحتوي على المستند، بحجم يصل إلى 30 MB. ملفات PDF المشفّرة تعيد 400؛ ارفع نسخة PDF غير مشفّرة أو صورة فوتوغرافية بدلاً منها.
  • save_api_request (الافتراضي true): يظهر الطلب والحقول المستخرجة والرموز المكتشفة في Business Console ضمن الفحوصات اليدوية، حيث يستطيع فريقك مراجعتها. اضبطه على false لتخطي الحفظ.
  • vendor_data وmetadata تُعادان دون تغيير في الاستجابة، لتتمكن من ربط النتيجة بسجلاتك الخاصة.
  • السعر: $0.20 لكل مستند، ويُحتسب عند معالجة المستند وإرجاع حالة. يُطبَّق خصم خطتك. راجع الأسعار.
هل تحتاج إلى أن يرفع المستخدم المستند بنفسه، أو جمع ما يصل إلى 3 مستندات في تدفق واحد، أو الترجمة التلقائية لشاشة الرفع، أو مقارنة الحقول المستخرجة ببيانات الهوية أو الاستبيان؟ استخدم بدلاً من ذلك خطوة سير عمل Document AI المستضافة.

التفويضات

x-api-key
string
header
مطلوب

مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console. يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير 404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL للصور ومقاطع الفيديو وملفات PDF كـ null، ويتلقى المفتاح الذي لا يمتلك إذن كتابة للجلسات روابط الجلسة وtoken كـ null. راجع https://docs.didit.me/console/api-keys.

الجسم

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

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

fields
string
مطلوب

سلسلة مصفوفة واحدة بترميز 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 قبل أي معالجة أو فوترة.

مثال:

"[{\"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
string

الاسم الأول للتحقق منه ومطابقته مع حقل الاسم في المستند (مطابقة تقريبية، تأخذ في الاعتبار الترجمة الصوتية). يُستخدم مع expected_last_name؛ ولا يمكن دمجه مع expected_company_name.

مثال:

"Sophia"

expected_last_name
string

اسم العائلة للتحقق منه مقابل حقل الاسم في المستند، مدمجاً مع expected_first_name لاحتساب name_match_score.

مثال:

"Martinez"

expected_company_name
string

اسم الشركة للتحقق منه بمطابقته مع حقل الاسم في المستند (لمستندات الشركات). لا يمكن دمجه مع expected_first_name / expected_last_name (لا توجد قيمة توضيحية عن قصد — عينة الطلب المنشأة تستخدم حقول الأشخاص؛ استبدلها بهذا الحقل عند التحقق من مستند شركة).

expected_company_country
string

رمز دولة اختياري وفق معيار ISO 3166-1 alpha-2 (حرفان بتنسيق ASCII، مثل FR) يضبط معايير تطبيع اسم الشركة لـ expected_company_name. يُستخدم فقط مع expected_company_name.

document_ai_name_match_score_threshold
integer
افتراضي:80

الحد الأدنى لـ name_match_score (من 0 إلى 100) لاعتبار الاسم متطابقًا. تؤدي الدرجة الأقل إلى إضافة DOCUMENT_AI_NAME_MISMATCH، ويحكمها document_ai_name_mismatch_action.

النطاق المطلوب: 0 <= x <= 100
مثال:

80

document_ai_unreadable_document_action
enum<string>
افتراضي:REVIEW

الإجراء المتبع عندما يتعذر قراءة أي حقل من المستند (DOCUMENT_AI_UNREADABLE_DOCUMENT).

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

الإجراء المتبع عندما يتعذر قراءة حقل واحد على الأقل من الحقول المطلوبة required (DOCUMENT_AI_MISSING_REQUIRED_FIELDS؛ وتسردهم additional_data.missing_fields).

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

الإجراء المتبع عند الاشتباه في تلاعب عبر التحليل الجنائي لـ PDF/EXIF — تعديل بعد التوقيع الرقمي، أو محرر PDF معروف، أو تلاعب بنصوص متراكبة، أو إعادة تصدير مريبة، أو شذوذ في الصورة (DOCUMENT_AI_SUSPECTED_MANIPULATION).

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

الإجراء المتبع عندما يكون name_match_score أقل من الحد الأدنى (DOCUMENT_AI_NAME_MISMATCH).

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

الإجراء المتخذ عندما يكون الملف المرفوع فارغاً أو غير قابل للمعالجة (DOCUMENT_AI_UNSUPPORTED_FILE).

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

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

مثال:

true

vendor_data
string

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

مثال:

"user-123"

metadata
object

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

مثال:

الاستجابة

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

request_id
string<uuid>

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

document_ai
object
vendor_data
string | null

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

metadata
object | null

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

created_at
string<date-time>

متى تمت معالجة الطلب (UTC، ISO 8601).

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