בניית הלוגיקה של האימות

במסמך הזה מתואר תהליך ליצירת מערכת לבדיקת כתובות, שתדע לטפל במגוון תגובות מ-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 מציינת שיכול להיות שיש בעיות משמעותיות בכתובת. לדוגמה, verdict.possibleNextAction הוא FIX. כדאי לבקש מהלקוח מידע נוסף. תהליך עבודה אם צריך, בודקים את רכיבי הכתובת. הצגת הנחיה ללקוח לפתור בעיות שקשורות לכתובת. מבקשים אימות של הכתובת המעודכנת. (אופציונלי) שליחת בקשה לנקודת הקצה של המשוב עבור ה-API. איך מעדכנים כתובות ממשיכים עם הכתובת.
הוספת מיקום משנה	התשובה מ-verdict מציינת שאולי חסר מידע על מיקום משני בכתובת. לדוגמה, verdict.possibleNextAction הוא CONFIRM_ADD_SUBPREMISES. כדאי לבקש מהלקוח להוסיף מספר יחידה. תהליך עבודה מבקשים מהלקוח להוסיף מספר יחידה. מבקשים אימות של הכתובת המעודכנת. (אופציונלי) שליחת בקשה לנקודת הקצה של המשוב עבור ה-API. איך מעדכנים כתובות ממשיכים עם הכתובת.
אישור הכתובת	התשובה מ-method‏ verdict מציינת שיכול להיות שיש בעיות קלות בכתובת. לדוגמה, verdict.possibleNextAction הוא CONFIRM. מומלץ לבקש מהלקוח לבדוק את הכתובת. תהליך עבודה נדרשים תיקונים: אם צריך, בודקים את רכיבי הכתובת. מבקשים אימות של הכתובת המעודכנת. (אופציונלי) שליחת בקשה לנקודת הקצה של המשוב עבור ה-API. איך מעדכנים כתובות ממשיכים עם הכתובת. לא נדרשים תיקונים: (אופציונלי) שליחת בקשה לנקודת הקצה של המשוב עבור ה-API. איך מעדכנים כתובות ממשיכים עם הכתובת.
מאשרים את הכתובת	התשובה מ-verdict מציינת שאולי אין בעיות בכתובת. לדוגמה, verdict.possibleNextAction הוא ACCEPT. כדאי להמשיך בתהליך עם הכתובת בהתאם לרמת הסיכון. תהליך עבודה להמשיך עם הכתובת להחזרת מוצרים.

הערה: כששולחים שוב בקשות ל-Address Validation API עבור אותה כתובת, אפשר לבצע קריאה ל-provideValidationFeedback כדי לציין את התוצאה. איך מטפלים בכתובות מעודכנות

רוצים לנסות את ההדגמה? בהמשך המאמר מופיעות דוגמאות שונות שיעזרו לכם להבין את תהליך התיקון, האישור והקבלה שמתואר למעלה. כדי לראות את התוצאות של הדוגמאות האלה, אפשר להזין אותן בהדגמה של Address Validation API.

התאמה אישית של לוגיקת האימות

אפשר להשתמש בתוצאות מהשדה verdict.possibleNextAction כדי לקבוע איך המערכת תמשיך עם תגובת ה-API, אבל אפשר גם ליצור לוגיקה מותאמת אישית, למשל כדי לטפל בצרכים ספציפיים של העסק.

בקטע הזה נסביר איך לפתח לוגיקה מותאמת אישית משלכם כדי לפרש את התגובה של ה-API ולקבוע אם ואיך להציג בקשה ללקוח. בקטע הזה מוסבר על רמות הסיכון ועל אותות נוספים בתגובת ה-API שכדאי לקחת בחשבון כשמבצעים התאמה אישית.

עם זאת, גם אם אתם מסתמכים רק על verdict.possibleNextAction כדי להחליט על השלבים הבאים, האותות הנוספים שמתוארים בהמשך יכולים לעזור לכם להבין פרטים על בעיות פוטנציאליות בכתובת.

סובלנות לסיכון

כשמתכננים איך המערכת תגיב לאותות מ-API לאימות כתובות, ההמלצות הבאות יכולות לעזור לכם לבנות מודל תגובה יעיל יותר. עם זאת, אלה רק המלצות, ולכן חשוב לזכור שההטמעה צריכה להתאים למודל העסקי שלכם.

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

תיקון אותות

תיקון כתובת כשהתוצאות מציינות בבירור שהאימייל לא יכול להימסר. לאחר מכן, המערכת יכולה לבקש מהלקוח לספק את המידע הנדרש, ואז תוכלו להפעיל מחדש את תהליך העבודה כדי לקבל כתובת למשלוח.

אפשר להשתמש בשדות הבאים בתגובה של 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, המשמעות היא שחסר מספר יחידה בכתובת. הערה: אם השדה מכיל סוגים שאינם subpremise, הפעולה תסווג לקטגוריה FIX. הרשימה המלאה של סוגי הרכיבים מופיעה בתיעוד של Geocoding.
USPS DPV Confirmation	אם הערך של uspsData.dpvConfirmation הוא S, המשמעות היא שהמספר הראשי של הכתובת תואם לכתובת במסד הנתונים של USPS. עם זאת, הכתובת הייתה אמורה להכיל גם מספר משני. השדה הזה זמין רק לכתובות בארה"ב. פרטים נוספים על uspsData.dpvConfirmation זמינים במאמר טיפול בכתובות בארצות הברית.

דוגמאות לכתובות של יחידות משנה בנכס

אותות אישור

כתובת מאומתת אם פסק הדין מציין שממשק Address Validation API הסיק או ביצע שינויים ברכיבי הכתובת כדי ליצור כתובת מאומתת. במקרים כאלה, יש לכם כתובת שאפשר לשלוח אליה, אבל אתם רוצים להיות בטוחים יותר שהכתובת שמתקבלת היא הכתובת שהלקוח התכוון אליה.

אפשר להשתמש בשדות הבאים בתגובה של Address Validation API בנוסף ל-verdict.possibleNextAction כדי לקבוע אם יש בעיות קלות בכתובת, ומהן הבעיות האלה.

רמת הפירוט של האימות	אם הערך של validationGranularity עבור כתובת הוא ROUTE או PREMISE_PROXIMITY, יכול להיות שהכתובת שגויה.
נתונים משוערים	אם השדה hasInferredComponents הוא true, המשמעות היא שממשק ה-API מילא מידע שנאסף מרכיבים אחרים של הכתובת.
הנתונים שהוחלפו	אם הערך בשדה hasReplacedComponents הוא true, ה-API החליף את הנתונים שהוזנו בנתונים שלדעתו הופכים את הכתובת לתקינה.
תיקוני איות	אם הערך בשדה hasSpellCorrectedComponents הוא true, ה-API תיקן את האיות של חלק מהרכיבים שאויתו בצורה שגויה.

דוגמאות לכתובות לאישור

אותות ACCEPT

יכול להיות שתאשרו כתובת אם התגובה של 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 זמינים במאמר טיפול בכתובות בארצות הברית.

דוגמאות לכתובות