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

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

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

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

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

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

if (verdict.possibleNextAction == FIX)
    Prompt the user to fix the address.
else if (verdict.possibleNextAction == CONFIRM_ADD_SUBPREMISES)
    Prompt the user to add a unit number.
else if (verdict.possibleNextAction == CONFIRM)
    Confirm with the user that the address is correct.
else
    Continue with the address returned by the API.

يعتمد المنطق الدقيق على حالتك، لذا يُرجى الاطّلاع على تخصيص منطق التحقّق لمزيد من التفاصيل.

أمثلة على سير العمل

يلخّص الجدول أدناه أمثلة على سير العمل التي يمكنك تنفيذها لتوجيه العميل استنادًا إلى الردّ الذي تتلقّاه من واجهة برمجة التطبيقات.

سلوك النظام
تصحيح العنوان	يشير الردّ الذي يتضمّن verdict إلى احتمال وجود مشاكل كبيرة في العنوان. على سبيل المثال، verdict.possibleNextAction هو FIX. ننصحك بطلب المزيد من المعلومات من العميل. سير العمل تحقَّق من مكوّنات العنوان إذا لزم الأمر. مطالبة العميل بحلّ مشاكل العنوان طلب التحقّق من صحة العنوان المعدَّل (اختياري) أرسِل طلبًا إلى نقطة نهاية الملاحظات الخاصة بواجهة برمجة التطبيقات. اطّلِع على التعامل مع العناوين المعدَّلة. المتابعة باستخدام العنوان
إضافة أماكن فرعية	يشير الردّ من verdict إلى أنّ العنوان قد يكون ناقصًا لعنوان فرعي. على سبيل المثال، verdict.possibleNextAction هي CONFIRM_ADD_SUBPREMISES. ننصحك بأن تطلب من العميل إضافة رقم وحدة. سير العمل مطالبة العميل بإضافة رقم وحدة طلب التحقّق من صحة العنوان المعدَّل (اختياري) أرسِل طلبًا إلى نقطة نهاية الملاحظات الخاصة بواجهة برمجة التطبيقات. اطّلِع على التعامل مع العناوين المعدَّلة. المتابعة باستخدام العنوان
تأكيد العنوان	يشير الردّ من verdict إلى أنّه قد تكون هناك مشاكل بسيطة في العنوان. على سبيل المثال، verdict.possibleNextAction هي CONFIRM. ننصحك بأن تطلب من العميل مراجعة العنوان. سير العمل الأخطاء التي يجب تصحيحها: تحقَّق من مكوّنات العنوان إذا لزم الأمر. طلب التحقّق من صحة العنوان المعدَّل (اختياري) أرسِل طلبًا إلى نقطة نهاية الملاحظات الخاصة بواجهة برمجة التطبيقات. اطّلِع على التعامل مع العناوين المعدَّلة. المتابعة باستخدام العنوان لا حاجة إلى إجراء تصحيحات: (اختياري) أرسِل طلبًا إلى نقطة نهاية الملاحظات الخاصة بواجهة برمجة التطبيقات. اطّلِع على التعامل مع العناوين المعدَّلة. المتابعة باستخدام العنوان
قبول العنوان	يشير الردّ من verdict إلى أنّه قد لا تكون هناك مشاكل في العنوان. على سبيل المثال، verdict.possibleNextAction هي ACCEPT. ننصحك بمواصلة عملية إدخال العنوان كما تفعل عادةً مع مستوى المخاطر الذي حدّدته. سير العمل المتابعة باستخدام العنوان الذي تم إرجاعه

ملاحظة: عند تكرار الطلبات إلى Address Validation API للعنوان نفسه، يمكنك إجراء طلب إلى provideValidationFeedback للإشارة إلى النتيجة. اطّلِع على التعامل مع العناوين المعدَّلة.

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

تخصيص منطق التحقّق

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

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

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

درجة تحمّل المخاطر

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

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

مثال على مسار دفع لا يتضمّن مخاطر

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

if (verdict.possibleNextAction == FIX or verdict.validationGranularity
== OTHER or verdict.validationGranularity == ROUTE)
  Prompt customer to fix their address.
else if (verdict.possibleNextAction == CONFIRM_ADD_SUBPREMISES)
  Prompt customer to add a unit number.
else if (verdict.possibleNextAction == CONFIRM or verdict.validationGranularity
== PREMISE_PROXIMITY or verdict.hasSpellCorrectedComponents or
verdict.hasReplacedComponents or verdict.hasInferredComponents)
  Prompt customer to confirm their address.
else
  Proceed with the returned address.

مثال على مسار دفع سلس

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

if (verdict.possibleNextAction == FIX)
  Prompt customer to fix their address.
else if (verdict.hasReplacedComponents)
  Prompt customer to confirm their address.
else
  Proceed with the returned address.

إشارات FIX

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

يمكن استخدام الحقول التالية من استجابة Address Validation API بالإضافة إلى verdict.possibleNextAction لتحديد ما إذا كان العنوان يتضمّن مشاكل كبيرة، وما هي هذه المشاكل.

دقة التحقّق من الصحة	عندما تكون قيمة تعداد دقة التحقّق من صحة العنوان هي OTHER، من المحتمل أن يكون العنوان غير صحيح.
المكوّنات غير المتوفّرة	عندما لا يكون الحقل address.missingComponentTypes فارغًا، من المحتمل أن يكون العنوان يفتقر إلى معلومات أساسية.
المكوّنات المشبوهة	عندما تكون قيمة التعداد الخاص بمستوى التأكيد لأحد المكوّنات هي UNCONFIRMED_AND_SUSPICIOUS، من المحتمل أن يكون المكوّن غير صحيح.
المكوّنات التي لم يتم حلّها	unresolvedToken هو جزء من الإدخال لا يتم التعرّف عليه كجزء صالح من العنوان.
تأكيد DPV من خدمة البريد الأمريكية	عندما تكون قيمة uspsData.dpvConfirmation هي N أو فارغة، قد تكون هناك مشكلة في العنوان. يتوفّر هذا الحقل لعناوين الولايات المتحدة فقط. لمزيد من التفاصيل حول uspsData.dpvConfirmation، راجِع التعامل مع العناوين في الولايات المتحدة.

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

إشارات CONFIRM_ADD_SUBPREMISES (عناوين الولايات المتحدة فقط)

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

يمكن استخدام الحقول التالية في ردّ واجهة برمجة التطبيقات Address Validation API بالإضافة إلى verdict.possibleNextAction لتحديد ما إذا كان العنوان من المحتمل أنّه لا يتضمّن مبنى فرعيًا.

Missing subpremise component	عندما يحتوي الحقل address.missingComponentTypes على القيمة subpremise، يشير ذلك إلى أنّ رقم الوحدة غير متوفّر في العنوان. ملاحظة: إذا كان الحقل يحتوي على أنواع غير subpremise، سيتم تصنيف الإجراء ضمن فئة FIX. يمكنك الاطّلاع على القائمة الكاملة لأنواع المكوّنات في مستندات الترميز الجغرافي.
تأكيد DPV من خدمة البريد الأمريكية	عندما تكون قيمة uspsData.dpvConfirmation هي S، يعني ذلك أنّه تمّت مطابقة الرقم الأساسي للعنوان مع عنوان في قاعدة بيانات USPS. ومع ذلك، كان من المتوقّع أن يحتوي العنوان على رقم ثانوي أيضًا. يتوفّر هذا الحقل لعناوين الولايات المتحدة فقط. لمزيد من التفاصيل حول uspsData.dpvConfirmation، راجِع التعامل مع العناوين في الولايات المتحدة.

أمثلة على إضافة عناوين الأماكن الفرعية

إشارات CONFIRM

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

يمكن استخدام الحقول التالية من استجابة Address Validation API بالإضافة إلى verdict.possibleNextAction لتحديد ما إذا كان العنوان يتضمّن مشاكل بسيطة، وما هي هذه المشاكل.

دقة التحقّق من الصحة	عندما تكون قيمة validationGranularity الخاصة بالعنوان هي ROUTE أو PREMISE_PROXIMITY، قد يكون العنوان غير صحيح.
البيانات المستنتَجة	عندما تكون قيمة الحقل hasInferredComponents هي true، تعرف أنّ واجهة برمجة التطبيقات قد ملأت المعلومات التي جمعتها من مكوّنات عناوين أخرى.
البيانات المستبدَلة	عندما تكون قيمة الحقل hasReplacedComponents هي true، استبدلت واجهة برمجة التطبيقات البيانات المُدخَلة بالبيانات التي اعتبرتها ضرورية لجعل العنوان صالحًا.
تصحيحات الأخطاء الإملائية	عندما تكون قيمة الحقل hasSpellCorrectedComponents هي true، صحّحت واجهة برمجة التطبيقات الإملاء لبعض المكوّنات التي تمّت كتابتها بشكل خاطئ.

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

إشارات ACCEPT

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

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

يمكن استخدام الحقول التالية في ردّ واجهة برمجة التطبيقات Address Validation API بالإضافة إلى verdict.possibleNextAction لتحديد ما إذا كان العنوان بجودة مقبولة.

دقة التحقّق من الصحة	غالبًا ما يكون validationGranularity بقيمة PREMISE مقبولاً، ولكن قد تشير القيمة ROUTE إلى عنوان صالح للتسليم.
ما مِن بيانات مستنتَجة	عندما تكون قيمة الحقل hasInferredComponents هي false، تعرف أنّه لم يتم استنتاج أي مكوّنات في الناتج.
ما مِن بيانات تم استبدالها	عندما يكون الحقل hasReplacedComponents هو false، تعرف أنّه لم يتم استبدال أي بيانات إدخال.
لا توجد تصحيحات إملائية	عندما تكون قيمة الحقل hasSpellCorrectedComponents هي false، تعرف أنّه لم يتم إجراء أي تصحيحات إملائية.
تأكيد DPV من خدمة البريد الأمريكية	عندما تكون قيمة uspsData.dpvConfirmation هي Y، يعني ذلك أنّه تم الربط بين العنوان وعنوان آخر في قاعدة بيانات USPS. يتوفّر هذا الحقل لعناوين الولايات المتحدة فقط. لمزيد من التفاصيل حول uspsData.dpvConfirmation، راجِع التعامل مع العناوين في الولايات المتحدة.

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