بناء منطق التحقق من الصحة

يصف هذا المستند عملية لإنشاء نظام للتحقق من العنوان للتعامل مع مجموعة متنوعة من الردود من واجهة برمجة تطبيقات التحقق من العناوين. ويتناول هذا الدليل كيفية إنشاء منطقك لاستخدام الردّ بشكل صحيح، والتحقيق في الإشارات الأخرى من واجهة برمجة التطبيقات، ووقت طلب المزيد من المعلومات من العملاء وكيفية طلبها.

بشكل عام، تحدِّد استجابة واجهة برمجة التطبيقات الطرق التالية التي يجب أن يعالج بها نظامك العنوان:

• handyman إصلاح: العنوان منخفض الجودة. يجب طلب مزيد من المعلومات.
• edit تأكيد: العنوان بجودة عالية، ولكن هناك تغييرات عن العنوان الذي أدخلته. يمكنك طلب تأكيد.
• check قبول: العنوان عالي الجودة. يمكنك قبول العنوان المقدَّم.

الغرض الرئيسي

يساعدك هذا المستند في تعديل نظامك لتحليل استجابة واجهة برمجة التطبيقات على أفضل نحو وتحديد الإجراءات التالية التي يجب اتّخاذها بشأن العناوين المقدَّمة. يوضح الكود الزائف التالي التدفق المحتمل.

if (the API response indicates significant problems in the address)
    FIX - prompt the user to fix the address
else if (the API response indicates less significant problems in the address)
    CONFIRM - confirm with the user that the address is correct
else
    ACCEPT - continue with the address returned by the API.

يعتمد المنطق الدقيق على حالتك. اطّلِع على إرشادات التنفيذ لمزيد من التفاصيل. يمكنك أيضًا استخدام تنفيذ هذا المنطق المفتوح المصدر، الذي يتوفّر في مكتبة المكوّنات الموسّعة.

نظرة عامة على سير العمل

يلخّص الجدول التالي إجراءَين لنظامك:

1. سير العمل المطلوب استخدامه استنادًا إلى سلوك الإصلاح والتأكيد والقبول.
2. الإشارة الأولى للتحقق من الردّ. تأتي الإشارات الموضّحة هنا من السمة verdict وهي ليست هي الإشارات الوحيدة التي يجب التحقق منها، ولكنها توفّر مؤشرًا أوليًا لجودة العنوان. يتوافق كل نوع سلوك مع قسم في هذا المستند يصف إشارات إضافية قد تحتاج إلى التحقيق فيها أيضًا.

إرشادات التنفيذ

عند تصميم طريقة استجابة نظامك للإشارات الواردة من واجهة برمجة تطبيقات التحقق من صحة العناوين، يمكن أن تساعدك الاقتراحات التالية في إنشاء نموذج استجابة أكثر فعالية. ومع ذلك، هذه مجرد اقتراحات، لذا يجب أن يكون تنفيذها ملائمًا لنموذج نشاطك التجاري.

تصحيح عنوان

يجب تصحيح عنوان عندما تشير النتائج بوضوح إلى أنّه لا يمكن تسليم الرسائل إليه. يمكن أن يطلب نظامك من العميل بعد ذلك تقديم المعلومات اللازمة، وبعد ذلك يمكنك إعادة إصدار سير العمل للحصول على عنوان قابل للتسليم.

إصلاح الإشارات

توفّر Address Validation API عددًا من الإشارات لإعلامك بما إذا كان يجب تصحيح عنوان.

1. دقّة التحقّق والمكوّنات غير المتوفّرة

توفّر هاتان الإشارتان أفضل مؤشر على أنّ العنوان يتضمن مشكلة:

• عندما يكون الحقل validationGranularity هو OTHER، يجب أن يتحقّق نظامك من إشارات مكوّنات العنوان لمعرفة المزيد من المعلومات حول مكان حدوث الخطأ وكيفية إصلاحه.
• عندما يعرض عنصرaddress الذي تمّت معالجته بعد ذلك حقل missingComponentTypes، من المفترض أن يبحث نظامك عن هذا المكوّن. تؤدي المكونات غير المتوفّرة أيضًا إلى جعل العنوان غير مكتمل وغير قابل للتسليم.

2. الإشارات الأخرى

توفّر واجهة برمجة التطبيقات Address Validation API أيضًا إشارات أخرى للمساعدة في تشخيص مشاكل معيّنة:

3- إشارات العناوين في الولايات المتحدة

توفّر حقول معيّنة لا تنطبق إلا على عناوين الولايات المتحدة إشارة مفيدة بأنّه لا يمكن إرسال الرسائل إلى العنوان ويجب إصلاحه. بالنسبة إلى العنوان الذي يتطلّب إصلاحًا، من المفترض أن يظهر لك ما يلي:

لمعرفة التفاصيل حول dpvConfirmation، يُرجى الاطّلاع على معالجة عناوين الولايات المتحدة.

أمثلة على إصلاح العناوين

تأكيد عنوان

يمكنك تأكيد عنوان عندما يشير الحكم إلى أنّ واجهة برمجة التطبيقات Address Validation API قد استنتجت أو أجرت تغييرات على مكوّنات العنوان من أجل إنشاء عنوان صالح. في هذه الحالات، يكون لديك عنوان يمكن تسليمه، ولكنك تفضّل الحصول على ثقة أكبر بأنّ العنوان الناتج هو العنوان الذي يريده العميل.

لتقديم الإرشادات الصحيحة للعميل، سيحدّد منطقك المكوّنات التي تم وضع علامة عليها من خلال الخدمة لتحديد الإجراء أو العلامة التي طبّقتها واجهة برمجة التطبيقات على المكوّن، مثل inferred أو replaced أو spellCorrected. اطّلِع على AddressComponent في المرجع.

تأكيد الإشارات

توفّر Address Validation API عددًا من الإشارات لإعلامك بما إذا كان يجب تأكيد العنوان.

1. دقّة التحقّق من الصحة

يُعدّ الحصول على validationGranularity بقيمة ROUTE أو أعلى مقبولًا، ولكن يقدّم كلاً من PREMISE أو SUBPREMISE إشارة أقوى لإمكانية التسليم.

2. الإشارات الأخرى

عند اتخاذ قرار تأكيد إدخال العنوان مع العميل، يقدّم البيان أيضًا ما يلي لتحديد المكونات التي يجب التحقيق فيها:

3- إشارات العناوين في الولايات المتحدة

تشير بعض الحقول التي تنطبق فقط على عناوين الولايات المتحدة إلى أنّه يجب تأكيد التفاصيل مع العميل. ينطبق أي مما يلي:

أمثلة على تأكيد العنوان

قبول عنوان

يتم قبول عنوان عندما يقدّم التقرير درجة عالية من الثقة بأنّه يمكن تسليم العنوان ويمكن استخدامه بدون مزيد من تفاعل العميل في عملية المعالجة اللاحقة.

قبول الإشارات

توفّر Address Validation API عددًا من الإشارات لإعلامك بما إذا كان يجب تأكيد العنوان.

1. دقّة التحقّق من الصحة

يُعدّ الحصول على validationGranularity بقيمة PREMISE أو أعلى مقبولًا، ولكن في بعض الحالات، يشير ROUTE إلى عنوان يمكن تسليم الرسائل إليه.

2. الإشارات الأخرى

يجب أيضًا أن يتضمن قرار الحصول على عنوان عالي الجودة ما يلي:

• ما مِن بيانات تم استبدالها وهي في هذه الحالة hasReplacedComponents: FALSE.
• ما مِن مكونات تم استنتاجها. في هذه الحالة، hasInferredComponents: FALSE.

3- إشارات العناوين في الولايات المتحدة

تشير حقول معيّنة لا تنطبق إلا على عناوين الولايات المتحدة إلى عنوان بجودة عالية يمكن تسليم الطلبات إليه. للحصول على عنوان مقبول في الولايات المتحدة، من المفترض أن يظهر ما يلي:

قبول أمثلة العناوين