במסמך הזה מתואר תהליך ליצירת מערכת לבדיקת כתובות, שמטפלת במגוון תגובות מ-Address Validation API. המאמר כולל הסברים על בניית הלוגיקה לשימוש נכון בתשובה, על בדיקת אותות אחרים מה-API ועל המקרים שבהם כדאי לבקש מהלקוחות מידע נוסף ואיך לעשות זאת.
באופן כללי, התגובה של ה-API קובעת את הדרכים הבאות שבהן המערכת צריכה לטפל בכתובת:
- תיקון – הכתובת באיכות נמוכה. כדאי לבקש מידע נוסף.
- אישור – הכתובת היא באיכות גבוהה, אבל יש בה שינויים לעומת הכתובת שהוזנה. יכול להיות שתתבקשו לאשר את הפעולה.
- אישור – הכתובת באיכות גבוהה. אפשר לאשר את הכתובת שסופקה.
המטרה העיקרית
המסמך הזה יעזור לכם לשנות את המערכת כדי לנתח בצורה הטובה ביותר את תגובת ה-API ולקבוע את הפעולות הבאות שצריך לבצע עם הכתובות שסופקו. בפסאודו-קוד הבא מוצג תהליך אפשרי.
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.
הלוגיקה המדויקת תלויה במצב שלכם. מידע נוסף זמין בהנחיות להטמעה. אפשר גם להשתמש בהטמעה שלנו של הלוגיקה הזו בקוד פתוח, שנמצאת בספריית הרכיבים המורחבת.
סקירה כללית של תהליך העבודה
בטבלה הבאה מפורטות שתי פעולות שמתבצעות במערכת:
- תהליך העבודה לשימוש בהתאם להתנהגות של תיקון, אישור וקבלה.
- האותות הראשונים שצריך לבדוק בתגובה. האותות
שמתוארים כאן מגיעים מהנכס
verdictוהם לא האותות היחידים שצריך לבדוק, אבל הם מספקים אינדיקציה ראשונית לאיכות הכתובת. כל סוג התנהגות תואם לקטע במסמך הזה שמתאר אותות נוספים שכדאי לבדוק.
| התנהגות המערכת | |||
|---|---|---|---|
| תיקון הכתובת |
התשובה מ-
|
||
| אישור הכתובת |
התשובה מ-
|
||
| מאשרים את הכתובת |
התשובה של Address Validation API מציינת כתובת באיכות מצוינת.
|
||
הדרכה בנושא הטמעה
כשמתכננים איך המערכת תגיב לאותות של אימות כתובות, ההמלצות הבאות יכולות לעזור לכם לבנות מודל תגובה יעיל יותר. עם זאת, אלה רק המלצות, ולכן חשוב לזכור שההטמעה צריכה להתאים למודל העסקי שלכם.
| הנחיות | פרטים | |
|---|---|---|
| רמת הסיכון |
כשמחליטים אם להציג בקשה לתיקון או לקבל את הכתובת כמו שהיא, צריך לקחת בחשבון את רמת הסבילות במצב שלכם. |
ה-Address Validation API מחזיר מגוון אותות שאפשר לשלב עם רמת הסיכון כדי לייעל את תהליך האימות. לדוגמה, אם לכתובת יש מספר רחוב לא מאומת, עדיין אפשר לאשר אותה. לעומת זאת, אם הפעילות העסקית שלכם דורשת דיוק רב יותר בכתובת, אתם יכולים להציג למשתמש הנחיה. דוגמה שיכולה להיכלל בכל אחת מהקטגוריות האלה מופיעה במאמר קבלת כתובת – דוגמאות בקטע מספר בית לא מאושר מחוץ לארה"ב. |
| אישור כתובות |
מומלץ לאפשר למערכת לקבל את הערך המקורי אם הלקוח לא מגיב להנחיות. |
במקרים כאלה, יכול להיות שהלקוח הזין כתובת שלא נמצאת במערכת, למשל כתובת של בניין חדש. |
תיקון כתובת
תיקון כתובת כשברור מהתוצאות שהאימייל לא יכול להימסר לכתובת. לאחר מכן, המערכת יכולה לבקש מהלקוח לספק את המידע הנדרש, ואז להפעיל מחדש את תהליך העבודה כדי לקבל כתובת למשלוח.
תיקון האותות
ה-Address Validation API מספק מספר אותות שמאפשרים לכם לדעת אם צריך לתקן כתובת.
1. גרנולריות של אימות ורכיבים חסרים
שני האותות האלה מספקים את האינדיקציה הטובה ביותר לכתובת בעייתית:
- בכל פעם שהשדה
validationGranularityהואOTHER, המערכת שלכם צריכה לבדוק את האותות של רכיבי הכתובת כדי לקבל מידע נוסף על המקום שבו השגיאה התרחשה ועל הדרך לתקן אותה. - בכל פעם שאובייקט
addressשעבר עיבוד חוזר מחזיר שדהmissingComponentTypes, המערכת שלכם צריכה לבדוק את הרכיב הזה. רכיבים חסרים גם הופכים את הכתובת ללא מלאה וללא אפשרות למשלוח.
2. אותות אחרים
בנוסף, Address Validation API מספק אותות אחרים שיעזרו לכם לאבחן בעיות ספציפיות:
| רכיבים חשודים | אם ערך ה-enum של רמת האישור של רכיב הוא UNCOMFIRMED_AND_SUSPICIOUS, סביר להניח שהרכיב שגוי.
|
|---|---|
| רכיב לא פתור | unresolvedToken הוא חלק מהקלט שלא מזוהה כחלק תקין של כתובת. |
3. אותות של כתובות בארה"ב
שדות מסוימים שרלוונטיים רק לכתובות בארה"ב מספקים אות שימושי לכך שהכתובת לא ניתנת למשלוח וצריך לתקן אותה. אם יש כתובת שצריך לתקן, יופיעו הפרטים הבאים:
dpvConfirmation
|
N, D או ריק.
|
|---|
פרטים על dpvConfirmation מופיעים במאמר בנושא טיפול בכתובות בארצות הברית.
אישור כתובת
כתובת מאומתת היא כתובת שרכיביה שונו או שוערכו על ידי Address Validation API כדי ליצור כתובת מאומתת. במקרים כאלה, יש לכם כתובת שאפשר לשלוח אליה, אבל אתם רוצים להיות בטוחים יותר שהכתובת שמתקבלת היא הכתובת שהלקוח התכוון אליה.
כדי לספק ללקוח הנחיה נכונה, הלוגיקה שלכם תזהה את הרכיבים שסומנו על ידי השירות כדי לקבוע איזו פעולה או דגל ה-API החיל על הרכיב, כמו inferred, replaced או spellCorrected.
פרטים נוספים מופיעים ב-AddressComponent במאמר בנושא הפניה.
אותות אישור
ממשק Address Validation API מספק מספר אותות שמאפשרים לדעת אם צריך לאשר כתובת.
1. רמת הפירוט של האימות
דירוג validationGranularity של ROUTE ומעלה הוא קביל, אבל דירוג של PREMISE או SUBPREMISE
מספק אות חזק יותר של יכולת מסירה.
2. אותות אחרים
כשמחליטים לאשר את הזנת הכתובת עם הלקוח, פסק הדין מספק גם את הפרטים הבאים כדי לקבוע אילו רכיבים צריך לבדוק:
| נתונים שנלמדו | כשערך השדה
hasInferredComponents הוא true, אתם יודעים שה-API מילא מידע שנאסף מרכיבי כתובת אחרים.
|
|---|---|
| הנתונים שהוחלפו | אם הערך בשדה
hasReplacedComponents הוא true, ה-API החליף את הנתונים שהוזנו בנתונים שלדעתו הופכים את הכתובת לתקינה.
|
3. אותות של כתובות בארה"ב
בשדות מסוימים שרלוונטיים רק לכתובות בארה"ב מצוין שהלוגיקה שלכם צריכה לאשר את הפרטים מול הלקוח. אחת מהאפשרויות הבאות רלוונטית:
dpvConfirmation
|
S
פרטים על |
|---|---|
| תגובה עם כתובת | הוא מכיל את השדה missingComponentTypes עם הערך subpremise.
|
אישור כתובת
אתם מאשרים כתובת כשההחלטה מספקת רמת ודאות גבוהה לגבי האפשרות למסור את הכתובת, ואפשר להשתמש בה בלי אינטראקציה נוספת עם הלקוח בתהליך בהמשך.
קבלת אותות
ממשק Address Validation API מספק מספר אותות שמאפשרים לדעת אם צריך לאשר כתובת.
1. רמת הפירוט של האימות
דירוג של validationGranularity או יותר הוא קביל, אבל במקרים מסוימים, גם דירוג של ROUTE מציין כתובת שאפשר לשלוח אליה.PREMISE
2. אותות אחרים
בנוסף, פסיקה לגבי כתובת באיכות גבוהה צריכה לכלול גם את הפרטים הבאים:
- אין נתונים שהוחלפו. במקרה הזה,
hasReplacedComponents: FALSE. - לא זוהו רכיבים משוערים. במקרה הזה,
hasInferredComponents: FALSE.
3. אותות של כתובות בארה"ב
שדות מסוימים שרלוונטיים רק לכתובות בארה"ב מציינים כתובת באיכות גבוהה שאפשר לשלוח אליה. אם הכתובת בארה"ב תקינה, אמורים להופיע הפרטים הבאים:
dpvConfirmation
|
Y
לפרטים על
|
|---|