Z tego dokumentu dowiesz się, jak utworzyć system sprawdzania adresów, który będzie obsługiwać różne odpowiedzi z interfejsu Address Validation API. Dowiesz się, jak utworzyć logikę, która będzie prawidłowo korzystać z odpowiedzi, sprawdzać inne sygnały z interfejsu API oraz kiedy i jak prosić klientów o więcej informacji.
Ogólnie rzecz biorąc, odpowiedź interfejsu API określa, w jaki sposób system powinien obsługiwać adres:
- Popraw – adres jest niskiej jakości. Powinieneś(-aś) poprosić o więcej informacji.
- Potwierdź – adres jest wysokiej jakości, ale ma zmiany w stosunku do adresu wejściowego. Możesz poprosić o potwierdzenie.
- Zaakceptuj – adres jest wysokiej jakości. Możesz zaakceptować podany adres.
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 przedstawia możliwy przepływ pracy.
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.
Dokładna logika zależy od Twojej sytuacji. Więcej informacji znajdziesz w sekcji Implementacja – wskazówki . Możesz też użyć naszej implementacji open source tej logiki, która znajduje się w rozszerzonej bibliotece komponentów.
Omówienie przepływu pracy
W tabeli poniżej znajdziesz podsumowanie 2 działań, które może wykonać Twój system:
- Przepływ pracy, którego należy użyć na podstawie zachowania „popraw”, „potwierdź” i „zaakceptuj”.
- Pierwsze sygnały, które należy sprawdzić w odpowiedzi. Opisane tutaj sygnały pochodzą z właściwości
verdicti nie są jedynymi sygnałami, które należy sprawdzić, ale stanowią wstępny wskaźnik jakości adresu. Każdy typ zachowania odpowiada sekcji w tym dokumencie, która opisuje dalsze sygnały, które mogą wymagać sprawdzenia.
| Zachowanie systemu | |||
|---|---|---|---|
| Popraw adres |
Odpowiedź z
|
||
| Potwierdź adres |
Odpowiedź z
|
||
| Zaakceptuj adres |
Odpowiedź interfejsu Address Validation API wskazuje adres o doskonałej jakości.
|
||
Implementacja – wskazówki
Podczas projektowania sposobu reagowania systemu na sygnały sprawdzania adresu możesz skorzystać z tych rekomendacji, aby stworzyć skuteczniejszy model odpowiedzi. Pamiętaj jednak, że są to tylko rekomendacje, a Twoja implementacja powinna być dostosowana do Twojego modelu biznesowego.
| Wskazówki | Szczegóły | |
|---|---|---|
| Poziom ryzyka |
Podczas równoważenia między proszeniem o poprawki a akceptowaniem adresu w takiej postaci, w jakiej został wpisany, weź pod uwagę poziom tolerancji w Twojej sytuacji. |
Interfejs Address Validation API zwraca różne sygnały które możesz uwzględnić na swoim poziomie ryzyka, aby zoptymalizować proces sprawdzania Jeśli na przykład adres ma niepotwierdzony numer ulicy, możesz zaakceptować go. Z drugiej strony, jeśli Twoja działalność wymaga większej precyzji adresu, możesz poprosić użytkownika o jego poprawienie. Przykład, który może należeć do jednej z tych kategorii, znajdziesz w sekcji Akceptowanie adresu – przykłady w artykule Non-US unconfirmed street number (Niepotwierdzony numer ulicy spoza USA). |
| Akceptowanie adresów |
Dobrym rozwiązaniem jest zezwolenie systemowi na akceptowanie pierwotnego wpisu jeśli klient nie odpowie na prośby. |
W takich przypadkach klient mógł wpisać adres, który nie znajduje się w systemie, np. adres nowego budynku. |
Poprawianie adresu
Popraw adres, gdy wyniki wyraźnie wskazują, że nie można go dostarczyć. System może wtedy poprosić klienta o podanie niezbędnych informacji, po czym ponownie uruchomisz przepływ pracy, aby uzyskać adres, pod który można dostarczyć przesyłkę.
Sygnały poprawki
Interfejs Address Validation API udostępnia kilka sygnałów, które informują, czy adres należy poprawić.
1. Szczegółowość sprawdzania i brakujące komponenty
Te 2 sygnały najlepiej wskazują na problematyczny adres:
- Gdy pole
validationGranularityma wartośćOTHER, system powinien sprawdzić sygnały komponentów adresu aby dowiedzieć się więcej o tym, gdzie wystąpił błąd i jak go naprawić. - Gdy przetworzony obiekt
addresszwraca polemissingComponentTypes, system powinien sprawdzić ten komponent. Brakujące komponenty sprawiają też, że adres jest niekompletny i nie można go dostarczyć.
2. Inne sygnały
Interfejs Address Validation API udostępnia też inne sygnały, które pomagają zdiagnozować konkretne problemy:
| Podejrzane komponenty | Gdy wyliczenie poziomu potwierdzenia komponentu ma wartość
UNCOMFIRMED_AND_SUSPICIOUS, prawdopodobnie komponent jest
nieprawidłowy.
|
|---|---|
| Nierozwiązany komponent | unresolvedToken |
3. Sygnały adresu w USA
Niektóre pola, które mają zastosowanie tylko do adresów w USA, stanowią przydatny sygnał, że adresu nie można dostarczyć i należy go poprawić. W przypadku adresu, który wymaga poprawienia, powinny być widoczne te informacje:
dpvConfirmation
|
N, D lub puste.
|
|---|
Więcej informacji o dpvConfirmation znajdziesz w
artykule Obsługa adresów w Stanach Zjednoczonych.
Potwierdzanie adresu
Potwierdzasz adres, gdy werdykt wskazuje, że interfejs Address Validation API wywnioskował lub zmienił komponenty adresu, aby uzyskać sprawdzony adres. W takich przypadkach masz adres, pod który można dostarczyć przesyłkę, ale wolisz mieć większą pewność, że wynikowy adres jest adresem, który miał na myśli klient.
Aby wyświetlić klientowi prawidłowy komunikat, Twoja logika powinna zidentyfikować komponenty oznaczone przez usługę, aby określić, jakie działanie lub flagę interfejs API zastosował do komponentu, np. inferred, replaced lub spellCorrected.
Więcej informacji znajdziesz w sekcji AddressComponent w dokumentacji.
Sygnały potwierdzenia
Interfejs Address Validation API udostępnia kilka sygnałów, które informują, czy adres należy potwierdzić.
1. Szczegółowość sprawdzania
A validationGranularity
o wartości ROUTE lub lepszej jest akceptowalna, ale PREMISE lub SUBPREMISE
stanowi silniejszy sygnał, że adres można dostarczyć.
2. Inne sygnały
Podczas podejmowania decyzji o potwierdzeniu adresu u klienta werdykt zawiera też te informacje, które pomagają określić, które komponenty należy sprawdzić:
| Wywnioskowane dane | Gdy pole
hasInferredComponents ma wartość true, wiesz, że interfejs API uzupełnił informacje, które uzyskał 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.
|
3. Sygnały adresu w USA
Niektóre pola, które mają zastosowanie tylko do adresów w USA, wskazują, że Twoja logika powinna potwierdzić szczegóły u klienta. Spełniony jest dowolny z tych warunków:
dpvConfirmation
|
S
Więcej informacji o |
|---|---|
| Odpowiedź adresu | Zawiera pole missingComponentTypes o wartości
subpremise.
|
Przykłady potwierdzania adresów
Akceptowanie adresu
Akceptujesz adres, gdy werdykt wskazuje, że adres można dostarczyć i można go użyć bez dalszej interakcji z klientem w dalszym procesie.
Sygnały akceptacji
Interfejs Address Validation API udostępnia kilka sygnałów, które informują, czy adres należy potwierdzić.
1. Szczegółowość sprawdzania
validationGranularity o wartości PREMISE lub lepszej jest akceptowalna, ale w niektórych przypadkach ROUTE nadal wskazuje adres, pod który można dostarczyć przesyłkę.
2. Inne sygnały
Werdykt dotyczący adresu wysokiej jakości powinien też zawierać te informacje:
- Brak zastąpionych danych. W takim przypadku
hasReplacedComponents: FALSE. - Brak wywnioskowanych komponentów. W takim przypadku
hasInferredComponents: FALSE.
3. Sygnały adresu w USA
Niektóre pola, które mają zastosowanie tylko do adresów w USA, wskazują adres wysokiej jakości, pod który można dostarczyć przesyłkę. W przypadku akceptowalnego adresu w USA powinny być widoczne te informacje:
dpvConfirmation
|
Y
Więcej informacji o
|
|---|
Przykłady akceptowania adresów