במסמך הזה מתואר תהליך לבניית מערכת לבדיקת כתובות, כדי לטפל במגוון תגובות מ-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.
הלוגיקה המדויקת תלויה במצב שלכם. פרטים נוספים זמינים בהנחיות להטמעה. אפשר גם להשתמש בהטמעה בקוד פתוח של הלוגיקה הזו, שנמצאת ב-Extended Component Library.
סקירה כללית של תהליך העבודה
בטבלה הבאה מפורטות שתי פעולות למערכת:
- תהליך העבודה שבו צריך להשתמש בהתאם להתנהגות של התיקון, האישור והקבלה.
- האותות הראשונים שצריך לבדוק בתגובה. האותות שמתוארים כאן מגיעים מהנכס
verdictוהם לא האותות היחידים שצריך לבדוק, אבל הם מספקים אינדיקציה ראשונית לאיכות הכתובת. כל סוג התנהגות תואם לקטע במסמך הזה, שמתאר אותות נוספים שאולי תצטרכו לחקור.
| התנהגות המערכת | |||
|---|---|---|---|
| תיקון הכתובת |
התשובה מה-
|
||
| אישור הכתובת |
התגובה מה-
|
||
| אישור הכתובת |
התגובה של Address Validation API מציינת שהכתובת באיכות מצוינת.
|
||
הדרכה בנושא הטמעה
כשאתם מתכננים את האופן שבו המערכת מגיבה לאותות של אימות כתובת, ההמלצות הבאות יכולות לעזור לכם לבנות מודל תגובה יעיל יותר. עם זאת, אלה רק המלצות, וחשוב לזכור שההטמעה צריכה להתאים למודל העסקי שלכם.
| הנחיות | פרטים | |
|---|---|---|
| רמת הסיכון |
כשאתם מאזנים בין בקשה לתיקון לבין קבלת הכתובת כפי שהוזנה, קחו בחשבון את רמת הסבילות למצב שלכם. |
Address Validation API מחזיר מגוון אותות שאפשר לשלב עם רמת הסיכון כדי לשפר את תהליך האימות. לדוגמה, אם בכתובת יש מספר רחוב לא מאושר, עדיין אפשר לאשר אותה. מצד שני, אם הפעילות העסקית שלכם דורשת דיוק רב יותר בכתובת, אתם יכולים להציג למשתמשים בקשה. דוגמה לכתובת שיכולה להיכלל בכל אחת מהקטגוריות מופיעה בקטע מספר בית לא מאומת מחוץ לארה"ב במאמר אישור כתובת – דוגמאות. |
| אישור כתובות |
מומלץ להגדיר את המערכת כך שתקבל את הקלט המקורי אם הלקוח לא מגיב להנחיות. |
במקרים כאלה, יכול להיות שהלקוח הזין כתובת שלא קיימת במערכת, למשל כתובת של מבנה חדש. |
תיקון כתובת
לתקן כתובת כשהתוצאות מצביעות בבירור על כך שלא ניתן לשלוח אליה. לאחר מכן, המערכת שלכם יכולה לבקש מהלקוח לספק את המידע הדרוש, ואז אתם מנפיקים מחדש את תהליך העבודה כדי לקבל כתובת שאפשר לשלוח אליה.
תיקון האותות
Address Validation API מספק כמה אותות שמאפשרים לכם לדעת אם צריך לתקן כתובת.
1. רמת הפירוט של האימות ורכיבים חסרים
שני האותות האלה מספקים את האינדיקציה הטובה ביותר לכתובת בעייתית:
- בכל פעם שהשדה
validationGranularityהואOTHER, המערכת צריכה לבדוק את האותות של רכיבי הכתובת כדי לקבל מידע נוסף על המקום שבו אירעה השגיאה ואיך לפתור את הבעיה. - בכל פעם שהאובייקט
addressשעבר עיבוד מחזיר שדהmissingComponentTypes, המערכת שלכם צריכה לבדוק את הרכיב הזה. אם חסרים רכיבים, הכתובת לא מלאה ואי אפשר לשלוח אליה.
2. אותות אחרים
Address Validation API מספק גם אותות אחרים שעוזרים לאבחן בעיות ספציפיות:
| רכיבים חשודים | כשרמת האישור של רכיב היא 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 של PREMISE או יותר הוא קביל, אבל במקרים מסוימים, ערך ROUTE עדיין מציין כתובת שאפשר לשלוח אליה.
2. אותות אחרים
התוצאה של כתובת באיכות גבוהה צריכה לכלול גם את הפרטים הבאים:
- אין נתונים שהוחלפו. במקרה כזה,
hasReplacedComponents: FALSE. - אין רכיבים שנוספו באופן אוטומטי. במקרה כזה,
hasInferredComponents: FALSE.
3. אותות של כתובות בארה"ב
שדות מסוימים שרלוונטיים רק לכתובות בארה"ב מציינים כתובת באיכות גבוהה שאפשר לשלוח אליה. אם הכתובת בארה"ב תקינה, יופיעו הפרטים הבאים:
dpvConfirmation
|
Y
לפרטים על
|
|---|