Neste documento, descrevemos um processo para criar um sistema de verificação de endereço para processar várias respostas da API Address Validation. Ele aborda como criar sua lógica para usar corretamente a resposta, investigar outros sinais da API e quando e como solicitar mais informações aos clientes.
Em geral, a resposta da API determina as seguintes maneiras pelas quais o sistema deve lidar com um endereço:
- Correção: o endereço está de baixa qualidade. Você vai precisar pedir mais informações.
- Confirmar: o endereço é de alta qualidade, mas o endereço de entrada sofre alterações. Você pode solicitar uma 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 do seu sistema:
- O fluxo de trabalho a ser usado com base no comportamento de corrigir, confirmar e aceitar.
- Os primeiros indicadores a serem verificados na resposta. Os indicadores
descritos aqui vêm da propriedade
verdict
e não são os únicos indicadores a serem verificados, mas fornecem um indicador inicial da qualidade do endereço. Cada tipo de comportamento corresponde a uma seção deste documento que descreve outros sinais que talvez você também precise investigar.
Comportamento do seu 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 qualidade excelente.
|
Diretrizes para implementação
Ao projetar como o sistema responde aos sinais da API Address Validation, as recomendações a seguir podem ajudar a criar um modelo de resposta mais eficaz. No entanto, essas são apenas recomendações. Portanto, tenha em mente que a implementação precisa estar adequada ao seu modelo de negócios.
Orientação | Detalhes | |
---|---|---|
Nível de risco |
Leve em consideração o nível de tolerância para sua situação ao equilibrar entre solicitar correções e aceitar o endereço inserido. |
A API Address Validation retorna vários indicadores que podem ser incorporados ao nível de risco para otimizar o processo de validação. Por exemplo, se um endereço tiver um número não confirmado, você ainda poderá aceitá-lo. Por outro lado, se sua 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 da rua não confirmado nos EUA em Aceitar endereço: exemplos. |
Aceitar endereços |
É uma boa prática 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 para obras novas. |
Gerar feedback |
Ao emitir novamente uma solicitação de validação de endereço, também é possível enviar uma solicitação para o endpoint |
Isso permite que o Google saiba como você lidou com a resposta final. Consulte Processar endereços atualizados. |
Corrigir um endereço
Corrija um endereço quando os resultados indicarem claramente que ele não pode ser entregue. Seu sistema pode solicitar que o cliente forneça as informações necessárias e, em seguida, você emitirá novamente o fluxo de trabalho para conseguir um endereço de entrega.
Corrigir indicadores
A API Address Validation fornece vários indicadores para que você saiba se um endereço precisa ser corrigido.
1. Granularidade de validação e componentes ausentes
Esses dois sinais são a melhor indicação de um endereço com problemas:
- Sempre que o campo
validationGranularity
forOTHER
, o sistema vai precisar investigar os sinais do componente de endereço para saber mais sobre onde o erro ocorreu e como corrigi-lo. - Sempre que o objeto
address
pós-processado retornar um campomissingComponentTypes
, o sistema precisará procurar esse componente. A falta de componentes também resulta na renderização de endereços incompleto e na entrega.
2. Outros indicadores
A API Address Validation também oferece outros sinais para ajudar a diagnosticar problemas específicos:
Componentes suspeitos | Quando o tipo enumerado de nível de confirmação de um componente é
UNCOMFIRMED_AND_SUSPICIOUS , é provável que o componente esteja
incorreto.
|
---|---|
Componente não resolvido | Um unresolvedToken faz parte da entrada não reconhecida como parte válida de um endereço. |
3. Indicadores de endereço dos EUA
Alguns campos aplicáveis apenas a endereços dos EUA oferecem um sinal útil de que o endereço não pode ser entregue e precisa ser corrigido. Para um endereço que requer correção, você verá o seguinte:
dpvConfirmation
|
N , D ou vazio.
|
---|
Para detalhes sobre dpvConfirmation
, consulte
Processar endereços nos Estados Unidos.
Corrigir exemplos de endereços
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 gerar um endereço validado. Nesses casos, você tem um endereço de entrega, mas prefere mais confiança de que o endereço resultante é o pretendido pelo cliente.
Para fornecer a solicitação correta ao cliente, sua lógica identificaria
os componentes sinalizados pelo serviço para determinar qual ação ou sinalização a API
aplicada 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 de validação
Um validationGranularity
de ROUTE
ou superior é aceitável, mas
PREMISSÃO ou SUBPREMISSÃO oferecem um sinal mais forte 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 está como true , a API substituiu os dados inseridos pelos dados considerados 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 precisa confirmar os detalhes com o cliente. Uma das seguintes opções se aplica:
dpvConfirmation
|
S
Para detalhes sobre |
---|---|
Resposta do endereço | Contém o campo missingComponentType com o valor de
subpremise .
|
Confirmar exemplos de endereço
Aceitar um endereço
Você aceita um endereço quando o veredito fornece um alto grau de confiança de que o endereço pode ser entregue e pode ser usado sem mais interação do 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 de validação
Um validationGranularity
de PREMISE
ou superior é 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 precisa 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 para entrega. Para um endereço aceitável nos EUA, você verá o seguinte:
dpvConfirmation
|
Y
Para detalhes sobre |
---|