W tym dokumencie opisujemy proces tworzenia systemu sprawdzania adresów, który obsługuje różne odpowiedzi z interfejsu Address Validation API. Wyjaśniamy w nim, jak opracować logikę, aby prawidłowo korzystać z odpowiedzi, badać inne sygnały z interfejsu API oraz kiedy i jak prosić klientów o więcej informacji.
Odpowiedź interfejsu API określa ogólnie te sposoby, w jakie system powinien obsługiwać adres:
- Popraw – adres jest niskiej jakości. Poproś o więcej informacji.
- Potwierdź – adres jest wysokiej jakości, ale różni się od adresu wejściowego. Możesz poprosić o potwierdzenie.
- Accept (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 ilustruje możliwy przepływ.
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 wskazówkach dotyczących implementacji. Możesz też użyć naszej implementacji open source tej logiki, która znajduje się w Bibliotece komponentów rozszerzonych.
Omówienie przepływu pracy
Tabela poniżej zawiera podsumowanie 2 działań w Twoim systemie:
- Przepływ pracy, którego należy użyć w zależności od tego, czy chcesz poprawić, potwierdzić czy zaakceptować.
- Pierwsze sygnały do sprawdzenia w odpowiedzi. Sygnały opisane poniżej pochodzą z usługi
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 zawiera opis dodatkowych sygnałów, które warto sprawdzić.
| zachowanie systemu, | |||
|---|---|---|---|
| Popraw adres |
Odpowiedź od
|
||
| Potwierdź adres |
Odpowiedź z
|
||
| Zaakceptuj adres |
Odpowiedź z interfejsu Address Validation API wskazuje adres o doskonałej jakości.
|
||
Wskazówki dotyczące implementacji
Podczas projektowania sposobu, w jaki system reaguje na sygnały weryfikacji adresu, 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. |
Poprawianie adresu
Popraw adres, gdy wyniki wyraźnie wskazują, że nie można dostarczyć przesyłki pod ten adres. System może wtedy poprosić klienta o podanie niezbędnych informacji, a następnie ponownie uruchomić proces, aby uzyskać adres dostawy.
Poprawianie sygnałów
Interfejs Address Validation API udostępnia szereg sygnałów, które informują, czy adres wymaga poprawy.
1. Szczegółowość weryfikacji i brakujące komponenty
Te 2 sygnały najlepiej wskazują na problematyczny adres:
- Gdy pole
validationGranularityma wartośćOTHER, system powinien zbadać sygnały komponentu adresu, aby dowiedzieć się więcej o tym, gdzie wystąpił błąd i jak go naprawić. - Gdy przetworzony obiekt
addresszwróci polemissingComponentTypes, system powinien sprawdzić ten komponent. Brakujące komponenty również sprawiają, że adres jest niekompletny i nie można na niego dostarczyć przesyłki.
2. Inne sygnały
Interfejs Address Validation API udostępnia też inne sygnały, które pomagają diagnozować konkretne problemy:
| Podejrzane komponenty | Jeśli wyliczenie poziomu potwierdzenia komponentu to UNCOMFIRMED_AND_SUSPICIOUS, prawdopodobnie komponent jest nieprawidłowy.
|
|---|---|
| Nierozwiązany komponent | unresolvedToken to część danych wejściowych, która nie została rozpoznana jako prawidłowa część adresu. |
3. Sygnały dotyczące adresu w Stanach Zjednoczonych
Niektóre pola mające zastosowanie tylko do adresów w Stanach Zjednoczonych stanowią przydatny sygnał, że adres jest nieprawidłowy i należy go poprawić. W przypadku adresu, który wymaga poprawy, zobaczysz:
dpvConfirmation
|
Może to być N, D lub pusta wartość.
|
|---|
Więcej informacji o dpvConfirmation znajdziesz w artykule Obsługa adresów w Stanach Zjednoczonych.
Przykłady poprawionych adresów
Potwierdzanie adresu
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.
Aby wyświetlić klientowi odpowiedni komunikat, logika musi 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.
Potwierdzanie sygnałów
Interfejs Address Validation API udostępnia szereg sygnałów, które informują, czy adres powinien zostać potwierdzony.
1. Szczegółowość weryfikacji
Dopuszczalny jest wynik validationGranularity
na poziomie ROUTE lub wyższym, ale PREMISE lub SUBPREMISE
dają silniejszy sygnał dostarczalności.
2. Inne sygnały
Decydując się na potwierdzenie adresu przez klienta, w wyniku podawane są też te informacje, które pomagają określić, które komponenty należy sprawdzić:
| 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 | Jeśli pole
hasReplacedComponents ma wartość true, interfejs API zastąpił wpisane dane danymi, które uznał za prawidłowe dla adresu.
|
3. Sygnały dotyczące adresu w Stanach Zjednoczonych
Niektóre pola, które mają zastosowanie tylko w przypadku adresów w Stanach Zjednoczonych, wskazują, że logika powinna potwierdzić szczegóły z klientem. Spełniony jest jeden z tych warunków:
dpvConfirmation
|
S
Więcej informacji o |
|---|---|
| Odpowiedź dotycząca adresu | Zawiera pole missingComponentTypes o wartości
subpremise.
|
Przykłady potwierdzania adresu
Akceptowanie adresu
Adres jest akceptowany, gdy wynik wskazuje na wysoki stopień pewności, że adres jest dostarczalny i może być używany w dalszym procesie bez dodatkowej interakcji z klientem.
Akceptowanie sygnałów
Interfejs Address Validation API udostępnia szereg sygnałów, które informują, czy adres powinien zostać potwierdzony.
1. Szczegółowość weryfikacji
Dopuszczalny jest validationGranularity o wartości PREMISE lub wyższej, ale w niektórych przypadkach ROUTE nadal oznacza 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 tym przypadku
hasReplacedComponents: FALSE. - Brak wywnioskowanych komponentów. W tym przypadku
hasInferredComponents: FALSE.
3. Sygnały dotyczące adresu w Stanach Zjednoczonych
Niektóre pola mające zastosowanie tylko do adresów w Stanach Zjednoczonych wskazują adres wysokiej jakości, pod który można dostarczyć przesyłkę. Prawidłowy adres w Stanach Zjednoczonych powinien zawierać te informacje:
dpvConfirmation
|
Y
Więcej informacji o
|
|---|
Przykłady akceptowanych adresów