Opracuj logikę weryfikacji

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 verdict wskazuje, że z adresem mogą występować poważne problemy. Na przykład verdict.possibleNextAction to FIX. Możesz poprosić klienta o więcej informacji. 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 interfejsu API. Zobacz Obsługa zaktualizowanych adresów. Kontynuuj, używając adresu.
Dodawanie podlokalizacji	Odpowiedź z verdict wskazuje, że w adresie może brakować części budynku. Na przykład verdict.possibleNextAction to CONFIRM_ADD_SUBPREMISES. Rozważ poproszenie klienta o dodanie numeru lokalu. Przepływ pracy Poproś klienta o dodanie numeru lokalu. Poproś o weryfikację zaktualizowanego adresu. (Opcjonalnie) Wyślij żądanie do punktu końcowego opinii interfejsu API. Zobacz Obsługa zaktualizowanych adresów. Kontynuuj, używając adresu.
Potwierdź adres	Odpowiedź z verdict wskazuje, że mogą występować drobne problemy z adresem. Na przykład verdict.possibleNextAction to CONFIRM. Poproś klienta o sprawdzenie adresu. Przepływ pracy Korekty: W razie potrzeby sprawdź komponenty adresu. Poproś o weryfikację zaktualizowanego adresu. (Opcjonalnie) Wyślij żądanie do punktu końcowego opinii interfejsu API. Zobacz Obsługa zaktualizowanych adresów. Kontynuuj, używając adresu. Nie wymaga poprawek: (Opcjonalnie) Wyślij żądanie do punktu końcowego opinii interfejsu API. Zobacz Obsługa zaktualizowanych adresów. Kontynuuj, używając adresu.
Zaakceptuj adres	Odpowiedź z verdict wskazuje, że z adresem nie powinno być problemów. Na przykład verdict.possibleNextAction to ACCEPT. Rozważ postępowanie z adresem zgodnie z poziomem ryzyka. Przepływ pracy Kontynuuj z adresem zwrotnym.

Uwaga: gdy powtarzasz żądania do interfejsu Address Validation API dotyczące tego samego adresu, możesz wykonać wywołanie funkcji provideValidationFeedback, aby wskazać wynik. Zobacz 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ć opisany powyżej proces naprawiania, potwierdzania i akceptowania. Wyniki tych przykładów możesz sprawdzić, wpisując je w wersji demonstracyjnej interfejsu Address Validation API.

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. Uwaga: jeśli pole zawiera typy inne niż subpremise, działanie zostanie zakwalifikowane do kategorii FIX. Pełną listę typów komponentów znajdziesz w dokumentacji Geocoding API.
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.

Przykłady adresów podrzędnych

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.

Uwaga: przy podejmowaniu decyzji o akceptacji adresu lub poproszeniu klienta o więcej informacji weź pod uwagę poziom ryzyka.

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