במסמך הזה מתואר תהליך לבניית מערכת לבדיקת כתובות, שמטפלת במגוון תגובות מ-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 מציינת כתובת באיכות מצוינת.
|
||
הדרכה בנושא הטמעה
ההמלצות הבאות יעזרו לכם לבנות מודל תגובה יעיל יותר, שיעזור לכם לתכנן איך המערכת שלכם תגיב לאותות של אימות כתובות. עם זאת, אלה רק המלצות, ולכן חשוב לזכור שההטמעה צריכה להתאים למודל העסקי שלכם.
| הנחיות | פרטים | |
|---|---|---|
| רמת הסיכון |
כשמחליטים אם להציג בקשה לתיקון או לקבל את הכתובת כמו שהיא, צריך לקחת בחשבון את רמת הסבילות במצב שלכם. |
ה-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
או יותר הוא קביל, אבל דירוג של PREMISE או SUBPREMISE
מספק אות חזק יותר לגבי יכולת המסירה.ROUTE
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
לפרטים על
|
|---|