Criar sua lógica de validação

Este documento descreve um processo para criar um sistema de verificação de endereços para processar 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 pedir mais informações aos clientes.

Em geral, a resposta da API determina as seguintes maneiras de processar um endereço:

  • Corrigir: o endereço tem baixa qualidade. Você precisa pedir mais informações.
  • Confirmar: o endereço é de alta qualidade, mas tem mudanças em relação ao endereço de entrada. Talvez seja necessário confirmar.
  • 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 possível fluxo.

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:

  1. O fluxo de trabalho a ser usado com base no comportamento "corrigir, confirmar e aceitar".
  2. 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 neste documento que descreve outros indicadores que você também pode precisar investigar.
Comportamento do sistema
Corrigir o endereço

A resposta do verdict indica informações importantes ausentes que precisam ser fornecidas. O endereço retornado pela API Address Validation pode não ter qualidade suficiente para entrega.

Fluxo de trabalho

  1. Investigue os componentes do endereço, se necessário.
  2. Peça ao cliente para corrigir os problemas de endereço.
  3. Solicite a validação do endereço atualizado.
  4. (Opcional) Envie uma solicitação para o endpoint de feedback da API. Consulte Processar endereços atualizados.
  5. Prossiga com o endereço.

Indicadores de veredito

Qualquer das seguintes condições se aplica:
Confirmar o endereço

A resposta do verdict indica um endereço de entrega, mas fez mudanças na entrada original: infere dados corrigidos ou dados que podem ser confirmados.

Fluxo de trabalho

  1. Correções necessárias:
    1. Investigue os componentes do endereço, se necessário.
    2. Solicite a validação do endereço atualizado.
    3. (Opcional) Envie uma solicitação para o endpoint de feedback da API. Consulte Processar endereços atualizados.
    4. Prossiga com o endereço.
  2. Nenhuma correção é necessária:
    1. (Opcional) Envie uma solicitação para o endpoint de feedback da API. Consulte Processar endereços atualizados.
    2. Prossiga com o endereço.

Indicadores de veredito

Todas as seguintes condições são aplicáveis:

  • validationGranularity contém ROUTE ou melhor. Consulte os valores de granularidade.
  • addressComplete é true.
  • O campo hasInferredComponents é true OU o campo hasReplacedComponents é true.
Aceitar o endereço

A resposta da API Address Validation indica um endereço de excelente qualidade.

Fluxo de trabalho

Continuar com o endereço de devolução.

Indicadores de veredito

Todas as seguintes condições são aplicáveis:

  • validationGranularity contém PREMISE ou melhor. Consulte os valores de granularidade.
  • addressComplete é true.
  • Nenhum componente inferido ou substituído.

Diretrizes para implementação

Ao projetar como seu sistema responde a 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, lembre-se de que a implementação precisa se adequar ao seu modelo de negócios.

Orientação Detalhes
Nível de risco

Considere o nível de tolerância para sua situação ao equilibrar as solicitações de correção e a aceitação do endereço conforme 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 da rua não confirmado, você ainda poderá aceitá-lo. Por outro lado, se a operação da sua empresa exigir uma precisão maior do endereço, você pode solicitar ao usuário. Para conferir um exemplo que se encaixa 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 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 o de uma construção nova.
Enviar feedback

Ao emitir novamente uma solicitação de validação de endereço, você também pode enviar uma solicitação para o endpoint provideValidationFeedback.

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. Depois disso, você pode emitir novamente o fluxo de trabalho para receber um endereço entregue.

Corrigir indicadores

A API Address Validation oferece 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 indicar um endereço com problemas:

  • Sempre que o campo validationGranularity for OTHER, o sistema vai investigar os indicadores de componentes do endereço para saber onde o erro ocorreu e como corrigi-lo.
  • Sempre que o objeto address pós-processado retornar um campo missingComponentTypes, o sistema vai verificar esse componente. Os componentes ausentes também fazem com que um endereço seja incompleto e não entregue.

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 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 é uma parte da entrada que 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 fornecem um indicador útil de que o endereço não pode ser entregue e precisa ser corrigido. Para um endereço que precisa ser corrigido, você verá o seguinte:

dpvConfirmation N, D ou vazio.

Para saber mais 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 inferia ou fez mudanças nos componentes do endereço para produzir um endereço validado. Nesses casos, você tem um endereço entregável, mas prefere ter mais confiança de que o endereço resultante é o pretendido pelo cliente.

Para fornecer ao cliente a solicitação correta, 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 oferece vários indicadores para informar 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 do 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 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 para tornar o endereço válido.

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 condições se aplica:

dpvConfirmation S

Para saber mais sobre dpvConfirmation, consulte Processar endereços dos Estados Unidos.
Resposta do endereço Contém o campo missingComponentType com o valor de subpremise.

Exemplos de confirmação 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 usado sem mais interação do cliente no processo de downstream.

Aceitar indicadores

A API Address Validation oferece vários indicadores para informar 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 entregável.

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 que pode ser entregue. Para um endereço aceitável nos EUA, você verá o seguinte:

dpvConfirmation Y

Para saber mais sobre dpvConfirmation, consulte Processar endereços dos Estados Unidos.

Aceitar exemplos de endereço

Anterior
Compreender uma resposta básica