Crea la tua logica di convalida

Questo documento descrive una procedura per creare un sistema di controllo degli indirizzi per gestire una serie di risposte dell'API Address Validation. Spiega come interpretare la risposta dell'API per determinare quando e come richiedere ai clienti ulteriori informazioni.

In generale, la risposta dell'API determina i seguenti modi in cui il sistema deve gestire un indirizzo:

  • Correggi: l'indirizzo potrebbe contenere problemi significativi.
    Valuta la possibilità di chiedere al cliente ulteriori informazioni.
  • Aggiungi unità secondaria: l'indirizzo potrebbe non includere un'unità secondaria.
    Valuta la possibilità di chiedere al cliente di aggiungere un numero di unità.
  • Conferma: l'indirizzo potrebbe contenere problemi minori.
    Valuta la possibilità di chiedere al cliente di confermare che l'indirizzo sia corretto.
  • Accetta: l'indirizzo potrebbe non contenere problemi.
    Prendi in considerazione l'utilizzo dell'indirizzo senza ulteriori prompt, a tuo rischio e pericolo.

Scopo principale

Questo documento ti aiuta a modificare il sistema per analizzare al meglio la risposta dell'API e determinare le azioni successive da intraprendere con gli indirizzi forniti. Il seguente pseudocodice illustra un possibile flusso.

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.

La logica esatta dipende dalla tua situazione. Per ulteriori dettagli, consulta la sezione Personalizzare la logica di convalida.

Flussi di lavoro di esempio

La tabella seguente riassume i flussi di lavoro di esempio che potresti implementare per richiedere al tuo cliente in base alla risposta dell'API.

Comportamento del sistema
Correggi l'indirizzo

La risposta di verdict indica che potrebbero esserci problemi significativi con l'indirizzo. Ad esempio, verdict.possibleNextAction è FIX. Valuta la possibilità di chiedere al tuo cliente ulteriori informazioni.

Flusso di lavoro

  1. Se necessario, esamina i componenti dell'indirizzo.
  2. Chiedi al cliente di risolvere i problemi relativi all'indirizzo.
  3. Richiedi la convalida dell'indirizzo aggiornato.
  4. (Facoltativo) Invia una richiesta all'endpoint di feedback per l'API. Consulta Gestire gli indirizzi aggiornati.
  5. Procedi con l'indirizzo.
Aggiungi sedi secondarie

La risposta di verdict indica che all'indirizzo potrebbe mancare un'unità secondaria. Ad esempio, verdict.possibleNextAction è CONFIRM_ADD_SUBPREMISES. Valuta la possibilità di chiedere al cliente di aggiungere un numero di unità.

Flusso di lavoro

  1. Chiedi al cliente di aggiungere un numero di unità.
  2. Richiedi la convalida dell'indirizzo aggiornato.
  3. (Facoltativo) Invia una richiesta all'endpoint di feedback per l'API. Consulta Gestire gli indirizzi aggiornati.
  4. Procedi con l'indirizzo.
Conferma l'indirizzo

La risposta di verdict indica che potrebbero esserci problemi minori con l'indirizzo. Ad esempio, verdict.possibleNextAction è CONFIRM. Valuta la possibilità di chiedere al cliente di controllare l'indirizzo.

Flusso di lavoro

  1. Correzioni necessarie:
    1. Se necessario, esamina i componenti dell'indirizzo.
    2. Richiedi la convalida dell'indirizzo aggiornato.
    3. (Facoltativo) Invia una richiesta all'endpoint di feedback per l'API. Consulta Gestire gli indirizzi aggiornati.
    4. Procedi con l'indirizzo.
  2. Nessuna correzione necessaria:
    1. (Facoltativo) Invia una richiesta all'endpoint di feedback per l'API. Consulta Gestire gli indirizzi aggiornati.
    2. Procedi con l'indirizzo.
Accetta l'indirizzo

La risposta di verdict indica che potrebbero non esserci problemi con l'indirizzo. Ad esempio, verdict.possibleNextAction è ACCEPT. Valuta la possibilità di procedere con l'indirizzo come faresti per il tuo livello di rischio.

Flusso di lavoro

Procedi con l'indirizzo restituito.

Personalizzare la logica di convalida

Sebbene tu possa utilizzare i risultati del campo verdict.possibleNextAction per determinare come il sistema procede con la risposta API, potresti anche valutare la possibilità di creare una logica personalizzata, ad esempio per gestire esigenze specifiche dell'attività.

Lo scopo di questa sezione è illustrare come sviluppare una logica personalizzata per interpretare la risposta dell'API al fine di determinare se e come vuoi sollecitare il cliente. Questa sezione illustra i livelli di rischio e gli indicatori di risposta API aggiuntivi da considerare per la personalizzazione.

Ciò detto, anche se ti affidi esclusivamente al verdict.possibleNextAction per decidere i passaggi successivi, gli indicatori aggiuntivi descritti di seguito possono comunque aiutarti a comprendere i dettagli relativi a potenziali problemi con l'indirizzo.

Tolleranza di rischio

Quando progetti il modo in cui il sistema risponde ai segnali dell'API Address Validation, i seguenti consigli possono aiutarti a creare un modello di risposta più efficace. Tuttavia, questi sono solo consigli, quindi tieni presente che la tua implementazione deve essere adatta al tuo modello di business.

Consulenza Dettagli
Livello di rischio

Tieni conto del livello di tolleranza per la tua situazione quando trovi un equilibrio tra la richiesta di correzioni e l'accettazione dell'indirizzo così come è stato inserito.

L'API Address Validation restituisce una serie di indicatori che puoi incorporare nel tuo livello di rischio per ottimizzare il processo di convalida.

Ad esempio, se un indirizzo ha un numero civico non confermato, puoi comunque accettarlo. D'altra parte, se la tua attività richiede una maggiore precisione dell'indirizzo, potresti chiedere all'utente. Per un esempio che potrebbe rientrare in una delle due categorie, vedi Numero civico non confermato non statunitense in Accetta indirizzo - esempi.
Accetta indirizzi

È buona norma consentire al sistema di accettare la voce originale se il cliente non risponde alle richieste.

In questi casi, il cliente potrebbe aver inserito un indirizzo non presente nel sistema, ad esempio per una nuova costruzione.

Esempio di flusso di pagamento con avversione al rischio

Se vuoi ridurre il rischio di mancate consegne, puoi personalizzare la tua logica per sollecitare i tuoi clienti più spesso. Ad esempio, anziché utilizzare la logica descritta nella sezione Scopo principale, potresti utilizzare la seguente logica.

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.

Esempio di flusso di pagamento con pochi problemi

Se vuoi ridurre l'attrito nel flusso di pagamento, puoi personalizzare la logica per chiedere ai clienti meno spesso. Ad esempio, anziché utilizzare la logica descritta nella sezione Scopo principale, potresti utilizzare la seguente logica.

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.

Indicatori FIX

Correggere un indirizzo quando i risultati indicano chiaramente che potrebbe non essere recapitabile. Il sistema può quindi chiedere al cliente di fornire le informazioni necessarie, dopodiché puoi riemettere il flusso di lavoro per ottenere un indirizzo di consegna.

I seguenti campi della risposta dell'API Address Validation possono essere utilizzati in aggiunta a verdict.possibleNextAction per determinare se un indirizzo presenta problemi gravi e quali sono.

Granularità della convalida Quando l'enumerazione della granularità di convalida per un indirizzo è OTHER, è probabile che l'indirizzo non sia corretto.
Componenti mancanti Quando address.missingComponentTypes non è vuoto, è probabile che nell'indirizzo manchino informazioni importanti.
Componenti sospetti Quando l'enumerazione del livello di conferma per un componente è UNCONFIRMED_AND_SUSPICIOUS, è probabile che il componente non sia corretto.
Componenti non risolti Un unresolvedToken è una parte dell'input non riconosciuta come parte valida di un indirizzo.
Conferma DPV USPS Quando uspsData.dpvConfirmation è N o vuoto, potrebbe esserci un problema con l'indirizzo. Questo campo è disponibile solo per gli indirizzi negli Stati Uniti. Per maggiori dettagli su uspsData.dpvConfirmation, vedi Gestire gli indirizzi degli Stati Uniti.

Esempi di correzione dell'indirizzo

Indicatori CONFIRM_ADD_SUBPREMISES (solo indirizzi statunitensi)

Inviti il cliente a rivedere l'indirizzo e a valutare la possibilità di aggiungere un numero di unità quando la risposta dell'API Address Validation indica che l'indirizzo potrebbe non includere un'unità secondaria. In questi casi, l'indirizzo dell'edificio è probabilmente valido, ma vuoi avere maggiore certezza che l'indirizzo risultante sia quello inteso dal cliente.

Oltre a verdict.possibleNextAction, è possibile utilizzare i seguenti campi della risposta dell'API Address Validation per determinare se è probabile che un indirizzo non includa un sottopremessa.

Missing subpremise component Quando il campo address.missingComponentTypes contiene un valore subpremise, significa che nell'indirizzo manca il numero dell'unità.
Conferma DPV USPS Quando uspsData.dpvConfirmation è S, significa che il numero civico principale dell'indirizzo è stato abbinato a un indirizzo nel database USPS. Tuttavia, era previsto che l'indirizzo contenesse anche un numero secondario. Questo campo è disponibile solo per gli indirizzi negli Stati Uniti. Per maggiori dettagli su uspsData.dpvConfirmation, consulta Gestire gli indirizzi degli Stati Uniti.

Aggiungere esempi di indirizzi di unità secondarie

Indicatori CONFIRM

Confermi un indirizzo quando il verdetto indica che l'API Address Validation ha dedotto o apportato modifiche ai componenti dell'indirizzo per produrre un indirizzo convalidato. In questi casi, hai un indirizzo recapitabile, ma preferisci una maggiore certezza che l'indirizzo risultante sia quello inteso dal cliente.

I seguenti campi della risposta dell'API Address Validation possono essere utilizzati in aggiunta a verdict.possibleNextAction per determinare se un indirizzo presenta problemi minori e quali sono.

Granularità della convalida Quando validationGranularity per un indirizzo è ROUTE o PREMISE_PROXIMITY, l'indirizzo potrebbe non essere corretto.
Dati dedotti Quando il campo hasInferredComponents è true, sai che l'API ha compilato le informazioni ricavate da altri componenti dell'indirizzo.
Dati sostituiti Quando il campo hasReplacedComponents è true, l'API ha sostituito i dati inseriti con i dati che riteneva validi per l'indirizzo.
Correzioni ortografiche Quando il campo hasSpellCorrectedComponents è true, l'API ha corretto l'ortografia di alcuni componenti con errori ortografici.

Esempi di indirizzi confermati

Indicatori ACCEPT

Potresti accettare un indirizzo quando la risposta dell'API Address Validation fornisce un alto grado di certezza che l'indirizzo sia recapitabile e possa essere utilizzato senza ulteriori interazioni con il cliente nel processo downstream.

I seguenti campi della risposta dell'API Address Validation possono essere utilizzati in aggiunta a verdict.possibleNextAction per determinare se un indirizzo è di qualità accettabile.

Granularità della convalida Un validationGranularity di PREMISE è spesso accettabile, anche se un valore di ROUTE può comunque indicare un indirizzo di consegna.
Nessun dato dedotto Quando il campo hasInferredComponents è false, sai che nessun componente nell'output è stato dedotto.
Nessun dato sostituito Quando il campo hasReplacedComponents è false, sai che nessun dato di input è stato sostituito.
Nessuna correzione ortografica Quando il campo hasSpellCorrectedComponents è false, sai che non sono state apportate correzioni ortografiche.
Conferma DPV USPS Quando uspsData.dpvConfirmation è Y, significa che l'indirizzo è stato associato a un indirizzo nel database USPS. Questo campo è disponibile solo per gli indirizzi negli Stati Uniti. Per maggiori dettagli su uspsData.dpvConfirmation, vedi Gestire gli indirizzi degli Stati Uniti.

Accettare gli esempi di indirizzi

Indietro
Comprendere una risposta di base