Neste documento, descrevemos um processo para criar um sistema de verificação de endereços que processa várias respostas da API Address Validation. Ele aborda como criar sua lógica para usar a resposta corretamente, investigar outros indicadores da API e quando e como solicitar mais informações aos clientes.
Em geral, a resposta da API determina as seguintes maneiras de o sistema lidar com um endereço:
- Correção: o endereço é de baixa qualidade. Você deve pedir mais informações.
- Confirm: o endereço é de alta qualidade, mas tem mudanças em relação ao endereço de entrada. Você pode solicitar confirmação.
- Aceitar: o endereço é de alta qualidade. Você pode aceitar o endereço fornecido.
Finalidade de chave
Este documento ajuda você a modificar seu sistema para analisar melhor a resposta da API e determinar as próximas ações a serem tomadas com os endereços fornecidos. O pseudocódigo a seguir ilustra um fluxo possível.
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.
A lógica exata depende da sua situação. Consulte as orientações de implementação para mais detalhes. Você também pode usar nossa implementação de código aberto dessa lógica, que está na Biblioteca de componentes estendida.
Visão geral do fluxo de trabalho
A tabela abaixo resume duas ações para seu sistema:
- O fluxo de trabalho a ser usado com base no comportamento de correção, confirmação e aceitação.
- Os primeiros indicadores a serem verificados na resposta. Os indicadores descritos aqui vêm da propriedade
verdicte não são os únicos a serem verificados, mas fornecem um indicador inicial da qualidade do endereço. Cada tipo de comportamento corresponde a uma seção neste documento que descreve outros indicadores que talvez você também precise investigar.
| O comportamento do sistema | |||
|---|---|---|---|
| Corrigir o endereço |
A resposta do
|
||
| Confirme o endereço |
A resposta do
|
||
| Aceitar o endereço |
A resposta da API Address Validation indica um endereço de excelente qualidade.
|
||
Diretrizes para implementação
Ao projetar como seu sistema responde aos indicadores de validação de endereço, as recomendações a seguir podem ajudar você a criar um modelo de resposta mais eficaz. No entanto, essas são apenas recomendações. Lembre-se de que sua implementação precisa ser adequada ao seu modelo de negócios.
| Orientação | Detalhes | |
|---|---|---|
| Nível de risco |
Considere o nível de tolerância da sua situação ao equilibrar a solicitação de correções e a aceitação do endereço inserido. |
A API Address Validation retorna vários indicadores que podem ser incorporados ao seu nível de risco para otimizar o processo de validação. Por exemplo, se um endereço tiver um número de rua não confirmado, você ainda poderá aceitá-lo. Por outro lado, se a operação comercial exigir maior precisão de endereço, você poderá solicitar ao usuário. Para ver um exemplo que pode se enquadrar em qualquer uma das categorias, consulte Número de rua não confirmado fora dos EUA em Aceitar endereço: exemplos. |
| Aceitar endereços |
É uma prática recomendada permitir que o sistema aceite a entrada original se o cliente não responder às solicitações. |
Nesses casos, o cliente pode ter inserido um endereço que não está no sistema, como uma nova construção. |
Corrigir um endereço
Corrija um endereço quando os resultados indicarem claramente que ele não é entregável. O sistema pode solicitar que o cliente forneça as informações necessárias. Depois disso, você pode reemitir o fluxo de trabalho para receber um endereço de entrega.
Corrigir indicadores
A API Address Validation fornece vários indicadores para informar se um endereço precisa ser corrigido.
1. Granularidade da validação e componentes ausentes
Estes dois indicadores são os melhores para identificar um endereço problemático:
- Sempre que o campo
validationGranularityforOTHER, seu sistema precisará investigar os indicadores de componentes de endereço para saber mais sobre onde o erro ocorreu e como corrigi-lo. - Sempre que o objeto
addresspós-processado retornar um campomissingComponentTypes, seu sistema precisará verificar esse componente. A falta de componentes também torna um endereço incompleto e não entregável.
2. Outros indicadores
A API Address Validation também fornece outros indicadores para ajudar a diagnosticar problemas específicos:
| Componentes suspeitos | Quando o tipo enumerado do nível de confirmação de um componente é
UNCOMFIRMED_AND_SUSPICIOUS, é provável que o componente esteja
incorreto.
|
|---|---|
| Componente não resolvido | Um unresolvedToken é uma parte da entrada que não é reconhecida como uma parte válida de um endereço. |
3. Indicadores de endereço dos EUA
Alguns campos aplicáveis apenas a endereços dos EUA fornecem um indicador útil de que o endereço não é entregável e precisa ser corrigido. Para um endereço que precisa de correção, você verá o seguinte:
dpvConfirmation
|
N, D ou vazio.
|
|---|
Para mais detalhes sobre dpvConfirmation, consulte
Processar endereços dos Estados Unidos.
Exemplos de correção de endereço
Confirmar um endereço
Você confirma um endereço quando o veredito indica que a API Address Validation inferiu ou fez mudanças nos componentes para produzir um endereço validado. Nesses casos, você tem um endereço de entrega, mas prefere ter mais confiança de que o endereço resultante é o pretendido pelo cliente.
Para fornecer ao cliente as instruções corretas, sua lógica identificaria
os componentes sinalizados pelo serviço para determinar qual ação ou sinalização a API
aplicou ao componente, como inferred, replaced ou spellCorrected.
Consulte AddressComponent na referência.
Confirmar indicadores
A API Address Validation fornece vários indicadores para que você saiba se um endereço precisa ser confirmado.
1. Granularidade da validação
Um validationGranularity
de ROUTE ou melhor é aceitável, mas PREMISE ou SUBPREMISE
fornece um indicador mais forte de capacidade de entrega.
2. Outros indicadores
Ao decidir confirmar a entrada de endereço com o cliente, o veredito também fornece o seguinte para determinar quais componentes investigar:
| Dados inferidos | Quando o campo
hasInferredComponents é true, você sabe que a API preencheu as informações coletadas de outros componentes de endereço.
|
|---|---|
| Dados substituídos | Quando o campo
hasReplacedComponents é true, a
API substitui os dados inseridos por dados que ela considera válidos para o endereço.
|
3. Indicadores de endereço dos EUA
Alguns campos aplicáveis apenas a endereços dos EUA indicam que sua lógica deve confirmar os detalhes com o cliente. Uma das seguintes situações se aplica:
dpvConfirmation
|
S
Para mais detalhes sobre |
|---|---|
| Resposta de endereço | Contém o campo missingComponentTypes com o valor de
subpremise.
|
Exemplos de confirmação de endereço
Aceitar um endereço
Você aceita um endereço quando o veredito oferece um alto grau de confiança de que o endereço é entregável e pode ser usado sem mais interações com o cliente no processo downstream.
Aceitar indicadores
A API Address Validation fornece vários indicadores para que você saiba se um endereço precisa ser confirmado.
1. Granularidade da validação
Um validationGranularity de PREMISE ou melhor é aceitável, mas, em alguns casos, ROUTE ainda indica um endereço de entrega.
2. Outros indicadores
Um veredito para um endereço de alta qualidade também deve fornecer o seguinte:
- Nenhum dado substituído. Nesse caso,
hasReplacedComponents: FALSE. - Nenhum componente inferido. Nesse caso,
hasInferredComponents: FALSE.
3. Indicadores de endereço dos EUA
Alguns campos aplicáveis apenas a endereços dos EUA indicam um endereço de alta qualidade que pode ser entregue. Para um endereço aceitável nos EUA, você verá o seguinte:
dpvConfirmation
|
Y
Para detalhes sobre
|
|---|