> ## 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. # واجهة برمجة التحقق من إثبات العنوان (POA) والتعرف الضوئي > Didit: تحقق من فواتير المرافق وكشوف الحسابات وعقود الإيجار عبر POST /v3/poa/، مع استخراج العنوان بالتعرف الضوئي وفحص الأصالة، بلا عقود. ## OpenAPI ````yaml ar/openapi-25.json POST /v3/poa/ 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/poa/: post: tags: - Standalone APIs summary: إثبات العنوان (OCR للمستند + عمليات التحقق من العنوان) description: >- استخراج والتحقق من مستند إثبات العنوان — فواتير المرافق، وكشوف الحسابات البنكية، والمستندات الصادرة عن الجهات الحكومية — في استدعاء واحد. يُرجع جهة الإصدار، وتواريخ الإصدار/الانتهاء، واسم حامل المستند، والعنوان بصيغته الأولية والمعالجة/المحددة جغرافياً، و`status` بقيمة `Approved`/`Declined`، وقائمة `warnings` توضح كل مشكلة تم العثور عليها. **زمن الاستجابة.** يعتمد الاستخراج على نماذج LLM: تستغرق الاستدعاءات النموذجية **5–15 ثانية**، وملفات PDF متعددة الصفحات حتى **~30 ثانية**. قم بتكوين مهلة العميل لتكون **45 ثانية على الأقل** ولا تقم بإعادة المحاولة قبل اكتمال الاستدعاء. **آلية العمل.** يتم تصنيف المستند (صورة أو PDF، حتى 15 MB؛ تتطلب ملفات PDF المشفرة `document_password`) إلى نوع مستند ونوع فرعي (مثل `UTILITY_BILL` / `WATER_BILL`)، ويتم استخراج جهة الإصدار، والتواريخ، واسم حامل المستند، والعنوان باستخدام استخراج يعتمد على نماذج LLM. تتم معالجة العنوان وتحديده جغرافياً في `poa_parsed_address`. يقوم الفحص الجنائي لملفات PDF/EXIF بالتحقق من التلاعب — التعديل بعد التوقيع الرقمي، ومحررات PDF المعروفة، والتلاعب بالنصوص المتراكبة، وعمليات إعادة التصدير المشبوهة — مما يظهر `SUSPECTED_DOCUMENT_MANIPULATION` أو `DOCUMENT_METADATA_MISMATCH`. حقل النص الذي تم إفراغه وإعادة كتابته بخط آخر، حيث لا يحتوي الملف نفسه على دليل يثبت ما إذا كان محتواه قد تغير، يظهر `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`. يتم التحقق من عمر المستند مقارنة بـ `poa_document_age_months`، واللغة مقارنة بـ `poa_languages_allowed`. إذا قمت بتمرير `expected_address`، أو `expected_country`، أو `expected_first_name`/`expected_last_name`، تتم مطابقة القيم المستخرجة ووضع علامات على أي عدم تطابق. **منطق القرار.** تكون `status` هي `Approved` ما لم تؤدِ إحدى التحذيرات على الأقل إلى الرفض. تؤدي حالات الفشل الصريحة دائماً إلى الرفض: `MISSING_ADDRESS_INFORMATION`، و`POA_DOCUMENT_EXPIRED`، و`INVALID_DOCUMENT_TYPE`، و`UNABLE_TO_VALIDATE_DOCUMENT_AGE`، بالإضافة إلى `UNABLE_TO_EXTRACT_ISSUE_DATE` و`POA_NAME_NOT_DETECTED` (غير قابلة للتكوين في هذا الـ endpoint). تتوفر خمس مجموعات مخاطر قابلة للتكوين لكل طلب عبر خيارات `poa_*_action` (`DECLINE` أو `NO_ACTION`، وجميعها مضبوطة افتراضياً على `DECLINE`). يُعد `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` و`UNPARSABLE_OR_INVALID_ADDRESS` تحذيرات إعلامية في هذا الـ endpoint ولا تؤدي إلى الرفض أبداً. المستند الذي لا يمكن معالجته على الإطلاق يُرجع `400`؛ بينما يُرجع الـ endpoint للمستند المقروء ذي المشكلات الرمز `200` مع `status: "Declined"` — تحقق دائماً من `poa.status` و`poa.warnings`، وليس فقط رمز استجابة HTTP. **الفوترة.** يستهلك كل رد `200` رصيد API واحد لإثبات العنوان (يُدفع من رصيد خطتك أو رصيد شحن الرصيد). عندما لا يتمكن رصيد المؤسسة من تغطية الاستدعاء، يُرجع الـ endpoint الرمز `403` مع خطأ عدم كفاية الرصيد قبل معالجة أي مستند. **حفظ الجلسة (`save_api_request`، القيمة الافتراضية `true`).** عند ضبطه على `true`، يتم حفظ الاستدعاء كجلسة من نوع API: يظهر في Business Console، ويتم تخزين المستند المرفوع، ويكون `request_id` المُرجع هو معرف جلسة حقيقي يمكنك تمريره إلى `GET /v3/session/{sessionId}/decision/` (يعرض القرار بالإضافة إلى ذلك `document_file` والفحص الجنائي في `document_metadata`، والذي لا تتضمنه هذه الاستجابة)، ويتم إرسال حدث webhook باسم `status.updated`. عند ضبطه على `false`، لا يتم تخزين أي شيء ويكون `request_id` عبارة عن UUID ارتباط يُستخدم لمرة واحدة ولا يمكن البحث عنه لاحقاً. **البيئة التجريبية.** تتخطى مفاتيح API في البيئة التجريبية جميع عمليات المعالجة والفوترة: بعد التحقق من صحة الطلب (تظل المدخلات غير الصالحة تُرجع `400`)، يُرجع الـ endpoint نموذج payload وهمي وثابت بقيمة `Approved` (فاتورة كهرباء خيالية لشركة "Sandbox Power Co.")، ولا يتم حفظ أي جلسة، ولا يُستهلك أي رصيد. **المصادقة.** أرسل مفتاح API الخاص بتطبيقك في الرأس `x-api-key`. تُرجع بيانات الاعتماد المفقودة أو غير الصالحة `403` (`{"detail": "You do not have permission to perform this action."}`) — لا تُرجع واجهة API هذه الرمز `401` أبداً. **حد المعدل.** ميزانية كتابة مشتركة تبلغ 300 طلب/دقيقة لكل مفتاح API عبر جميع endpoints الخاصة بـ POST/PATCH/DELETE؛ وتجاوزها يُرجع `429`. ملاحظة: يوجد `FUTURE_ISSUE_DATE` و`POOR_DOCUMENT_QUALITY` في جلسات سير العمل، ولكن لا يتم إنتاجهما أبداً بواسطة هذا الـ endpoint المستقل — لا يتم رفض المستند ذي التاريخ المستقبلي تلقائياً هنا. operationId: post_v3poa parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - document properties: document: type: string format: binary description: >- مستند إثبات العنوان. الامتدادات المسموح بها: `tiff`، و`jpg`، و`jpeg`، و`png`، و`pdf`، و`webp`. الحد الأقصى لحجم الرفع: **15 MB** (يتم رفض الملفات الأكبر حجماً بالرمز `400`). ملفات PDF متعددة الصفحات مدعومة (توقع استجابة أبطأ)؛ وتتطلب ملفات PDF المشفرة `document_password`. يتم ضغط الصور تلقائياً قبل معالجتها. document_password: type: string description: >- كلمة المرور لفك تشفير `document` عندما يكون ملف PDF مشفراً. إرسال ملف PDF مشفر بدون كلمة مرور (أو بكلمة مرور خاطئة) يُرجع الرمز `400`. writeOnly: true expected_address: type: string description: >- العنوان المراد التحقق منه مقابل المستند. يتم تحديد موقعه الجغرافي ومقارنته بالعنوان المستخرج؛ وأي عدم تطابق (أو عنوان متوقع يتعذر تحديد موقعه الجغرافي/التحقق منه) يضيف `ADDRESS_MISMATCH_WITH_PROVIDED`، الخاضع لـ `poa_address_mismatch_action`. وتتم إعادة إرسال الصيغة المحددة جغرافياً في `expected_details_formatted_address` / `expected_details_parsed_address`. example: Av. Monseñor Tavella 1291, Salta, Argentina expected_country: type: string description: >- الدولة المراد التحقق منها مقابل المستند (رمز ISO 3166-1، مثل `ARG` أو `AR`). يضيف عدم التطابق مع دولة المستند `POA_COUNTRY_MISMATCH_WITH_PROVIDED`، وتتحكم به `poa_address_mismatch_action`. example: ARG expected_first_name: type: string description: >- الاسم الأول للتحقق منه ومطابقته مع `name_on_document` (مطابقة تقريبية، تأخذ في الاعتبار الترجمة الصوتية). الدرجة الأقل من حد المطابقة تضيف `NAME_MISMATCH_WITH_PROVIDED`، وتخضع لـ `poa_address_mismatch_action`. example: Sophia expected_last_name: type: string description: >- اسم العائلة للتحقق منه مقابل `name_on_document`، مدمجاً مع `expected_first_name` لاحتساب درجة التطابق. example: Martinez poa_languages_allowed: type: string description: >- قائمة مفصولة بفواصل بلغات المستندات المقبولة كرموز ISO 639-1 (مثل `en,es,fr`). عند إغفالها أو تركها فارغة، يتم قبول **جميع اللغات المدعومة البالغ عددها 51 لغة**. يضيف المستند المكتوب بلغة خارج القائمة `UNSUPPORTED_DOCUMENT_LANGUAGE` (تخضع لـ `poa_unsupported_language_action`)؛ ويعيد الرمز غير المعروف في القائمة `400` مع المجموعة الكاملة من الرموز المدعومة. example: en,es poa_document_age_months: type: string description: >- أزواج `key:value` مفصولة بفواصل تحدد الحد الأقصى لعمر المستند بالأشهر لكل نوع مستند — المفاتيح: `utility_bill`، `bank_statement`، `government_issued_document`، `other_poa_document`؛ القيم: من `1` إلى `120`، أو `-1` لغير محدود (بدون فحص العمر). القيم الافتراضية عند الإغفال: `utility_bill:3,bank_statement:3,government_issued_document:12,other_poa_document:12`. يُرفض المستند الأقدم من حده مع `POA_DOCUMENT_EXPIRED`. **تنبيه:** عند تقديم هذا الحقل، اذكر *كل* نوع تقبله — يتم التعامل مع الأنواع المُغفلة على أنها غير مقبولة (إشعار `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`) ويتم تخطي فحص العمر الخاص بها. example: utility_bill:3,bank_statement:6 poa_name_mismatch_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- مقبول ولكن **لا يتم تطبيقه حاليًا** — تتبع تحذيرات عدم تطابق الأسماء (`NAME_MISMATCH_WITH_PROVIDED`) الإجراء `poa_address_mismatch_action` بدلاً من ذلك. قم بتعيين `poa_address_mismatch_action` للتحكم في سلوك عدم تطابق كل من الاسم والعنوان. poa_document_issues_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- الإجراء المتبع عند وجود مشكلات في سلامة الملف — عملياً ينتج فقط `DOCUMENT_METADATA_MISMATCH` عن هذا الـ endpoint. poa_document_authenticity_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- الإجراء المتبع عند الاشتباه في تلاعب بالمستند (`SUSPECTED_DOCUMENT_MANIPULATION`) — كأن يتم تعديل ملف PDF بعد التوقيع الرقمي، أو معالجته بمحرر PDF معروف، أو إظهار تلاعب بنصوص متراكبة، أو وجود تواريخ EXIF غير متسقة. يحكم أيضاً `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` (حقل نصي أعيدت كتابته ولا يمكن للملف إثبات تغييره أو عدمه): `DECLINE` يرفضه أيضاً، و`NO_ACTION` يبقيه كتحذير. poa_unsupported_language_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- الإجراء المتخذ عندما تكون لغة المستند خارج `poa_languages_allowed` (`UNSUPPORTED_DOCUMENT_LANGUAGE`). poa_address_mismatch_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- الإجراء المتخذ عندما تتعارض التفاصيل المستخرجة مع حقول `expected_*`: تتبع جميع حالات `ADDRESS_MISMATCH_WITH_PROVIDED` و`NAME_MISMATCH_WITH_PROVIDED` و`POA_COUNTRY_MISMATCH_WITH_PROVIDED` هذا الإجراء. poa_issuer_not_identified_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- الإجراء المتبع عند تعذر تحديد الشركة/المؤسسة المصدرة على المستند (`ISSUER_NOT_IDENTIFIED`). save_api_request: type: boolean default: true description: >- عندما تكون القيمة `true` (الافتراضية)، يتم حفظ الاستدعاء كجلسة من نوع API — مرئية في Business Console، ويمكن استرجاعها عبر `GET /v3/session/{sessionId}/decision/` باستخدام `request_id` المُرجع، ويتم الإشعار بها عبر webhook لحدث `status.updated`، مع تخزين المستند المرفوع. عندما تكون القيمة `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 example: document: (binary JPEG/PNG/PDF of the utility bill or bank statement) expected_address: Av. Monseñor Tavella 1291, Salta, Argentina expected_country: ARG expected_first_name: Sophia expected_last_name: Martinez poa_languages_allowed: en,es save_api_request: true vendor_data: user-123 responses: '200': description: >- تمت معالجة المستند. تكون قيمة `poa.status` إما `Approved` أو `Declined`؛ وتُفصّل كل مشكلة تم اكتشافها في `poa.warnings`. المستند منتهي الصلاحية أو غير المتطابق أو المشبوه سيظل يُرجع `200` مع `status: "Declined"` — افحص نص الاستجابة، وليس فقط رمز HTTP. عندما تكون `save_api_request=true`، يكون `request_id` هو معرّف الجلسة المحفوظ. content: application/json: examples: Approved: summary: >- تمت قراءة فاتورة المرافق بوضوح، بدون فحوصات للتفاصيل المتوقعة value: request_id: 4b523a8d-ed32-45e4-8aa8-a89eda459d88 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2026-04-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. extra_fields: bank_account_number: null bank_iban: null bank_sort_code: null bank_routing_number: null bank_swift_bic: null bank_branch_name: null bank_branch_address: null document_phone_number: null additional_names: - LA EMBOTELLADORA DEL NORTE SA detected_codes: - type: QR_CODE page_number: 1 position: - - 820 - 1120 - - 1002 - 1120 - - 1002 - 1302 - - 820 - 1302 x: 820 'y': 1120 width: 182 height: 182 page_width: 1190 page_height: 1684 raw_payload: >- aHR0cHM6Ly9hZ3Vhc2RlbG5vcnRlLmNvbS9mYWN0dXJhLzk5ODgxMQ== parsed_payload: https://aguasdelnorte.com/factura/998811 - type: CODE_128 page_number: 1 position: - - 112 - 1480 - - 560 - 1480 - - 560 - 1540 - - 112 - 1540 x: 112 'y': 1480 width: 448 height: 60 page_width: 1190 page_height: 1684 raw_payload: MDA5OTg4MTEwMDA0Mg== parsed_payload: '0099881100042' status: Approved warnings: [] vendor_data: user-123 metadata: null created_at: '2026-06-12T02:29:02.439655+00:00' Declined - document too old: summary: تاريخ الإصدار أقدم من `poa_document_age_months` المسموح به value: request_id: f61681b8-9422-4378-ac3e-04c6a247fb45 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2021-02-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. extra_fields: bank_account_number: null bank_iban: null bank_sort_code: null bank_routing_number: null bank_swift_bic: null bank_branch_name: null bank_branch_address: null document_phone_number: null additional_names: - LA EMBOTELLADORA DEL NORTE SA status: Declined warnings: - risk: POA_DOCUMENT_EXPIRED feature: PROOF_OF_ADDRESS additional_data: expiration_reason: age_window max_age_months: 3 document_subtype: WATER_BILL document_type: UTILITY_BILL issue_date: '2021-02-10' log_type: error short_description: Document expired long_description: >- The submitted document is older than the maximum accepted age of 3 months from its issue date, which exceeds the acceptable time period for validity. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:23:02.165493+00:00' Declined - name mismatch: summary: >- `expected_first_name`/`expected_last_name` لا يتطابقان مع `name_on_document` value: request_id: 0a7f2f9c-58f1-4b8e-b1e3-2f6f9d4f7a21 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2021-02-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. extra_fields: bank_account_number: null bank_iban: null bank_sort_code: null bank_routing_number: null bank_swift_bic: null bank_branch_name: null bank_branch_address: null document_phone_number: null additional_names: - LA EMBOTELLADORA DEL NORTE SA status: Declined warnings: - risk: NAME_MISMATCH_WITH_PROVIDED feature: PROOF_OF_ADDRESS additional_data: null log_type: error short_description: Name mismatch with provided information long_description: >- The full name on the document does not match the name from the user's verified identity documents, or the full name sent by API. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:27:21.330172+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- معرّف الجلسة المحفوظة عندما تكون `save_api_request=true` (يمكن استخدامه مع `GET /v3/session/{sessionId}/decision/`)؛ وإلا فسيكون UUID ارتباط مؤقت. poa: type: object properties: status: type: string enum: - Approved - Declined description: >- `Approved` عندما لا يؤدي أي تحذير إلى الرفض؛ و`Declined` خلاف ذلك — توضح قائمة `warnings` السبب. issuing_state: type: string nullable: true description: >- الدولة التي صدر فيها المستند، كما تم استخراجها من المستند — عادةً ISO 3166-1 alpha-3 (مثل `ARG`). example: ARG document_type: type: string enum: - UTILITY_BILL - BANK_STATEMENT - GOVERNMENT_ISSUED_DOCUMENT - OTHER_POA_DOCUMENT - UNKNOWN description: >- فئة المستند المكتشفة. تعني `UNKNOWN` أنه تعذر تصنيف المستند كإثبات العنوان المقبول ويتم الرفض تلقائياً مع `INVALID_DOCUMENT_TYPE`. لا تكون null أبداً — ترجع إخفاقات التصنيف إلى `UNKNOWN`. document_subtype: type: string description: >- تصنيف أكثر دقة وتفصيلاً ضمن `document_type` — مثل `ELECTRICITY_BILL`، و`WATER_BILL`، و`GAS_BILL`، و`INTERNET_BILL`، و`PHONE_BILL` (فواتير المرافق)؛ و`ACCOUNT_STATEMENT`، و`CREDIT_CARD_STATEMENT` (كشوف الحسابات المصرفية)؛ و`TAX_ASSESSMENT`، و`RESIDENCY_CERTIFICATE` (المستندات الحكومية). وتكون `UNKNOWN` عندما يتعذر تحديد أي نوع فرعي. لا تكون null أبداً — إذ تعود حالات فشل التصنيف تلقائياً إلى `UNKNOWN`. example: WATER_BILL document_language: type: string nullable: true description: لغة المستند المكتشفة (ISO 639-1). example: es issuer: type: string nullable: true description: >- الشركة أو المؤسسة التي أصدرت المستند. تضيف القيمة `null`‏ `ISSUER_NOT_IDENTIFIED`. example: Aguas del Norte issue_date: type: string format: date nullable: true description: >- تاريخ إصدار المستند (`YYYY-MM-DD`). القيمة `null` عند تعذر استخراجه — مما يؤدي إلى الرفض مع `UNABLE_TO_EXTRACT_ISSUE_DATE` في هذا الـ endpoint. example: '2021-02-10' expiration_date: type: string format: date nullable: true description: >- تاريخ الانتهاء/الصلاحية الصريح المطبوع على المستند، إن وجد. مستقل عن فحص عمر المستند `poa_document_age_months`. poa_address: type: string nullable: true description: >- العنوان تماماً كما هو مطبوع على المستند. تؤدي القيمة `null` إلى الرفض التلقائي مع `MISSING_ADDRESS_INFORMATION`. poa_formatted_address: type: string nullable: true description: نسخة محددة جغرافياً وموحدة من `poa_address`. example: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: type: object nullable: true description: >- تفصيل مهيكل ومحدد جغرافياً لعنوان المستند. تكون قيمته `null` عندما يتعذر تحليل العنوان. properties: street_1: type: string nullable: true example: Avenida Monseñor Tavella 1291 street_2: type: string nullable: true city: type: string nullable: true example: Salta region: type: string nullable: true example: Salta country: type: string nullable: true description: رمز الدولة وفقاً لـ ISO 3166-1 alpha-2. example: AR postal_code: type: string nullable: true example: A4400 document_location: type: object nullable: true properties: latitude: type: number longitude: type: number description: الإحداثيات الجغرافية لعنوان المستند. expected_details_address: type: string nullable: true description: >- نسخة مطابقة من `expected_address` الذي أرسلته، أو `null`. expected_details_formatted_address: type: string nullable: true description: >- النسخة المحددة جغرافياً والموحدة من `expected_address`؛ وتكون `null` عند عدم تقديمها أو تعذر تحديدها جغرافياً. expected_details_parsed_address: type: object nullable: true additionalProperties: true description: >- نتيجة التحديد الجغرافي الكاملة لـ `expected_address` (الشارع/المدينة/المنطقة/الدولة/الرمز البريدي بالإضافة إلى مخرجات أداة التحديد الجغرافي الخام وعلامة `is_verified`). تكون `null` عند عدم تقديم `expected_address`. name_on_document: type: string nullable: true description: >- اسم حامل المستند الأساسي المستخرج من المستند؛ يُقارن مع `expected_first_name`/`expected_last_name` عند توفيرهما. تؤدي القيمة `null` إلى الرفض بالرمز `POA_NAME_NOT_DETECTED` في هذا الـ endpoint. example: OESTE EMBOTELLADORA S.A. extra_fields: type: object description: >- بيانات إضافية خاصة بالمستند. يتم ملء الحقول المصرفية لكشوف الحسابات المصرفية عند ظهورها مطبوعةً على المستند؛ وتكون `null` بخلاف ذلك. properties: bank_account_number: type: string nullable: true bank_iban: type: string nullable: true bank_sort_code: type: string nullable: true bank_routing_number: type: string nullable: true bank_swift_bic: type: string nullable: true bank_branch_name: type: string nullable: true bank_branch_address: type: string nullable: true document_phone_number: type: string nullable: true description: رقم هاتف التواصل المطبوع على المستند. additional_names: type: array items: type: string description: >- أسماء الحاملين الآخرين الموجودة في المستند (مثل أصحاب الحسابات المشتركة، أسماء الحسابات السابقة). warnings: type: array description: >- فارغ عند الموافقة السليمة. يوضح كل إدخال خطراً واحداً تم اكتشافه؛ تُعيّن الإدخالات ذات `log_type: "error"` الـ `status` إلى `Declined`. items: type: object properties: risk: type: string description: >- رمز مخاطر مقروء آلياً. مخاطر تؤدي دائماً إلى الرفض: `MISSING_ADDRESS_INFORMATION`، و`POA_DOCUMENT_EXPIRED`، و`INVALID_DOCUMENT_TYPE`، و`UNABLE_TO_VALIDATE_DOCUMENT_AGE`، بالإضافة إلى `UNABLE_TO_EXTRACT_ISSUE_DATE` و`POA_NAME_NOT_DETECTED` (محددة مسبقاً للرفض في هذا الـ endpoint). تحكمها خيارات الطلب: `NAME_MISMATCH_WITH_PROVIDED` / `ADDRESS_MISMATCH_WITH_PROVIDED` / `POA_COUNTRY_MISMATCH_WITH_PROVIDED` (`poa_address_mismatch_action`)، و`POOR_DOCUMENT_QUALITY` (لا يصدر عن هذا الـ endpoint أبداً) / `DOCUMENT_METADATA_MISMATCH` (`poa_document_issues_action`)، و`SUSPECTED_DOCUMENT_MANIPULATION` و`POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` (`poa_document_authenticity_action`)، و`UNSUPPORTED_DOCUMENT_LANGUAGE` (`poa_unsupported_language_action`)، و`ISSUER_NOT_IDENTIFIED` (`poa_issuer_not_identified_action`). مخاطر معلوماتية في هذا الـ endpoint: `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`، و`UNPARSABLE_OR_INVALID_ADDRESS`. example: POA_DOCUMENT_EXPIRED feature: type: string enum: - PROOF_OF_ADDRESS description: >- الميزة التي أصدرت التحذير. دائماً `PROOF_OF_ADDRESS` في هذا الـ endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- سياق إضافي لبعض المخاطر — على سبيل المثال، يتضمن `POA_DOCUMENT_EXPIRED` كلاً من `expiration_reason` (`printed_expiration` أو `age_window`)، و`document_type`، و`document_subtype`، و`issue_date`، بالإضافة إلى `expiration_date` في مسار `printed_expiration` أو `max_age_months` في مسار `age_window`؛ ويتضمن `SUSPECTED_DOCUMENT_MANIPULATION` كلاً من `reason` و`detection_method`؛ ويتضمن `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` كلاً من `reason`، و`detection_method` (`unproven_text_replacement`)، و`replaced_text`، و`manipulated_regions`، و`manipulated_blocks`. ويكون `null` لمعظم المخاطر. log_type: type: string enum: - error - information description: >- مستوى الخطورة. تحذيرات `error` تنقل `status` إلى `Declined`؛ وإدخالات `information` استشارية ولا تؤدي إلى الرفض بمفردها أبداً. (لا يُنتج هذا الـ endpoint تحذيرات من نوع `warning` — حيث تقبل خياراته `DECLINE` أو `NO_ACTION` فقط). short_description: type: string description: ملخص للمخاطر في سطر واحد مقروء للبشر. long_description: type: string description: تفسير سهل القراءة للمخاطر. detected_codes: type: array description: >- رموز QR والرموز الشريطية المكتشفة في كل صفحة تمت معالجتها من المستند. تكون فارغة عند عدم العثور على أي منها. رمز QR الذي تم تحديد مكانه ولكن تعذر فك تشفيره يحتوي على `parsed_payload: null`. items: $ref: '#/components/schemas/DocumentAIDetectedCode' vendor_data: type: string nullable: true description: نسخة مطابقة من `vendor_data` التي أرسلتها، أو `null`. metadata: type: object nullable: true additionalProperties: true description: نسخة مطابقة من كائن `metadata` الذي أرسلته، أو `null`. created_at: type: string format: date-time description: >- طابع زمني بتنسيق ISO 8601 (بالتوقيت العالمي المنسق UTC) لوقت إنشاء الاستجابة. '400': description: >- خطأ في التحقق أو المعالجة. تُرجع المشكلات على مستوى الحقول غلاف DRF القياسي (مصفوفة واحدة من الرسائل لكل حقل مخالف). وتُرجع مشكلات ملفات PDF المشفرة `{"detail": ...}`. والمستند الذي يتعذر على مسار الاستخراج معالجته يُرجع `{"error": ["Error extracting POA information"]}`. content: application/json: examples: Missing document: summary: '`document` غير مدرج في بيانات النموذج' value: document: - No file was submitted. Unsupported file extension: summary: امتداد الملف خارج tiff/jpg/jpeg/png/pdf/webp value: document: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, pdf, webp. File too large: summary: يتجاوز الملف المرفوع حد 15 ميجابايت value: document: - File size should not exceed 15 MB Encrypted PDF: summary: تم تحميل ملف PDF بدون كلمة المرور المطلوبة value: detail: >- The PDF is encrypted. Please upload a decrypted PDF or a photo instead. Wrong PDF password: summary: '`document_password` لا يفك تشفير ملف PDF' value: detail: >- The PDF password is incorrect. Please provide the correct password. Invalid language code: summary: '`poa_languages_allowed` يحتوي على رمز غير مدعوم' value: poa_languages_allowed: - >- Invalid language code: 'xx'. Must be one of the supported languages: ['ar', 'bn', 'hy', 'bg', 'bs', 'ca', 'cnr', 'sq', 'zh', 'hr', 'cs', 'da', 'nl', 'en', 'et', 'fi', 'fr', 'ka', 'kk', 'de', 'el', 'he', 'hi', 'hu', 'id', 'it', 'ja', 'ko', 'ky', 'lv', 'lt', 'mk', 'mn', 'ms', 'no', 'fa', 'pl', 'pt', 'ro', 'ru', 'sr', 'sk', 'sl', 'so', 'es', 'sv', 'th', 'tr', 'uk', 'uz', 'vi']. Invalid document age value: summary: قيمة `poa_document_age_months` خارج النطاق 1–120 / -1 value: poa_document_age_months: - >- Invalid integer value for 'utility_bill': '999'. Must be -1 (unlimited) or a positive integer between 1 and 120. Extraction failure: summary: تعذر معالجة المستند بواسطة مسار الاستخراج value: error: - Error extracting POA information '403': description: >- تم رفض الإذن. يُرجع عند فقدان الرأس `x-api-key`، وأيضاً عندما لا يتمكن رصيد المؤسسة الطالبة من تغطية الاستدعاء؛ ويُرجع المفتاح الخاطئ أو الملغى أو منتهي الصلاحية `401`. يؤدي المفتاح المفقود إلى إرجاع `403` مع `{"detail": ...}`؛ ويؤدي المفتاح الخاطئ أو الملغى أو منتهي الصلاحية إلى إرجاع `401`. يُرجع نقص الرصيد `403` مع `{"error": ...}` قبل إجراء أي معالجة للمستند. content: application/json: examples: Missing or invalid API key: summary: لا يوجد رأس `x-api-key`، أو أن المفتاح غير صالح/ملغى value: detail: You do not have permission to perform this action. Not enough credits: summary: رصيد المؤسسة لا يمكنه تغطية تكلفة الاستدعاء value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- تم تجاوز حد المعدل. تشترك نقاط endpoint الخاصة بـ POST/PATCH/DELETE في ميزانية قدرها 300 طلب كتابة في الدقيقة لكل مفتاح API (إنشاء المعاملات واستيعاب الأحداث لهما ميزانية منفصلة تبلغ 600). تتضمن الاستجابة رؤوس `X-RateLimit-Limit` و`X-RateLimit-Remaining` و`X-RateLimit-Reset` و`Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: أكثر من 300 طلب كتابة في الدقيقة الحالية value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '503': $ref: '#/components/responses/DocumentProcessingBusy' security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/poa/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'document=@./utility-bill.pdf' \ -F 'expected_address=Av. Monseñor Tavella 1291, Salta, Argentina' \ -F 'expected_country=ARG' \ -F 'expected_first_name=Sophia' \ -F 'expected_last_name=Martinez' \ -F 'poa_languages_allowed=en,es' \ -F 'vendor_data=user-123' \ --max-time 45 - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.proof_of_address.verify( document=open("document.pdf", "rb"), expected_address="Av. Monseñor Tavella 1291, Salta, Argentina", expected_country="ARG", expected_first_name="Sophia", expected_last_name="Martinez", poa_languages_allowed="en,es", save_api_request=True, vendor_data="user-123", ) 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.proofOfAddress.verify({ document: await fileFromPath("document.pdf"), expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina", expected_country: "ARG", expected_first_name: "Sophia", expected_last_name: "Martinez", poa_languages_allowed: "en,es", save_api_request: true, vendor_data: "user-123", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.ProofOfAddress.Verify(ctx, didit.ProofOfAddressVerifyParams{\n\tDocument: didit.FileFromPath(\"document.pdf\"),\n\tExpectedAddress: didit.String(\"Av. Monseñor Tavella 1291, Salta, Argentina\"),\n\tExpectedCountry: didit.String(\"ARG\"),\n\tExpectedFirstName: didit.String(\"Sophia\"),\n\tExpectedLastName: didit.String(\"Martinez\"),\n\tPOALanguagesAllowed: didit.String(\"en,es\"),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\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.ProofOfAddressVerifyParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.proofOfAddress().verify(ProofOfAddressVerifyParams.builder() .document(Path.of("document.pdf")) .expectedAddress("Av. Monseñor Tavella 1291, Salta, Argentina") .expectedCountry("ARG") .expectedFirstName("Sophia") .expectedLastName("Martinez") .poaLanguagesAllowed("en,es") .saveApiRequest(true) .vendorData("user-123") .build()); System.out.println(result); - lang: php label: PHP source: |- proofOfAddress->verify([ 'document' => File::fromPath('document.pdf'), 'expected_address' => 'Av. Monseñor Tavella 1291, Salta, Argentina', 'expected_country' => 'ARG', 'expected_first_name' => 'Sophia', 'expected_last_name' => 'Martinez', 'poa_languages_allowed' => 'en,es', 'save_api_request' => true, 'vendor_data' => 'user-123', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.proof_of_address.verify( document: Pathname("document.pdf"), expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina", expected_country: "ARG", expected_first_name: "Sophia", expected_last_name: "Martinez", poa_languages_allowed: "en,es", save_api_request: true, vendor_data: "user-123" ) 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.ProofOfAddress.VerifyAsync(new ProofOfAddressVerifyParams { Document = FileUpload.FromPath("document.pdf"), ExpectedAddress = "Av. Monseñor Tavella 1291, Salta, Argentina", ExpectedCountry = "ARG", ExpectedFirstName = "Sophia", ExpectedLastName = "Martinez", PoaLanguagesAllowed = "en,es", SaveApiRequest = true, VendorData = "user-123", }); 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.