> ## 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. # تحذيرات إثبات العنوان ورموز الأخطاء > رموز تحذيرات إثبات العنوان من Didit: عدم تطابق الاسم، المستندات منتهية الصلاحية وغيرها، مع ضبط الرفض التلقائي لكل تحذير. ## نظرة عامة يُصدر التحقق من إثبات العنوان (POA) تحذيرات في `poa_verifications[].warnings[]` لكل مشكلة تتعلق بالجودة أو الأصالة أو المطابقة يتم اكتشافها أثناء الاستخراج والتحليل الجنائي. كل تحذير هو [كائن تحذير](https://docs.didit.me/ar/reference/data-models.md#كائن-التحذير) مع ضبط `feature` على `"PROOF_OF_ADDRESS"`. تفرض مجموعة محدودة من المخاطر دائمًا حالة `Declined`؛ بينما تتبع بقية المخاطر إجراءً مخصصًا لكل خطر (`DECLINE` / `REVIEW` / `NO_ACTION`) يتم تكوينه في سير العمل لديك. تم التحقق من كل خطر أدناه مقابل مسار اتخاذ القرار الفعلي؛ وتمت إعادة إنتاج سلاسل الوصف الدقيقة، القصيرة والطويلة، حرفيًا في الجداول. > [!NOTE] > > يتسبب استخراج POA في زمن استجابة يتراوح بين **5 و15 ثانية** لكل مستند. لا تُكتب التحذيرات إلا عند اكتمال خطوة سير العمل؛ لا تقم بالاستقصاء بمعدل أسرع من مرة كل 5 ثوانٍ. ## مساران في بيئة الإنتاج يتم إصدار تحذيرات POA عبر مسارين مختلفين، وتختلف مجموعة المخاطر بينهما: * **جلسات سير العمل** (خطوة POA داخل جلسة التحقق) — يقوم endpoint الخاص بالرفع أولاً بتشغيل تحقق مانع مع حلقة إعادة محاولة (انظر [سلوك إعادة المحاولة](#سلوك-إعادة-المحاولة-جلسات-سير-العمل))، ثم يتم حساب التحذيرات المخزنة النهائية بواسطة `check_poa_risks` بالإضافة إلى التحقق من الاسم عبر مستندات متعددة. * **واجهة API مستقلة** (`POST /v3/poa/`) — تأتي التحذيرات من `check_poa_risks` فقط. لا توجد حلقة إعادة محاولة، ولا يوجد سياق هوية تم التحقق منها، ويوجد مستند واحد فقط، لذلك لا يتم إصدار `NAME_MISMATCH_ID_VERIFICATION` و`POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` و`POA_MAX_ATTEMPTS_EXCEEDED` و`FUTURE_ISSUE_DATE` **أبدًا** بواسطة واجهة API المستقلة. يتم تجاهل أخطاء التحقق السابقة للاستخراج في هذا المسار. تم تحديد `POOR_DOCUMENT_QUALITY` في تعداد المخاطر وحجزه في تعيين الإجراءات، ولكن **لا يوجد مسار برمجي في مسار معالجة POA يُنتجه** — فهو لا يظهر أبدًا في `warnings[]` على أي من المسارين. لا تقم بإنشاء تفرعات برمجية بالاعتماد عليه. ## تحذيرات الرفض التلقائي (تفرض دائمًا حالة `Declined`) توجد هذه المخاطر ضمن `AUTO_DECLINE_RISKS`؛ وعند تسجيلها، تكون حالة POA هي `Declined` بغض النظر عن التكوين، ويكون `log_type` دائمًا `error`. | الخطر | السبب | المعالجة الموصى بها | | - | - | - | | `MISSING_ADDRESS_INFORMATION` | تعذر استخراج أي عنوان من المستند. | اطلب من المستخدم إعادة إرسال مستند يوضح عنوانه بوضوح. | | `POA_DOCUMENT_EXPIRED` | انتهت صلاحية المستند عبر أحد مسارين: تجاوز **تاريخ انتهاء الصلاحية المطبوع** عليه، أو أنه **أقدم من الحد الأقصى للعمر المُكوَّن** لنوعه. الإعدادات الافتراضية: **3 أشهر** لـ `UTILITY_BILL` و`BANK_STATEMENT`، و**12 شهرًا** لـ `GOVERNMENT_ISSUED_DOCUMENT` و`OTHER_POA_DOCUMENT` (يُحسب الشهر على أنه 30 يومًا؛ وتعطيل الفحص باستخدام `-1`). يحمل `additional_data` دائمًا `expiration_reason` (`printed_expiration` أو `age_window`)، و`document_type`، و`document_subtype`، و`issue_date`؛ يضيف مسار `printed_expiration` قيمة `expiration_date`، بينما يضيف مسار `age_window` قيمة `max_age_months`. | اطلب من المستخدم مستندًا صالحًا أو أحدث، أو ارفع قيمة `age_months` لهذا النوع. | | `INVALID_DOCUMENT_TYPE` | تعذر تصنيف المستند إلى أي نوع POA مدعوم (يعود `document_type` إلى `UNKNOWN`). | اطلب من المستخدم إعادة الإرسال؛ وتأكد من أن الملف ليس تالفًا. | | `UNABLE_TO_VALIDATE_DOCUMENT_AGE` | فشل التحقق من عمر المستند نفسه (خطأ أثناء حساب انتهاء الصلاحية من تاريخ الإصدار). | اطلب من المستخدم مستندًا يحتوي على تاريخ إصدار مقروء بوضوح. | تم إدراج `FUTURE_ISSUE_DATE` أيضًا ضمن `AUTO_DECLINE_RISKS`، ولكن لديه مُنتِج وحيد في التحقق السابق للاستخراج (تاريخ إصدار يزيد عن 7 أيام في المستقبل) وتُغذي أخطاؤه **حلقة إعادة المحاولة في سير العمل** فقط — حيث يظهر كخطأ رفع يمنع المتابعة هناك، ولا يتم إنتاجه أبدًا بواسطة واجهة API المستقلة، ولا يُكتب في `warnings[]`. انظر [سلوك إعادة المحاولة](#سلوك-إعادة-المحاولة-جلسات-سير-العمل). ## التحذيرات القابلة للتهيئة يتبع كل تحذير من هذه التحذيرات أحد مفاتيح الإجراء في عقدة POA الخاصة بسير العمل (`DECLINE` / `REVIEW` / `NO_ACTION`). يطابق `log_type` الخاص بالتحذير الإجراء المُعدّ: `error` للرفض، و`warning` للمراجعة، و`information` لعدم اتخاذ إجراء. | الخطر | السبب | مفتاح الإجراء | الافتراضي | | - | - | - | - | | `NAME_MISMATCH_WITH_PROVIDED` | تحصل نسبة تطابق الاسم في المستند على درجة أقل من `poa_name_match_score_threshold` (الافتراضي 86) مقارنةً بالاسم المُدخل عند إنشاء الجلسة (`expected_details`). | `poa_name_or_address_mismatch_action` | مراجعة | | `NAME_MISMATCH_ID_VERIFICATION` | تحصل نسبة تطابق الاسم في المستند على درجة أقل من الحد مقارنةً بمستند الهوية الذي جرى التحقق منه. `additional_data`: `{ poa_name, kyc_name, match_score }`. تنطبق على جلسات سير العمل فقط. | `poa_name_or_address_mismatch_action` | مراجعة | | `ADDRESS_MISMATCH_WITH_PROVIDED` | يختلف العنوان المستخرج عن العنوان المُرسَل عبر API، أو تعذّر التحقق من أن أيٍّ من العنوانين عنوان سكني. | `poa_name_or_address_mismatch_action` | مراجعة | | `POA_COUNTRY_MISMATCH_WITH_PROVIDED` | لا تتطابق دولة المستند مع الدولة المُرسَلة عبر API (بعد توحيدها بصيغة ISO-3). `additional_data`: `{ expected_country, extracted_country }`. | `poa_name_or_address_mismatch_action` | مراجعة | | `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` | يحمل مستندان أو أكثر من مستندات إثبات العنوان في الجلسة نفسها أسماءً مختلفة. يتضمن `additional_data` معرّفَي العقدتين والاسمين ودرجة التطابق. تنطبق على جلسات سير العمل فقط. | `poa_name_or_address_mismatch_action` | مراجعة | | `DOCUMENT_METADATA_MISMATCH` | الملف فارغ (`file_size` يساوي 0)، أو أن تواريخ EXIF فيه غير صالحة. | `poa_document_issues_action` | مراجعة | | `SUSPECTED_DOCUMENT_MANIPULATION` | أظهر التحليل الجنائي دليلاً على التلاعب: تعديل بعد التوقيع الرقمي (`is_tampered`)، أو التلاعب بالنص المتراكب (مع مستطيلات `additional_data.manipulated_regions`)، أو محرّر PDF معروف، أو تواريخ EXIF غير متسقة، أو إعادة تصدير مشبوهة. يُسمّي `additional_data.detection_method` الفحص الذي أطلق التحذير. | `poa_document_authenticity_action` | **رفض** | | `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` | حُذف حقل نصي ثم أُعيدت كتابته بخط آخر، ولا يحتوي الملف على دليل يثبت ما إذا تغيّر محتواه، فالمحررات الإلكترونية تعيد كتابة النص غير المعدَّل أيضاً. لا يُطلق هذا التحذير وحده أبداً `SUSPECTED_DOCUMENT_MANIPULATION`؛ فإذا أطلقته إشارة أخرى على المستند نفسه، فالإجراء الأشد من الاثنين هو الذي يحكم. يكون `additional_data.detection_method` هو `unproven_text_replacement`، مع `replaced_text` و`manipulated_regions`. ويُطلق هذا التحذير أيضاً عند تعذّر فحص الملف بالكامل، لأن الجزء غير المفحوص قد يحتوي على مثل هذا الحقل: عندها يكون `detection_method` هو `analysis_incomplete`، مع `replaced_text` و`manipulated_regions` فارغين، إلا إذا عُثر على حقل في الجزء الذي فُحص. | `poa_document_unproven_text_replacement_action` | مراجعة | | `UNSUPPORTED_DOCUMENT_LANGUAGE` | لغة المستند غير مدرجة في `poa_languages_allowed`. | `poa_unsupported_language_action` | **رفض** | | `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | نوع المستند المكتشف غير مفعّل في `poa_documents_allowed` لدولة المستند، أو أن نوعه الفرعي معطّل صراحةً. | `poa_unsupported_document_type_action` | **رفض** | | `ISSUER_NOT_IDENTIFIED` | تعذّر التعرّف على الجهة المُصدِرة من المستند. | `poa_issuer_not_identified_action` | مراجعة | | `UNABLE_TO_EXTRACT_ISSUE_DATE` | تعذّر العثور على تاريخ إصدار صالح في المستند. | `poa_issue_date_not_detected_action` | مراجعة | | `POA_NAME_NOT_DETECTED` | لم يُكتشف أي اسم في المستند. | `poa_issue_date_not_detected_action` (المفتاح المشترك) | مراجعة | | `UNPARSABLE_OR_INVALID_ADDRESS` | استُخرج عنوان، لكن تعذّر تحليله وتحديد موقعه الجغرافي ليصبح عنواناً سكنياً صالحاً. | `poa_unparsable_or_invalid_address_action` | مراجعة | | `POA_MAX_ATTEMPTS_EXCEEDED` | استنفد المستخدم عدد `poa_max_retry_attempts` (الافتراضي 2) في حلقة إعادة المحاولة في سير العمل. `additional_data`: `{ attempts }`. تنطبق على جلسات سير العمل فقط. | `poa_max_attempts_exceeded_action` | **رفض** | > [!NOTE] > > يوجد **إجراء مشترك واحد** لجميع حالات عدم تطابق الأسماء والعناوين: يغطي `poa_name_or_address_mismatch_action` الخطرين المتعلقين بالاسم، والخطرين المتعلقين بالعنوان، وفحص الاسم عبر المستندات، ولا يمكنك ضبط سلوك عدم تطابق الاسم وسلوك عدم تطابق العنوان بشكل منفصل. في واجهة API المستقلة، تخضع المجموعة نفسها لخيار الطلب `poa_address_mismatch_action`، أما الخيار `poa_name_mismatch_action` فهو مقبول، لكن لا تتم قراءته أبداً. ## اختلافات API المستقل (`POST /v3/poa/`) يبني الـ endpoint المستقل نفس ربط المخاطر بالإجراءات ولكن مع خيارات على مستوى الطلب تقبل `DECLINE` أو `NO_ACTION` فقط (وجميعها مضبوطة افتراضياً على `DECLINE`): * `UNABLE_TO_EXTRACT_ISSUE_DATE` و`POA_NAME_NOT_DETECTED` **محددان برمجياً على الرفض** في هذا الـ endpoint. * `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` و`UNPARSABLE_OR_INVALID_ADDRESS` **معلوماتيان** هنا — حيث يتم ضبط إجراءاتهما افتراضياً على عدم اتخاذ إجراء ولا يمكن تكوينهما لكل طلب. * لا يتم إصدار `FUTURE_ISSUE_DATE` و`POOR_DOCUMENT_QUALITY` و`NAME_MISMATCH_ID_VERIFICATION` و`POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` و`POA_MAX_ATTEMPTS_EXCEEDED` أبداً — فالمستند ذو التاريخ المستقبلي **لا** يتم رفضه تلقائياً في هذا الـ endpoint. راجع [مرجع API لـ POST /v3/poa/](https://docs.didit.me/ar/standalone-apis/proof-of-address.md) للاطلاع على خيارات الطلب. ## سلوك إعادة المحاولة (جلسات سير العمل) في جلسة التحقق، تُجري خطوة رفع مستند POA عملية تحقق مانعة قبل قبول المستند. وعندما تكتشف خطأً مانعاً — `INVALID_DOCUMENT_TYPE` أو `UNABLE_TO_EXTRACT_ISSUE_DATE` أو `FUTURE_ISSUE_DATE` أو `POA_NAME_NOT_DETECTED` أو `MISSING_ADDRESS_INFORMATION` أو `POA_COUNTRY_MISMATCH_WITH_PROVIDED` أو `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` أو `UNSUPPORTED_DOCUMENT_LANGUAGE` أو `POA_DOCUMENT_EXPIRED` — يتم رفض عملية الرفع مع كود الحالة `400` ورمز المخاطر كرسالة، ويمكن للمستخدم إعادة المحاولة بمستند أفضل. بالنسبة للرمز `POA_DOCUMENT_EXPIRED`، يتضمن جسم استجابة `400` أيضاً `expiration_reason` (`printed_expiration` أو `age_window`) حتى تتمكن واجهة المستخدم لديك من إظهار السبب الدقيق؛ وفي مسار `age_window`، يتضمن بالإضافة إلى ذلك `max_age_months`. وفي مسار `printed_expiration`، يتم حذف `max_age_months` عمداً لأن المستند رُفض بسبب تاريخ الانتهاء المطبوع عليه بدلاً من نافذة العمر. بمجرد أن يستنفد المستخدم محاولات `poa_max_retry_attempts` (الافتراضي 2، قابل للتكوين بين 2 و5)، يتم قبول الإرسال على أي حال: يُعاد احتساب التحذيرات المخزنة من المستند المحفوظ، ويُضاف `POA_MAX_ATTEMPTS_EXCEEDED`، وتُحدد الحالة بناءً على مجموعة المخاطر الكاملة. ولهذا السبب يمكن لـ `FUTURE_ISSUE_DATE` أن يحجب عملية الرفع ومع ذلك لا يظهر أبداً في `warnings[]`. ## الإعدادات القابلة للتكوين تتيح عقدة POA في سير العمل خيارات الضبط التالية (المطابقة لحقول `VerificationSettings`): | الإعداد | يتحكم في | القيمة الافتراضية | | - | - | - | | `poa_name_or_address_mismatch_action` | `NAME_MISMATCH_WITH_PROVIDED`, `NAME_MISMATCH_ID_VERIFICATION`, `ADDRESS_MISMATCH_WITH_PROVIDED`, `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` | مراجعة | | `poa_document_issues_action` | `DOCUMENT_METADATA_MISMATCH` | مراجعة | | `poa_document_authenticity_action` | `SUSPECTED_DOCUMENT_MANIPULATION` | رفض | | `poa_document_unproven_text_replacement_action` | `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` | مراجعة (سير العمل الذي لا يُجري مراجعة أبداً يستخدم إعداد `poa_document_authenticity_action` الخاص به عندما يكون رفض، وإلا لا إجراء؛ وتتبع واجهة API المستقلة قيمة `poa_document_authenticity_action` الخاصة بالطلب) | | `poa_unsupported_language_action` | `UNSUPPORTED_DOCUMENT_LANGUAGE` | رفض | | `poa_unsupported_document_type_action` | `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | رفض | | `poa_issuer_not_identified_action` | `ISSUER_NOT_IDENTIFIED` | مراجعة | | `poa_issue_date_not_detected_action` | `UNABLE_TO_EXTRACT_ISSUE_DATE`, `POA_NAME_NOT_DETECTED` | مراجعة | | `poa_unparsable_or_invalid_address_action` | `UNPARSABLE_OR_INVALID_ADDRESS` | مراجعة | | `poa_max_attempts_exceeded_action` | `POA_MAX_ATTEMPTS_EXCEEDED` | رفض | | `poa_documents_allowed` | أنواع المستندات المقبولة لكل دولة، ويحتوي كل منها على `enabled` و`age_months` (`-1` = غير محدود)؛ وإعدادات مخصصة لكل نوع فرعي عبر `document_subtypes_config`. | فواتير الخدمات وكشوف الحسابات البنكية: 3 أشهر؛ المستندات الصادرة عن جهات حكومية وغيرها: 12 شهراً | | `poa_languages_allowed` | لغات المستندات المقبولة. | جميع اللغات المدعومة | | `poa_name_match_score_threshold` | الحد الأدنى لدرجة مطابقة الاسم (0–100) قبل إطلاق مخاطر `NAME_MISMATCH*`. | 86 | | `poa_max_retry_attempts` | محاولات الرفع قبل أن تتوقف حلقة إعادة المحاولة (2–5). | 2 | ## منطق مطابقة الأسماء تتسامح مطابقة أسماء POA مع الاختلافات الشائعة: * **الأسماء الوسطى والأحرف الأولى**: تتم مطابقتها بمرونة (يُسمح بوجودها أو غيابها). * **الأسماء المرشحة** — يتم احتساب درجة لكل اسم يُكتشف في المستند (`name_on_document` بالإضافة إلى `additional_names`)، ويتم الاحتفاظ بالمرشح الحاصل على أعلى درجة. * **حد التطابق** — القيمة الافتراضية لـ `poa_name_match_score_threshold` هي **86**؛ وتؤدي أي درجة أقل منها إلى إطلاق تحذير `NAME_MISMATCH*` ذي الصلة. تظهر الدرجات الرقمية في التقرير كـ `name_match_score_expected_details` و`name_match_score_id_verification` (0–100). وتُعد قيم الدرجات مفيدة لإجراء مراجعة تفصيلية حتى في حالة عدم إطلاق أي تحذير. ## أمثلة ### التلاعب عبر التراكب (الرفض افتراضياً) ```json theme={null} { "warnings": [ { "feature": "PROOF_OF_ADDRESS", "risk": "SUSPECTED_DOCUMENT_MANIPULATION", "additional_data": { "reason": "Overlay-text manipulation detected: same base font embedded with multiple subset prefixes on 1 page(s).", "detection_method": "overlay_text_manipulation", "signals": ["duplicate_font_subset", "glyph_fragmentation"], "duplicate_font_subsets": [{ "page": 1, "base_font": "Helvetica" }], "fragmented_fonts": [], "manipulated_regions": [ { "page": 1, "x": 102.4, "y": 318.1, "width": 187.0, "height": 18.0, "page_width": 595, "page_height": 842 } ] }, "log_type": "error", "short_description": "Suspected document manipulation", "long_description": "The system detected signs of potential document manipulation or editing.", "node_id": "feature_poa_1" } ] } ``` ### مستند منتهي الصلاحية + عنوان مفقود (رفض تلقائي) ```json theme={null} { "warnings": [ { "feature": "PROOF_OF_ADDRESS", "risk": "POA_DOCUMENT_EXPIRED", "additional_data": { "expiration_reason": "age_window", "max_age_months": 3, "document_subtype": "ELECTRICITY_BILL", "document_type": "UTILITY_BILL", "issue_date": "2025-11-02" }, "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.", "node_id": "feature_poa_1" }, { "feature": "PROOF_OF_ADDRESS", "risk": "MISSING_ADDRESS_INFORMATION", "additional_data": null, "log_type": "error", "short_description": "Missing address information", "long_description": "The document does not contain complete or clear address information that can be extracted.", "node_id": "feature_poa_1" } ] } ``` ### عدم تطابق الاسم (المراجعة افتراضياً) ```json theme={null} { "warnings": [ { "feature": "PROOF_OF_ADDRESS", "risk": "NAME_MISMATCH_ID_VERIFICATION", "additional_data": { "poa_name": "JOHN B SMYTH", "kyc_name": "John A. Smith", "match_score": 60 }, "log_type": "warning", "short_description": "Name mismatch with ID verification", "long_description": "The full name on the document does not match the name from the user's verified identity documents.", "node_id": "feature_poa_1" } ] } ``` ## مواضيع ذات صلة * [تقرير إثبات العنوان](https://docs.didit.me/ar/core-technology/proof-of-address/report-proof-of-address.md) — شكل الاستجابة الكامل، والتحليل الجنائي للتلاعب عبر التراكب، ودلالات الحالة * [نظرة عامة على إثبات العنوان](https://docs.didit.me/ar/core-technology/proof-of-address/overview.md) — أنواع المستندات المقبولة * [نماذج البيانات — إثبات العنوان](https://docs.didit.me/ar/reference/data-models.md#إثبات-العنوان) — المخطط النموذجي وكائن التحذير * [webhook](https://docs.didit.me/ar/integration/webhooks.md) — يحمل الحدث `status.updated` تحذيرات POA ### أنواع التحذيرات This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.