W tym dokumencie opisujemy proces tworzenia systemu sprawdzania adresów, który obsługuje różne odpowiedzi z interfejsu Address Validation API. Wyjaśnia, jak interpretować odpowiedź interfejsu API, aby określić, kiedy i w jaki sposób prosić klientów o dodatkowe informacje.
Odpowiedź interfejsu API określa ogólnie te sposoby, w jakie system powinien obsługiwać adres:
-
Popraw – adres może zawierać poważne problemy.
Poproś klienta o więcej informacji. -
Dodaj obiekt podrzędny – w adresie może brakować obiektu podrzędnego.
Rozważ wyświetlenie klientowi prośby o dodanie numeru lokalu. -
Potwierdź – adres może zawierać drobne problemy.
Możesz poprosić klienta o potwierdzenie, że adres jest prawidłowy. -
Zaakceptuj – adres może nie zawierać problemów.
Możesz użyć adresu bez dalszych monitów na własne ryzyko.
Przeznaczenie klucza
Ten dokument pomoże Ci zmodyfikować system, aby jak najlepiej analizować odpowiedź interfejsu API i określać kolejne działania, które należy podjąć w przypadku podanych adresów. Poniższy pseudokod ilustruje możliwy przepływ.
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.
Dokładna logika zależy od Twojej sytuacji. Więcej informacji znajdziesz w sekcji Dostosowywanie logiki weryfikacji.
Przykładowe przepływy pracy
Tabela poniżej zawiera podsumowanie przykładowych przepływów pracy, które możesz wdrożyć, aby wyświetlać klientowi prośby na podstawie odpowiedzi interfejsu API.
| zachowanie systemu, | ||
|---|---|---|
| Popraw adres |
Odpowiedź z
|
|
| Dodawanie podlokalizacji |
Odpowiedź z
|
|
| Potwierdź adres |
Odpowiedź z
|
|
| Zaakceptuj adres |
Odpowiedź z
|
|
Dostosowywanie logiki weryfikacji
Wyniki z pola verdict.possibleNextAction możesz wykorzystać do określenia, jak Twój system ma postępować z odpowiedzią interfejsu API. Możesz też rozważyć utworzenie logiki niestandardowej, np. do obsługi potrzeb specyficznych dla Twojej firmy.
Celem tej sekcji jest pokazanie, jak możesz opracować własną logikę niestandardową do interpretowania odpowiedzi interfejsu API, aby określić, czy i w jaki sposób chcesz wyświetlać prompt klientowi. W tej sekcji znajdziesz informacje o poziomach ryzyka i dodatkowych sygnałach odpowiedzi interfejsu API, które warto uwzględnić podczas dostosowywania.
Nawet jeśli przy podejmowaniu kolejnych kroków polegasz wyłącznie na verdict.possibleNextAction, dodatkowe sygnały opisane poniżej mogą pomóc Ci zrozumieć szczegóły potencjalnych problemów z adresem.
Tolerancja ryzyka
Podczas projektowania sposobu, w jaki system reaguje na sygnały z interfejsu Address Validation API, poniższe zalecenia mogą pomóc w utworzeniu skuteczniejszego modelu odpowiedzi. Są to jednak tylko rekomendacje, więc pamiętaj, że Twoje wdrożenie powinno być dostosowane do Twojego modelu biznesowego.
| Wskazówki | Szczegóły | |
|---|---|---|
| Poziom ryzyka |
Przy ustalaniu równowagi między wyświetlaniem prośby o poprawki a akceptowaniem wpisanego adresu weź pod uwagę poziom tolerancji w Twojej sytuacji. |
Address Validation API zwraca różne sygnały, które możesz uwzględnić w swoim poziomie ryzyka, aby zoptymalizować proces weryfikacji. Jeśli na przykład adres ma niepotwierdzony numer ulicy, możesz go zaakceptować. Z drugiej strony, jeśli Twoja firma wymaga większej precyzji adresu, możesz poprosić użytkownika o podanie dokładniejszych informacji. Przykład adresu, który może należeć do jednej z tych kategorii, znajdziesz w sekcji Niepotwierdzony numer domu spoza Stanów Zjednoczonych w akceptowanych adresach – przykłady. |
| Akceptowanie adresów |
Warto zezwolić systemowi na zaakceptowanie pierwotnego wpisu, jeśli klient nie odpowie na prośby. |
W takich przypadkach klient mógł wpisać adres, którego nie ma w systemie, np. w przypadku nowej konstrukcji. |
Przykład przepływu płatności z ograniczonym ryzykiem
Jeśli chcesz zmniejszyć ryzyko nieudanych dostaw, możesz dostosować logikę, aby częściej wyświetlać prośby do klientów. Zamiast logiki opisanej w sekcji Główny cel możesz na przykład użyć tej logiki:
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.
Przykład procesu płatności o niskim poziomie skomplikowania
Jeśli chcesz zmniejszyć liczbę kroków w procesie płatności, możesz dostosować logikę, aby rzadziej wyświetlać prośby do klientów. Zamiast logiki opisanej w sekcji Główny cel możesz na przykład użyć tej logiki:
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.
Sygnały FIX
Popraw adres, gdy wyniki wyraźnie wskazują, że dostarczenie przesyłki pod ten adres może być niemożliwe. System może wtedy poprosić klienta o podanie niezbędnych informacji, po czym ponownie uruchomić proces, aby uzyskać adres dostawy.
Oprócz pola verdict.possibleNextAction możesz użyć tych pól odpowiedzi interfejsu Address Validation API, aby określić, czy adres ma poważne problemy, i jakie to są problemy.
| Szczegółowość weryfikacji | Jeśli wartość wyliczeniowa szczegółowości weryfikacji adresu to OTHER, prawdopodobnie adres jest nieprawidłowy.
|
|---|---|
| Brakujące komponenty | Jeśli pole address.missingComponentTypes nie jest puste, prawdopodobnie w adresie brakuje kluczowych informacji.
|
| Podejrzane komponenty | Jeśli wyliczenie poziomu potwierdzenia komponentu to UNCONFIRMED_AND_SUSPICIOUS, prawdopodobnie komponent jest nieprawidłowy.
|
| Nierozwiązane komponenty | unresolvedToken to część danych wejściowych, która nie została rozpoznana jako prawidłowa część adresu. |
| Potwierdzenie DPV USPS | Jeśli wartość uspsData.dpvConfirmation to N lub jest pusta, może to oznaczać problem z adresem. To pole jest dostępne tylko w przypadku adresów w Stanach Zjednoczonych. Więcej informacji o uspsData.dpvConfirmation znajdziesz w artykule Obsługa adresów w Stanach Zjednoczonych.
|
Przykłady poprawionych adresów
Sygnały CONFIRM_ADD_SUBPREMISES (tylko adresy w Stanach Zjednoczonych)
Gdy odpowiedź interfejsu Address Validation API wskazuje, że w adresie może brakować części adresu, prosisz klienta o sprawdzenie adresu i rozważenie dodania numeru lokalu. W takich przypadkach adres budynku jest prawdopodobnie prawidłowy, ale chcesz mieć większą pewność, że wynikowy adres jest tym, o który chodziło klientowi.
Oprócz pola verdict.possibleNextAction możesz użyć tych pól odpowiedzi interfejsu Address Validation API, aby określić, czy w adresie prawdopodobnie brakuje lokalu.
Missing subpremise component
|
Jeśli pole address.missingComponentTypes zawiera wartość subpremise, oznacza to, że w adresie brakuje numeru lokalu.
|
|---|---|
| Potwierdzenie DPV USPS | Gdy uspsData.dpvConfirmation ma wartość S, oznacza to, że główny numer adresu został dopasowany do adresu w bazie danych USPS. Oczekiwano jednak, że adres będzie zawierać również numer dodatkowy. To pole jest dostępne tylko w przypadku adresów w Stanach Zjednoczonych. Więcej informacji o uspsData.dpvConfirmation znajdziesz w artykule Obsługa adresów w Stanach Zjednoczonych.
|
Sygnały CONFIRM
Adres jest potwierdzany, gdy wynik wskazuje, że interfejs Address Validation API wywnioskował lub zmienił komponenty adresu, aby uzyskać zweryfikowany adres. W takich przypadkach masz adres, pod który można dostarczyć przesyłkę, ale chcesz mieć większą pewność, że wynikowy adres jest tym, o który chodziło klientowi.
Oprócz pola verdict.possibleNextAction możesz użyć tych pól odpowiedzi interfejsu Address Validation API, aby określić, czy adres ma drobne problemy, i jakie to są problemy.
| Szczegółowość weryfikacji | Gdy validationGranularity adresu ma wartość ROUTE lub PREMISE_PROXIMITY, adres może być nieprawidłowy.
|
|---|---|
| Wywnioskowane dane | Gdy pole hasInferredComponents ma wartość true, oznacza to, że interfejs API wypełnił informacje uzyskane z innych komponentów adresu.
|
| Zastąpione dane | Gdy pole hasReplacedComponents ma wartość true, interfejs API zastąpił wprowadzone dane danymi, które uznał za prawidłowe dla adresu.
|
| Korekta pisowni | Gdy pole hasSpellCorrectedComponents ma wartość true, interfejs API poprawił pisownię niektórych komponentów.
|
Przykłady potwierdzania adresu
Sygnały ACCEPT
Możesz zaakceptować adres, gdy odpowiedź interfejsu Address Validation API wskazuje wysoki stopień pewności, że adres jest prawidłowy i może być używany w dalszym procesie bez dodatkowej interakcji z klientem.
Oprócz pola verdict.possibleNextAction do określania, czy adres ma odpowiednią jakość, można używać tych pól odpowiedzi interfejsu Address Validation API:
| Szczegółowość weryfikacji | Wartość validationGranularity wynosząca PREMISE jest często akceptowalna, chociaż wartość ROUTE może nadal wskazywać adres, pod który można dostarczyć przesyłkę.
|
|---|---|
| Brak danych wywnioskowanych | Gdy pole hasInferredComponents ma wartość false, oznacza to, że w danych wyjściowych nie ma żadnych wywnioskowanych komponentów.
|
| Brak zastąpionych danych | Jeśli pole hasReplacedComponents ma wartość false, oznacza to, że żadne dane wejściowe nie zostały zastąpione.
|
| Brak poprawek pisowni | Gdy pole hasSpellCorrectedComponents ma wartość false, oznacza to, że nie wprowadzono żadnych poprawek pisowni.
|
| Potwierdzenie DPV USPS | Gdy uspsData.dpvConfirmation ma wartość Y, oznacza to, że adres został dopasowany do adresu w bazie danych USPS. To pole jest dostępne tylko w przypadku adresów w Stanach Zjednoczonych. Więcej informacji o uspsData.dpvConfirmation znajdziesz w artykule Obsługa adresów w Stanach Zjednoczonych.
|
Przykłady akceptowanych adresów