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

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

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

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

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

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

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 من USPS	عندما يكون uspsData.dpvConfirmation إما N أو أو فارغًا، قد تكون هناك مشكلة في العنوان. لا يتوفّر هذا الحقل إلا للعناوين في الولايات المتحدة. لمزيد من التفاصيل حول uspsData.dpvConfirmation، يُرجى الاطّلاع على معالجة عناوين الولايات المتحدة.

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

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

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

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

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

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

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

يمكنك تأكيد عنوان عندما يشير الحكم إلى أنّ 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 من USPS	عندما يكون uspsData.dpvConfirmation هو Y، يعني ذلك أنّه تمت مطابقة العنوان مع عنوان في قاعدة بيانات USPS. لا يتوفّر هذا الحقل إلا للعناوين في الولايات المتحدة. لمزيد من التفاصيل حول uspsData.dpvConfirmation، يُرجى الاطّلاع على معالجة عناوين الولايات المتحدة.

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