نظرة عامة
يُصدر التحقق من إثبات العنوان (POA) تحذيرات فيpoa_verifications[].warnings[] لكل مشكلة تتعلق بالجودة أو الأصالة أو المطابقة يتم اكتشافها أثناء الاستخراج والتحليل الجنائي. كل تحذير هو كائن تحذير مع ضبط feature على "PROOF_OF_ADDRESS". تفرض مجموعة محدودة من المخاطر دائمًا حالة Declined؛ بينما تتبع بقية المخاطر إجراءً مخصصًا لكل خطر (DECLINE / REVIEW / NO_ACTION) يتم تكوينه في سير العمل لديك.
تم التحقق من كل خطر أدناه مقابل مسار اتخاذ القرار الفعلي؛ وتمت إعادة إنتاج سلاسل الوصف الدقيقة، القصيرة والطويلة، حرفيًا في الجداول.
يتسبب استخراج 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.
تم إدراج
FUTURE_ISSUE_DATE أيضًا ضمن AUTO_DECLINE_RISKS، ولكن لديه مُنتِج وحيد في التحقق السابق للاستخراج (تاريخ إصدار يزيد عن 7 أيام في المستقبل) وتُغذي أخطاؤه حلقة إعادة المحاولة في سير العمل فقط — حيث يظهر كخطأ رفع يمنع المتابعة هناك، ولا يتم إنتاجه أبدًا بواسطة واجهة API المستقلة، ولا يُكتب في warnings[]. انظر سلوك إعادة المحاولة.
التحذيرات القابلة للتهيئة
يتبع كل تحذير من هذه التحذيرات أحد مفاتيح الإجراء في عقدة POA الخاصة بسير العمل (DECLINE / REVIEW / NO_ACTION). يطابق log_type الخاص بالتحذير الإجراء المُعدّ: error للرفض، وwarning للمراجعة، وinformation لعدم اتخاذ إجراء.
يوجد إجراء مشترك واحد لجميع حالات عدم تطابق الأسماء والعناوين: يغطي
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.
سلوك إعادة المحاولة (جلسات سير العمل)
في جلسة التحقق، تُجري خطوة رفع مستند 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_on_documentبالإضافة إلىadditional_names)، ويتم الاحتفاظ بالمرشح الحاصل على أعلى درجة. - حد التطابق — القيمة الافتراضية لـ
poa_name_match_score_thresholdهي 86؛ وتؤدي أي درجة أقل منها إلى إطلاق تحذيرNAME_MISMATCH*ذي الصلة.
name_match_score_expected_details وname_match_score_id_verification (0–100). وتُعد قيم الدرجات مفيدة لإجراء مراجعة تفصيلية حتى في حالة عدم إطلاق أي تحذير.
أمثلة
التلاعب عبر التراكب (الرفض افتراضياً)
مستند منتهي الصلاحية + عنوان مفقود (رفض تلقائي)
عدم تطابق الاسم (المراجعة افتراضياً)
مواضيع ذات صلة
- تقرير إثبات العنوان — شكل الاستجابة الكامل، والتحليل الجنائي للتلاعب عبر التراكب، ودلالات الحالة
- نظرة عامة على إثبات العنوان — أنواع المستندات المقبولة
- نماذج البيانات — إثبات العنوان — المخطط النموذجي وكائن التحذير
- webhook — يحمل الحدث
status.updatedتحذيرات POA