במסמך הזה מתוארים תהליך לפיתוח מערכת לבדיקת כתובות, כדי לטפל במגוון תגובות מ-Address Validation API. במאמר הזה מוסבר איך לפרש את התשובה מה-API כדי לקבוע מתי ואיך לבקש מהלקוחות מידע נוסף.
באופן כללי, התשובה מה-API קובעת את הדרכים הבאות שבהן המערכת צריכה לטפל בכתובת:
-
תיקון – יכול להיות שהכתובת מכילה בעיות משמעותיות.
כדאי לבקש מהלקוח מידע נוסף. -
הוספת מתחם משנה – יכול להיות שהכתובת חסרה מתחם משנה.
כדאי לבקש מהלקוח להוסיף מספר יחידה. -
אישור – יכול להיות שהכתובת מכילה בעיות קלות.
מומלץ לבקש מהלקוח לאשר שהכתובת נכונה. -
אישור – יכול להיות שהכתובת לא מכילה בעיות.
מומלץ להשתמש בכתובת ללא הנחיה נוספת, על אחריותך בלבד.
מטרת המפתח
המסמך הזה יעזור לכם לשנות את המערכת כדי לנתח בצורה הטובה ביותר את התשובה מה-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.
הלוגיקה המדויקת תלויה בנסיבות שלכם – פרטים נוספים זמינים במאמר התאמה אישית של לוגיקת האימות.
תהליכי עבודה אפשריים
בטבלה הבאה מפורט סיכום של תהליכי עבודה אפשריים שאפשר להטמיע כדי להציג ללקוח בקשה בהתאם לתשובה מה-API.
| התנהגות המערכת | ||
|---|---|---|
| תיקון הכתובת |
התשובה מ-
|
|
| הוספת מתחמים משניים |
התשובה מ-
|
|
| אישור הכתובת |
התשובה מ-
|
|
| אישור הכתובת |
התשובה מ-
|
|
התאמה אישית של לוגיק האימות
אפשר להשתמש בתוצאות מהשדה verdict.possibleNextAction כדי לקבוע איך המערכת תמשיך לטפל בתשובת ה-API, אבל כדאי גם לחשוב על פיתוח לוגיקה בהתאמה אישית, למשל כדי לטפל בצרכים ספציפיים לעסק.
המטרה של הקטע הזה היא להמחיש איך אפשר לפתח לוגיקה מותאמת אישית משלכם לצורך פרשנות התשובה מה-API, כדי לקבוע אם אתם רוצים להציג בקשה ללקוח ואיך אתם רוצים לעשות זאת. בקטע הזה נסביר על רמות הסיכון ועל אותות נוספים של תגובות API שאפשר להביא בחשבון בהתאמה האישית.
עם זאת, גם אם אתם מסתמכים רק על הערך של 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 כדי לקבוע אם יש בכתובת בעיות משמעותיות, ואילו בעיות הן.
| רמת הפירוט של האימות | אם הערך של enum של רמת הפירוט של האימות של כתובת הוא OTHER, סביר להניח שהכתובת שגויה.
|
|---|---|
| רכיבים חסרים | אם השדה address.missingComponentTypes לא ריק, סביר להניח שפרטי הכתובת חסרים פרטים חיוניים.
|
| רכיבים חשודים | אם הערך של enum של רמת האישור של רכיב הוא UNCONFIRMED_AND_SUSPICIOUS, סביר להניח שהרכיב שגוי.
|
| רכיבים שלא טופלו | unresolvedToken הוא חלק מהקלט שלא מזוהה כחלק תקין של כתובת. |
| USPS DPV Confirmation | אם הערך של uspsData.dpvConfirmation הוא N או ריק, יכול להיות שיש בעיה בכתובת. השדה הזה זמין רק לכתובות בארה"ב. למידע נוסף על uspsData.dpvConfirmation, ראו טיפול בכתובות בארה"ב.
|
אותות CONFIRM_ADD_SUBPREMISES (כתובות בארה"ב בלבד)
אם התשובה של Address Validation API מציינת שייתכן שכתובת הלקוח חסרה מבנה משנה, צריך לבקש מהלקוח לבדוק את הכתובת ולשקול להוסיף מספר יחידה. במקרים כאלה, סביר להניח שהכתובת של הבניין תקינה, אבל אתם רוצים להיות בטוחים שהכתובת שהתקבלה היא הכתובת שהלקוח התכוון אליה.
אפשר להשתמש בשדות הבאים בתשובה של Address Validation API בנוסף לשדה verdict.possibleNextAction כדי לקבוע אם סביר להניח שכתובת מסוימת חסרה לה נכס משנה.
Missing subpremise component
|
אם השדה address.missingComponentTypes מכיל את הערך subpremise, המשמעות היא שמספר הדירה חסר בכתובת.
|
|---|---|
| USPS DPV Confirmation | כשהערך של uspsData.dpvConfirmation הוא S, המשמעות היא שהמספר הראשי של הכתובת תואם לכתובת במסד הנתונים של USPS. עם זאת, הכתובת אמורה להכיל גם מספר משני. השדה הזה זמין רק לכתובות בארה"ב. למידע נוסף על uspsData.dpvConfirmation, ראו טיפול בכתובות בארה"ב.
|
דוגמאות להוספת כתובת של נכס משנה
אותות CONFIRM
מאשרים כתובת כשהתוצאה מציינת ש-Address Validation API הסיק או ביצע שינויים ברכיבי הכתובת כדי ליצור כתובת מאומתת. במקרים כאלה, יש לכם כתובת שאפשר לשלוח אליה, אבל אתם רוצים לוודא שהכתובת שהתקבלה היא הכתובת שבה הלקוח התכוון לשלוח את ההזמנה.
אפשר להשתמש בשדות הבאים בתגובה של Address Validation API בנוסף ל-verdict.possibleNextAction כדי לקבוע אם יש בכתובת בעיות קלות, ואילו בעיות הן.
| רמת הפירוט של האימות | אם הערך של validationGranularity בכתובת הוא ROUTE או PREMISE_PROXIMITY, יכול להיות שהכתובת שגויה.
|
|---|---|
| נתונים משוערים | כשהערך בשדה hasInferredComponents הוא true, זה אומר שה-API מילא מידע שצבר מרכיבי כתובת אחרים.
|
| הנתונים שהוחלפו | כשהשדה hasReplacedComponents הוא true, ה-API מחליף את הנתונים שהוזנו בנתונים שהוא סבר שהם יהפכו את הכתובת לתקינה.
|
| תיקוני איות | כשהשדה hasSpellCorrectedComponents הוא true, המשמעות היא שה-API תיקן את האיות של רכיבים מסוימים עם שגיאות איות.
|
אותות ACCEPT
אפשר לאשר כתובת אם התשובה מה-API של Address Validation API מספקת רמת ביטחון גבוהה שהכתובת ניתנת למשלוח ואפשר להשתמש בה בלי אינטראקציה נוספת עם הלקוח בתהליך במורד הזרם.
אפשר להשתמש בשדות הבאים בתגובה של Address Validation API בנוסף ל-verdict.possibleNextAction כדי לקבוע אם איכות הכתובת היא טובה.
| רמת הפירוט של האימות | לעיתים קרובות הערך validationGranularity של PREMISE מקובל, אבל גם הערך ROUTE יכול להצביע על כתובת שאפשר לשלוח אליה.
|
|---|---|
| ללא נתונים משוערים | כשהשדה hasInferredComponents הוא false, משמעות הדבר היא שלא בוצעה השערה לגבי רכיבים בפלט.
|
| אין נתונים שהוחלפו | כשהערך בשדה hasReplacedComponents הוא false, משמעות הדבר שאין נתוני קלט שהוחלפו.
|
| ללא תיקוני איות | אם השדה hasSpellCorrectedComponents הוא false, משמעות הדבר היא שלא בוצעו תיקוני איות.
|
| USPS DPV Confirmation | כשהערך של uspsData.dpvConfirmation הוא Y, המשמעות היא שהכתובת תואמה לכתובת במסד הנתונים של USPS. השדה הזה זמין רק לכתובות בארה"ב. למידע נוסף על uspsData.dpvConfirmation, ראו טיפול בכתובות בארה"ב.
|