POST /v1/kyc/extract ملفات خطوة رفع واحدة ويعيد الحقول التي عثر عليها، والفحوص الخاصة بكل مستند، ومع reference يعيد معرّف ملف حالة (case) ومعرّفات المستندات. النطاق (scope): kyc:extract. هذا هو الاستدعاء الوحيد الذي يستخدم نموذج الرؤية، ولذلك هو الوحيد الذي يُحتسب ضمن حصة القراءات الشهرية.
الطلب
نموذج متعدد الأجزاء (multipart/form-data). الحقل files وحده مطلوب.
أرسلوا نوع مستند واحدًا في كل استدعاء. يسري
doc_type وstep_key على جميع الملفات في الاستدعاء، والحالة المعتادة لملفين هي وجه البطاقة وظهرها.
قواعد الملفات
يُؤخذ نوع المحتوى من ترويسة جزء multipart لديكم، لا من اسم الملف. أرسلوا
Content-Type الصحيح لكل جزء ملف. تضبطه معظم مكتبات HTTP وcurl -F من الامتداد.
ما يحدث عند الاستدعاء
الترتيب مهم في موضعين. أخطاء التحقق (400 و413 و422) تحدث قبل حجز القراءة، فلا تكلّف شيئًا. ويحدث الحجز قبل تشغيل النموذج، فالقراءة التي تفشل بعد ذلك تُحتسب مع ذلك.الاستجابة
مفاتيح المستوى الأعلى
مفاتيح كل عنصر في documents[]
مفاتيح
meta_provenance: لملف PDF، producer وcreator (البرنامج، حتى 200 حرف)، وmodified (قيمة ModDate بصيغة YYYY-MM-DD، عندما تختلف عن تاريخ الإنشاء)، وrevisions (عدد مرات حفظ الملف تزايديًا). وللصورة، creator (وسم EXIF Software) وcamera (وسم EXIF Make). غياب كتلة EXIF لا يُبلَّغ عنه، لأن WhatsApp ومعظم المتصفحات تزيلها.
قيم الحقول
كل قيمة فيfields سلسلة نصية. يُطلب من القارئ حذف الحقل الذي لا يستطيع قراءته، فغياب المفتاح يعني “لم يُقرأ” وليس “فارغ” أبدًا. ثم يوحّد الخادم القيم:
التصحيحات التي يجريها الخادم بعد القراءة، وكل منها مدرج في
notes:
- لا تُحفظ البيانات المصرفية إلا إذا كان المستند مستندًا مصرفيًا (شيك ملغى، كشف حساب، رسالة من البنك، RIB). وتُزال من أي مستند آخر، لأن رقم الحساب في فاتورة مرافق أو IBAN في فاتورة ليس للعميل.
bank_numberوbank_transitرمزان كنديان. يُسقطان إذا كان المستند من بلد آخر، أو إذا كان الطول خاطئًا (3 أرقام و5 أرقام). ويُنقلbank_numberالمكوّن من 9 أرقام إلىbank_routing، لأن 9 أرقام تمثل رقم توجيه أمريكيًا.- الاسم الذي يُقرأ على أنه اسم أحد الوالدين في البطاقة المغربية (
... ben ...وfils deوbent) يُسقط منfirst_nameوlast_nameوdocument_holder_name. - في الفاتورة، لا يُدمج الاسم القانوني للمورّد وعنوانه وأرقام تسجيله في
fieldsما لم يكن المستلم هو الكيان نفسه. - يبقى
specimen_markingsفي عنصر المستند ولا يُدمج فيfieldsأبدًا.
الثقة
لا تعيد الواجهة درجة ثقة لكل حقل ولا درجة لكل مستند. يعطي القارئ قيمًا لا احتمالات. لا تبحثوا عن مفتاح ثقة. ما زال بإمكانكم الحكم على القراءة:
تعرض وحدة التحكم (console) قيمة ثابتة 0.9 لكل حقل يعيده القارئ. هي وسم يعني “قرأه النموذج ولم يُراجَع بعد”، وليست قياسًا، ويبقى التحقق من الحقل
pending إلى أن يراجعه شخص.
reader_unavailable
تعني reader_unavailable: true أن ملفًا واحدًا على الأقل لم يُقرأ: لا توجد بيانات اعتماد من جانب Sahl، أو تجاوز حصة أو مهلة، أو إجابة تعذّر تحليلها. ولا تعني أن المستند كان فارغًا. المستند الفارغ أو المقصوص يعيد reader_unavailable: false مع حقول قليلة أو دون حقول.
يعيد الاستدعاء 200 مع ذلك. وتُحتسب القراءة. أعيدوا محاولة الملف لاحقًا، وإن استمر ذلك فاذكروا ترويسة X-Request-ID لـ Sahl.
مع reference يُحفظ كل ملف في ملف الحالة بوضع تشاهدونه في وحدة التحكم ضمن Documents:
فحوص المستندات في الإجابة
يحصل كل ملف على الفحوص التي تناسب نوعه. وهي نفسها الفحوص التي يكررها/verify على المدخلات التي تعيدونها. القائمة الكاملة بمعانيها في التحقق من ملف تعريف.
باختصار: المستند من النوع الذي تتوقعه الخطوة (doctype:)، وقُرئت حقوله الأساسية (legible:)، والهوية غير منتهية (expiry:) أو على وشك الانتهاء (expiry_soon:)، وصاحبها بعمر 18 سنة أو أكثر (adult:)، وأرقام التحقق في MRZ لجواز السفر أو بطاقة الهوية صحيحة (mrz:)، وإثبات العنوان حديث (recency:)، ولم يُعد حفظ الملف من محرر (provenance:)، والمستند ليس نموذجًا أو عينة (authenticity:specimen:).
قسيمة الراتب (payslip) لا تحصل على أي فحص مستند. يحمل عنصرها الحقول فقط.