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. Dowiesz się z niego, jak interpretować odpowiedź interfejsu API, aby określić, kiedy i jak poprosić klientów o dodatkowe informacje.

Ogólnie odpowiedź interfejsu API określa, w jaki sposób system powinien obsługiwać adres:

• Popraw – adres może zawierać poważne błędy.
  Zachęć klienta do podania dodatkowych informacji.
• Dodaj lokalizację w podmiocie zależnym – może brakować adresu lokalizacji w podmiocie zależnym.
  Zachęć klienta do dodania numeru jednostki.
• Potwierdź – adres może zawierać drobne błędy.
  Zachęć klienta do potwierdzenia, że adres jest prawidłowy.
• Zaakceptuj – adres może nie zawierać problemów.
  Użyj adresu bez dodatkowego wyświetlania prośby o jego podanie.

Przeznaczenie klucza

Ten dokument pomoże Ci zmodyfikować system, aby najlepiej analizować odpowiedź interfejsu API i określać kolejne działania dotyczące podanych adresów. Poniżej przedstawiono przepływ danych w postaci pseudokodu.

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 sytuacji. Więcej informacji znajdziesz w sekcji Dostosowywanie logiki sprawdzania.

Możliwe przepływy pracy

Tabela poniżej zawiera podsumowanie możliwych przepływów pracy, które możesz wdrożyć, aby poprosić klienta o opinię na podstawie odpowiedzi interfejsu API.

Zachowanie systemu
Popraw adres	Odpowiedź z verdict wskazuje, że adres może mieć poważne problemy. Na przykład:verdict.possibleNextAction to FIX. Zaproponuj klientowi podanie dodatkowych informacji. Przepływ pracy W razie potrzeby sprawdź elementy adresu. Poproś klienta o naprawienie problemów z adresem. Poproś o weryfikację zaktualizowanego adresu. (Opcjonalnie) Prześlij żądanie do punktu końcowego opinii interfejsu API. Zobacz Praca z zaktualizowanymi adresami. Przejdź do adresu.
Dodawanie pomieszczeń podrzędnych	Odpowiedź z verdict wskazuje, że adres może nie zawierać lokalizacji podrzędnej. Na przykład verdict.possibleNextAction jest CONFIRM_ADD_SUBPREMISES. Poproś klienta o dodanie numeru jednostki. Przepływ pracy Poproś klienta o dodanie numeru pokoju. Poproś o weryfikację zaktualizowanego adresu. (Opcjonalnie) Prześlij żądanie do punktu końcowego opinii interfejsu API. Zobacz Praca z zaktualizowanymi adresami. Przejdź do adresu.
Potwierdź adres	Odpowiedź z verdict wskazuje, że adres może mieć drobne problemy. Na przykład verdict.possibleNextAction jest CONFIRM. Poproś klienta o sprawdzenie adresu. Przepływ pracy Korekty: W razie potrzeby sprawdź elementy adresu. Poproś o weryfikację zaktualizowanego adresu. (Opcjonalnie) Prześlij żądanie do punktu końcowego opinii interfejsu API. Zobacz Praca z zaktualizowanymi adresami. Przejdź do adresu. Nie trzeba wprowadzać żadnych poprawek: (Opcjonalnie) Prześlij żądanie do punktu końcowego opinii interfejsu API. Zobacz Praca z zaktualizowanymi adresami. Przejdź do adresu.
Akceptowanie adresu	Odpowiedź z verdict wskazuje, że adres może nie mieć problemów. Na przykład verdict.possibleNextAction jest ACCEPT. Rozważ podanie adresu w sposób odpowiedni do poziomu ryzyka. Przepływ pracy Przejdź do adresu zwrotnego.

Uwaga: jeśli powtarzasz żądania wysyłane do interfejsu Address Validation API dotyczące tego samego adresu, możesz wywołać funkcję provideValidationFeedback, aby wskazać wynik. Zobacz Praca z adresami zaktualizowanymi

.

Wypróbuj wersję demonstracyjną W dalszej części tego dokumentu znajdziesz różne przykłady, które pomogą Ci zrozumieć omówiony powyżej proces naprawy, potwierdzenia i zaakceptowania. Wyniki z tych przykładów możesz sprawdzić, wpisując je w demo interfejsu Address Validation API.

Dostosowywanie logiki weryfikacji

Możesz użyć wyników z pola verdict.possibleNextAction, aby określić, jak Twój system ma postępować z odpowiedzią interfejsu API, ale możesz też zastosować logikę niestandardową, np. do obsługi potrzeb związanych z Twoją firmą.

Celem tej sekcji jest pokazanie, jak możesz opracować własną logikę do interpretowania odpowiedzi interfejsu API, aby określić, czy i jak chcesz zapytać klienta. W tej sekcji omawiamy poziomy ryzyka i dodatkowe sygnały odpowiedzi interfejsu API, które warto wziąć pod uwagę podczas dostosowywania.

Mimo to nawet wtedy, gdy podejmujesz decyzje wyłącznie na podstawie verdict.possibleNextAction, dodatkowe sygnały opisane poniżej mogą Ci pomóc w zrozumieniu szczegółów dotyczących potencjalnych problemów z adresem.

Tolerancja ryzyka

Podczas projektowania sposobu, w jaki Twój system reaguje na sygnały z interfejsu Address Validation API, te zalecenia mogą pomóc Ci stworzyć skuteczniejszy model odpowiedzi. Pamiętaj jednak, że są to tylko rekomendacje, a ich wdrożenie powinno być dostosowane do Twojego modelu biznesowego.

	Wskazówki	Szczegóły
Poziom ryzyka	Podczas podejmowania decyzji o tym, czy wyświetlać prośbę o poprawki, czy zaakceptować adres w takiej formie, jaką został wpisany, weź pod uwagę poziom tolerancji w danym przypadku.	Interfejs API weryfikacji adresu zwraca różne sygnały, które możesz uwzględnić w poziomie ryzyka, aby zoptymalizować proces weryfikacji. Jeśli na przykład adres ma niezweryfikowany numer ulicy, możesz go nadal zaakceptować. Jeśli jednak Twoja firma wymaga większej dokładności adresu, możesz poprosić użytkownika o jego podanie. Przykład, który może pasować do obu kategorii, znajdziesz w sekcji Niepotwierdzony numer ulicy w kraju spoza USA w artykule Akceptowane adresy – przykłady.
Akceptowanie adresów	Jeśli klient nie reaguje na prompty, warto pozwolić systemowi zaakceptować pierwotne dane.	W takich przypadkach klient może podać adres, którego nie ma w systemie, np. adres nowej budowy.

Przykład procesu płatności dla użytkowników unikających ryzyka

Jeśli chcesz zmniejszyć ryzyko nieudanych dostaw, możesz dostosować logikę, aby częściej wyświetlać klientom prośby. 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 współczynniku tarcia

Jeśli chcesz zmniejszyć trudności w procesie płatności, możesz dostosować logikę, aby rzadziej wyświetlać klientom prośby. 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 może być on nieprawidłowy. Twój system może poprosić klienta o podanie niezbędnych informacji, a następnie ponownie uruchomić przepływ pracy, aby uzyskać adres dostawy.

Oprócz 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 enumeracja dokładności weryfikacji adresu ma wartość OTHER, adres jest prawdopodobnie nieprawidłowy.
Brakujące komponenty	Jeśli element address.missingComponentTypes nie jest pusty, prawdopodobnie brakuje w adresie kluczowych informacji.
Podejrzane komponenty	Jeśli enumeracja poziomu potwierdzenia dla 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 USPS DPV	Jeśli uspsData.dpvConfirmation to N lub jest pusty, 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 Praca z adresami w Stanach Zjednoczonych.

Przykłady poprawiania adresów

sygnały CONFIRM_ADD_SUBPREMISES (tylko adresy w USA),

Gdy odpowiedź interfejsu Address Validation API wskazuje, że adres może nie zawierać informacji o podmiocie, poproś klienta o sprawdzenie adresu i rozważ dodanie numeru mieszkania. W takich przypadkach adres budynku jest prawdopodobnie prawidłowy, ale chcesz mieć pewność, że adres wynikowy jest tym, który podał klient.

Oprócz pola verdict.possibleNextAction można użyć tych pól odpowiedzi interfejsu API weryfikacji adresu, aby określić, czy adres prawdopodobnie nie zawiera części obiektu:

Missing subpremise component	Jeśli pole address.missingComponentTypes zawiera wartość subpremise, oznacza to, że w adresie brakuje numeru pokoju. Uwaga: jeśli pole zawiera typy inne niż subpremise, działanie zostanie przypisane do kategorii NAPRAW. Pełną listę typów komponentów znajdziesz w dokumentacji dotyczącej geokodowania.
Potwierdzenie USPS DPV	Jeśli uspsData.dpvConfirmation to S, oznacza to, że główny numer adresu został dopasowany do adresu w bazie danych USPS. Adres powinien jednak zawierać także numer pomocniczy. To pole jest dostępne tylko w przypadku adresów w Stanach Zjednoczonych. Więcej informacji o uspsData.dpvConfirmation znajdziesz w artykule Praca z adresami w Stanach Zjednoczonych.

Przykłady adresów w subprezydium

POTWIERDŹ sygnały

Adres jest potwierdzany, gdy interfejs Address Validation API stwierdza, że został wywnioskowany lub zmieniony w składowych adresu, aby uzyskać potwierdzony adres. W takich przypadkach masz adres dostawy, ale wolisz mieć pewność, że jest to adres, który klient wskazał.

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	Jeśli validationGranularity adresu toROUTE lub PREMISE_PROXIMITY, adres może być nieprawidłowy.
Dane wywnioskowane	Gdy pole hasInferredComponents ma wartość true, wiesz, że interfejs API wypełnił informacje uzyskane z innych komponentów adresu.
Zastąpione dane	Gdy pole hasReplacedComponents ma wartość true, interfejs API zastępuje wprowadzone dane danymi, które uzna za prawidłowe.
Poprawki pisowni	Gdy pole hasSpellCorrectedComponents ma wartość true, interfejs API poprawia pisownię niektórych komponentów z błędami.

Przykłady adresów do potwierdzenia

Sygnały ACCEPT

Adres możesz zaakceptować, jeśli odpowiedź interfejsu Address Validation API zapewnia wysoki stopień pewności, że adres jest prawidłowy i można go wykorzystać bez dalszej interakcji z klientem w dalszym procesie.

Uwaga: rozważ poziom ryzyka, zanim zdecydujesz, czy zaakceptować adres lub poprosić klienta o dodatkowe informacje.

Oprócz pola verdict.possibleNextAction można użyć tych pól odpowiedzi interfejsu Address Validation API, aby określić, czy adres jest wystarczająco dobrej jakości.

Szczegółowość weryfikacji	Wartość validationGranularity PREMISE jest często akceptowalna, ale wartość ROUTE może nadal wskazywać adres, pod który można dostarczyć przesyłkę.
Brak danych wywnioskowanych	Jeśli pole hasInferredComponents ma wartość false, wiesz, że w danych wyjściowych nie wywnioskowano żadnych komponentów.
Brak zastąpionych danych	Jeśli pole hasReplacedComponents ma wartość false, wiesz, że żadne dane wejściowe nie zostały zastąpione.
Brak korekty pisowni	Jeśli pole hasSpellCorrectedComponents ma wartość false, wiesz, że nie wprowadzono żadnych poprawek pisowni.
Potwierdzenie USPS DPV	Jeśli uspsData.dpvConfirmation to 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 Praca z adresami w Stanach Zjednoczonych.

Przykłady adresów do zaakceptowania