Crea la 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 creare la logica per utilizzare correttamente la risposta, come esaminare altri indicatori dell'API e quando e come chiedere ai clienti maggiori informazioni.

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

  • Correggi: l'indirizzo è di bassa qualità. Dovresti chiedere ulteriori informazioni.
  • Conferma: l'indirizzo è di alta qualità, ma presenta modifiche rispetto all'indirizzo inserito. Potrebbe essere richiesta una conferma.
  • Accetta: l'indirizzo è di alta qualità. Puoi accettare l'indirizzo fornito.

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 (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.

La logica esatta dipende dalla tua situazione. Per ulteriori dettagli, consulta la guida all'implementazione. Puoi anche utilizzare la nostra implementazione open source di questa logica, che si trova nella libreria di componenti estesa.

Panoramica del flusso di lavoro

La tabella seguente riassume due azioni per il tuo sistema:

  1. Il flusso di lavoro da utilizzare in base al comportamento correggi, conferma, accetta.
  2. I primi indicatori da controllare nella risposta. Gli indicatori descritti qui provengono dalla proprietà verdict e non sono gli unici indicatori da controllare, ma forniscono un indicatore iniziale della qualità dell'indirizzo. Ogni tipo di comportamento corrisponde a una sezione di questo documento che descrive ulteriori indicatori che potresti dover esaminare.
Comportamento del sistema
Correggi l'indirizzo

La risposta di verdict indica informazioni importanti mancanti che devono essere fornite. L'indirizzo restituito dall'API potrebbe non essere di qualità idonea per la consegna.

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. Procedi con l'indirizzo.

Indicatori del verdetto

Una delle seguenti condizioni:
Conferma l'indirizzo

La risposta da verdict indica un indirizzo di consegna, ma ha apportato modifiche all'input originale: deducendo dati con correzione ortografica o dati che possono essere confermati.

Flusso di lavoro

  1. Correzioni necessarie:
    1. Se necessario, esamina i componenti dell'indirizzo.
    2. Richiedi la convalida dell'indirizzo aggiornato.
    3. Procedi con l'indirizzo.
  2. Nessuna correzione necessaria:
  3. Procedi con l'indirizzo.

Indicatori del verdetto

Tutti i seguenti punti sono validi:
Accetta l'indirizzo

La risposta dell'API Address Validation indica un indirizzo di qualità eccellente.

Flusso di lavoro

Procedi con l'indirizzo restituito.

Indicatori del verdetto

Tutti i seguenti punti sono validi:

Linee guida per l'implementazione

Quando progetti la modalità di risposta del sistema ai segnali di convalida dell'indirizzo, i seguenti suggerimenti 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.

Correggere un indirizzo

Correggere un indirizzo quando i risultati indicano chiaramente che non è possibile effettuare la consegna. 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.

Correggere gli indicatori

L'API Address Validation fornisce una serie di indicatori per farti sapere se un indirizzo deve essere corretto.

1. Granularità della convalida e componenti mancanti

Questi due indicatori forniscono la migliore indicazione di un indirizzo problematico:

  • Ogni volta che il campo validationGranularity è OTHER, il sistema deve analizzare gli indicatori dei componenti dell'indirizzo per scoprire di più su dove si è verificato l'errore e come risolverlo.
  • Ogni volta che l'oggetto address post-elaborato restituisce un campo missingComponentTypes, il sistema deve verificare la presenza di questo componente. Anche i componenti mancanti rendono un indirizzo incompleto e non consegnabile.

2. Altri indicatori

L'API Address Validation fornisce anche gli altri indicatori per aiutarti a diagnosticare problemi specifici:

Componenti sospetti Quando l'enumerazione del livello di conferma per un componente è UNCOMFIRMED_AND_SUSPICIOUS, è probabile che il componente non sia corretto.
Componente non risolto Un unresolvedToken è una parte dell'input non riconosciuta come parte valida di un indirizzo.

3. Indicatori di indirizzo negli Stati Uniti

Alcuni campi applicabili solo agli indirizzi statunitensi forniscono un segnale utile che indica che l'indirizzo non è recapitabile e deve essere corretto. Per un indirizzo che richiede una correzione, dovresti visualizzare quanto segue:

dpvConfirmation N, D o vuoto.

Per informazioni dettagliate su dpvConfirmation, vedi Gestire gli indirizzi degli Stati Uniti.

Correggere gli esempi di indirizzo

Confermare un indirizzo

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.

Per fornire al cliente il prompt corretto, la tua logica identificherebbe i componenti segnalati dal servizio per determinare quale azione o flag l'API ha applicato al componente, ad esempio inferred, replaced o spellCorrected. Consulta AddressComponent nel riferimento.

Conferma indicatori

L'API Address Validation fornisce una serie di indicatori per farti sapere se un indirizzo deve essere confermato.

1. Granularità della convalida

Un validationGranularity di ROUTE o superiore è accettabile, ma PREMISE o SUBPREMISE forniscono un segnale più forte di recapitabilità.

2. Altri indicatori

Quando decidi di confermare l'inserimento dell'indirizzo con il cliente, il verdetto fornisce anche quanto segue per determinare quali componenti esaminare:

Dati dedotti Quando il campo hasInferredComponents è true, sai che l'API ha compilato le informazioni raccolte 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.

3. Indicatori di indirizzo negli Stati Uniti

Alcuni campi applicabili solo agli indirizzi statunitensi indicano che la tua logica deve confermare i dettagli con il cliente. Si verifica una delle seguenti condizioni:

dpvConfirmation S

Per informazioni dettagliate su dpvConfirmation, vedi Gestire gli indirizzi degli Stati Uniti.
Risposta all'indirizzo Contiene il campo missingComponentTypes con il valore subpremise.

Esempi di indirizzi confermati

Accettare un indirizzo

Accetti un indirizzo quando il risultato fornisce un elevato grado di certezza che l'indirizzo è recapitabile e può essere utilizzato senza ulteriori interazioni con il cliente nel processo downstream.

Accettare i segnali

L'API Address Validation fornisce una serie di indicatori per farti sapere se un indirizzo deve essere confermato.

1. Granularità della convalida

Un validationGranularity di PREMISE o superiore è accettabile, ma in alcuni casi, ROUTE indica comunque un indirizzo di consegna.

2. Altri indicatori

Il verdetto per un indirizzo di alta qualità deve fornire anche quanto segue:

  • Nessun dato sostituito. In questo caso, hasReplacedComponents: FALSE.
  • Nessun componente dedotto. In questo caso, hasInferredComponents: FALSE.

3. Indicatori di indirizzo negli Stati Uniti

Alcuni campi applicabili solo agli indirizzi statunitensi indicano un indirizzo di alta qualità a cui è possibile effettuare la consegna. Per un indirizzo statunitense accettabile, dovresti vedere quanto segue:

dpvConfirmation Y

Per informazioni dettagliate su dpvConfirmation, consulta Gestire gli indirizzi degli Stati Uniti.

Accettare gli esempi di indirizzi