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