Opracuj logikę weryfikacji

Ten dokument opisuje proces tworzenia systemu sprawdzania adresów do obsługi różnych odpowiedzi z interfejsu Address Validation API. Dowiesz się z niego, jak stworzyć logikę prawidłowego korzystania z odpowiedzi, zbadać inne sygnały z interfejsu API oraz jak i kiedy prosić klientów o dodatkowe informacje.

Ogólnie odpowiedź interfejsu API określa następujące sposoby obsługi adresu przez system:

• Napraw – adres jest niskiej jakości. Powinna pojawić się prośba o podanie dodatkowych informacji.
• Potwierdź – adres ma wysoką jakość, ale został zmieniony z podanego adresu. Możesz zobaczyć prośbę o potwierdzenie.
• Akceptuj – adres jest wysokiej jakości. Możesz zaakceptować podany adres.

Przeznaczenie klucza

Ten dokument pomoże Ci zmodyfikować system, aby jak najdokładniej przeanalizować odpowiedź interfejsu API i określić następne działania, jakie 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 konkretnej sytuacji – więcej informacji znajdziesz w sekcji Wskazówki dotyczące implementacji. Możesz też skorzystać z naszej implementacji tej logiki typu open source, która znajduje się w rozszerzonej bibliotece komponentów.

Omówienie przepływu pracy

W tabeli poniżej znajdziesz podsumowanie 2 działań wykonywanych w systemie:

1. Przepływ pracy do użycia oparty na rozwiązaniu problemu, który należy potwierdzić i zaakceptować.
2. Pierwszy sygnał, który należy sprawdzić w odpowiedzi. Opisane tu sygnały pochodzą z usługi verdict i nie są jedynymi sygnałami, które należy sprawdzić, ale stanowią początkowy wskaźnik jakości adresu. Każdy typ zachowania odpowiada sekcji w tym dokumencie opisującej dalsze sygnały, które również mogą wymagać zbadania.

Działanie systemu
Popraw adres	Odpowiedź z verdict wskazuje ważne brakujące informacje, które należy podać. Adres zwracany przez interfejs Address Validation API może mieć niską jakość. Przepływ pracy W razie potrzeby sprawdź komponenty adresu. Poproś klienta o rozwiązanie problemów z adresem. Poproś o weryfikację zaktualizowanego adresu. (Opcjonalnie) Wyślij żądanie do punktu końcowego opinii dla interfejsu API. Zapoznaj się z sekcją Obsługa zaktualizowanych adresów. Kontynuuj z adresem. Sygnały oceny Ma miejsce dowolne z tych warunków: Ustawiono validationGranularity na OTHER. Zobacz wartości szczegółowości. addressComplete to false.
Potwierdź adres	Odpowiedź z verdict wskazuje adres, który można dostarczyć, ale wprowadziła zmiany w pierwotnych danych wejściowych: określamy dane, które zostały poprawione, lub dane, które można potwierdzić. Przepływ pracy Wymagane poprawki: W razie potrzeby sprawdź komponenty adresu. Poproś o weryfikację zaktualizowanego adresu. (Opcjonalnie) Wyślij żądanie do punktu końcowego opinii dla interfejsu API. Zapoznaj się z sekcją Obsługa zaktualizowanych adresów. Kontynuuj z adresem. Nie ma potrzeby wprowadzania poprawek: (Opcjonalnie) Wyślij żądanie do punktu końcowego opinii dla interfejsu API. Zapoznaj się z sekcją Obsługa zaktualizowanych adresów. Kontynuuj z adresem. Sygnały oceny Są spełnione wszystkie te warunki: validationGranularity zawiera wartość ROUTE lub lepszą. Zobacz wartości szczegółowości. addressComplete to true. Pole hasInferredComponents to true LUB pole hasReplacedComponents zawiera wartość true.
Zaakceptuj adres	Odpowiedź interfejsu Address Validation API wskazuje doskonały adres wysokiej jakości. Przepływ pracy Kontynuuj ze zwróconym adresem. Sygnały oceny Są spełnione wszystkie te warunki: validationGranularity zawiera wartość PREMISE lub lepszą. Zobacz wartości szczegółowości. addressComplete to true. Nie zostały ustalone lub wymienione komponenty.

Implementacja – wskazówki

Poniższe rekomendacje pomogą Ci podczas projektowania reakcji systemu na sygnały z interfejsu Address Validation API. Podane niżej zalecenia pomogą Ci utworzyć wydajniejszy model odpowiedzi. Są to jednak tylko zalecenia, pamiętaj więc, że implementacja powinna być zgodna z Twoim modelem biznesowym.

	Wskazówki	Szczegóły
Poziom ryzyka	Aby zachować równowagę między prośbami o poprawienie a akceptacją wpisanego adresu, weź pod uwagę poziom tolerancji w swojej sytuacji.	Interfejs Address Validation API zwraca różne sygnały, które możesz uwzględnić w zestawieniu z poziomem ryzyka, aby zoptymalizować proces weryfikacji. Jeśli na przykład adres ma niepotwierdzony numer domu, nadal możesz go zaakceptować. Jeśli natomiast Twoja firma wymaga większej precyzji adresu, możesz poprosić o to użytkownika. Przykłady, które mogą należeć do każdej z tych kategorii, znajdziesz w sekcji Niepotwierdzony numer domu spoza USA w artykule Akceptowany adres – przykłady.
Akceptuj adresy	Warto zezwolić systemowi na zaakceptowanie pierwotnego wpisu, jeśli klient nie odpowie na prompty.	W takich przypadkach klient mógł wpisać adres, którego nie ma w systemie, na przykład w przypadku nowej budowy.
Przekazywanie opinii	Gdy ponownie wyślesz prośbę o weryfikację adresu, możesz ją też wysłać do punktu końcowego provideValidationFeedback.	Dzięki temu będziemy wiedzieć, jak ostatecznie podjęto decyzję. Zapoznaj się z sekcją Obsługa zaktualizowanych adresów.

Wypróbuj wersję demonstracyjną W pozostałej części tego dokumentu znajdziesz różne przykłady, które pomogą Ci zrozumieć, jak naprawić błąd, a także potwierdzić i zaakceptować opisany powyżej proces. Możesz zapoznać się z wynikami tych przykładów, wpisując je w wersji demonstracyjnej interfejsu Address Validation API.

Poprawianie adresu

Popraw adres, gdy wyniki wyraźnie wskazują, że nie można go dostarczyć. System może następnie poprosić klienta o podanie niezbędnych informacji, a potem ponownie uruchomić przepływ pracy, aby uzyskać adres do dostarczenia.

Uwaga: jeśli w przypadku tego samego adresu wielokrotnie wysyłasz żądania do interfejsu Address Validation API, możesz wywołać metodę provideValidationFeedback, aby poinformować o wyniku. Patrz sekcja Obsługa adresów w Stanach Zjednoczonych.

Napraw sygnały

Interfejs Address Validation API dostarcza wiele sygnałów, które informują, czy adres należy poprawić.

1. Szczegółowość weryfikacji i brakujące komponenty

Te dwa sygnały najlepiej wskazują problemy z adresem:

• Gdy pole validationGranularity ma wartość OTHER, system powinien sprawdzać sygnały komponentów adresu, aby dowiedzieć się, gdzie wystąpił błąd i jak go naprawić.
• Za każdym razem, gdy przetworzony obiekt address zwraca pole missingComponentTypes, system powinien szukać tego komponentu. Brakujące komponenty powodują też, że adres jest niekompletny i nie można go dostarczyć.

2. Inne sygnały

Interfejs Address Validation API dostarcza też inne sygnały pomagające w diagnozowaniu konkretnych problemów:

Podejrzane komponenty	Gdy enum poziomu potwierdzenia dla komponentu wynosi UNCOMFIRMED_AND_SUSPICIOUS, prawdopodobnie komponent jest nieprawidłowy.
Komponent nierozwiązany	unresolvedToken to część danych wejściowych, która nie została rozpoznana jako prawidłowa część adresu.

3. Sygnały adresowe w Stanach Zjednoczonych

Niektóre pola dotyczące tylko adresów w Stanach Zjednoczonych stanowią przydatny sygnał, że adresu nie można dostarczyć i należy poprawić adres. W przypadku adresu, który wymaga naprawy, zobaczysz ten komunikat:

dpvConfirmation	Pole N, D lub puste.

Szczegółowe informacje o dpvConfirmation znajdziesz w artykule Obsługa adresów w Stanach Zjednoczonych.

Przykłady poprawek adresów

Potwierdź adres

Potwierdzasz adres, gdy wynik wskazuje, że interfejs Address Validation API został wywnioskowany lub wprowadził zmiany w komponentach adresu w celu wygenerowania potwierdzonego adresu. W takich przypadkach masz adres, który można dostarczyć, ale chcesz mieć większą pewność, że otrzymany adres to adres zamierzony przez klienta.

Aby dostarczyć klientowi prawidłowe prompty, Twoje systemy logiczne rozpoznają komponenty oznaczone przez usługę w celu określenia działania lub flagi zastosowanego przez interfejs API do komponentu, np. inferred, replaced lub spellCorrected. Zobacz AddressComponent w dokumentacji.

Uwaga: podejmując decyzję, czy potwierdzić adres klientowi czy zaakceptować go jako prawidłowy, weź pod uwagę poziom ryzyka. Dodatkowo, jeśli ponownie wyślesz żądania do interfejsu Address Validation API, możesz użyć wywołania provideValidationFeedback, aby wskazać wynik. Patrz sekcja Obsługa zaktualizowanych adresów.

Potwierdzanie sygnałów

Interfejs Address Validation API dostarcza szereg sygnałów, które informują, czy adres należy potwierdzić.

1. Szczegółowość walidacji

Akceptowana jest wartość validationGranularity o wartości ROUTE lub wyższa, ale opcja PREMIS (PREMIUM) lub SUBPREMISE (PRZEŚLIJ) pozwala lepiej wskazać, że została ona dostarczona.

2. Inne sygnały

Decydując się na potwierdzenie podania adresu z klientem, w wyniku weryfikacji znajdują się również następujące informacje pozwalające określić, które elementy należy sprawdzić:

Dane wywnioskowane	Gdy pole hasInferredComponents ma wartość true, wiesz, że interfejs API wypełnił informacje zebrane z innych komponentów adresu.
Zastąpione dane	Gdy pole hasReplacedComponents ma wartość true, interfejs API zastępuje wpisane dane danymi, które uznał za prawidłowy adres.

3. Sygnały adresowe w Stanach Zjednoczonych

Niektóre pola, które mają zastosowanie tylko w przypadku adresów w Stanach Zjednoczonych, wskazują, że Twój mechanizm logiczny powinien potwierdzać dane z klientem. Może być spełniony jeden z tych warunków:

dpvConfirmation	S Szczegółowe informacje o dpvConfirmation znajdziesz w sekcji Obsługa adresów w Stanach Zjednoczonych.
Odpowiedź z adresem	Zawiera pole missingComponentType o wartości subpremise. Uwaga: jeśli pole zawiera typy inne niż subpremise, działanie będzie należeć do kategorii naprawy adresów. Pełną listę typów adresów znajdziesz w dokumentacji geokodowania.

Przykładowe potwierdzanie adresów

Akceptowanie adresu

Akceptujesz adres, gdy ocena daje wysoki stopień pewności, że adres może zostać dostarczony i będzie można go użyć bez dalszej interakcji z klientem w kolejnym procesie.

Akceptuj sygnały

Interfejs Address Validation API dostarcza szereg sygnałów, które informują, czy adres należy potwierdzić.

1. Szczegółowość walidacji

Dozwolona jest wartość validationGranularity o wartości PREMISE lub większa, ale w niektórych przypadkach ROUTE nadal wskazuje adres, który można dostarczyć.

2. Inne sygnały

Ocena wysokiej jakości adresu powinna też zawierać:

• Brak zastąpionych danych. W tym przypadku: hasReplacedComponents: FALSE.
• Brak wykrytych komponentów. W tym przypadku: hasInferredComponents: FALSE.

3. Sygnały adresowe w Stanach Zjednoczonych

Niektóre pola dotyczące adresów w Stanach Zjednoczonych wskazują wysokiej jakości adres, na który można dostarczyć przesyłkę. Oto informacje o akceptowanym adresie w Stanach Zjednoczonych:

dpvConfirmation	Y Szczegółowe informacje o dpvConfirmation znajdziesz w sekcji Obsługa adresów w Stanach Zjednoczonych.

Przykłady adresów akceptowanych