Criar sua lógica de validação

Neste documento, descrevemos o processo de criação de um sistema de verificação de endereço para processar uma variedade de 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 maneiras a seguir pelas quais seu sistema deve lidar com um endereço:

• handyman Corrigir: o endereço tem baixa qualidade. Solicitar mais informações.
• edit Confirmar: o endereço é de alta qualidade, mas tem mudanças em relação ao endereço de entrada. É possível que você solicite confirmação.
• check Aceitar: o endereço é de alta qualidade. É possível aceitar o endereço fornecido.

Finalidade de chave

Este documento ajuda a modificar seu sistema para analisar melhor a resposta da API e determinar as próximas ações a serem realizadas 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:

1. O fluxo de trabalho a ser usado com base no comportamento de correção, confirmação e aceitação.
2. Os primeiros sinais a serem verificados na resposta. Os indicadores descritos aqui vêm da propriedade verdict e 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 sinais que você também pode precisar investigar.

Comportamento do sistema
handyman Corrigir o endereço	A resposta de verdict indica informações importantes que precisam ser fornecidas. O endereço retornado pela API Address Validation pode não ter qualidade de entrega. Fluxo de trabalho Investigue os componentes de endereço, se necessário. Solicitar que o cliente corrija os problemas. Solicite a validação para o endereço atualizado. (Opcional) Envie uma solicitação ao endpoint de feedback da API. Consulte Processar endereços atualizados. Prossiga com o endereço. Sinais de veredito Qualquer uma das seguintes opções é aplicável: validationGranularity definido como OTHER. Consulte valores de granularidade. addressComplete é false.
edit Confirme o endereço	A resposta de verdict indica um endereço de entrega, mas fez alterações na entrada original: inferir dados que tenham grafia corrigida ou dados que possam ser confirmados. Fluxo de trabalho Correções necessárias: Investigue os componentes de endereço, se necessário. Solicite a validação para o endereço atualizado. (Opcional) Envie uma solicitação ao endpoint de feedback da API. Consulte Processar endereços atualizados. Prossiga com o endereço. Nenhuma correção necessária: (Opcional) Envie uma solicitação ao endpoint de feedback da API. Consulte Processar endereços atualizados. Prossiga com o endereço. Sinais de veredito Todas as seguintes opções se aplicam: validationGranularity contém ROUTE ou mais. Consulte valores de granularidade. addressComplete é true. O campo hasInferredComponents é true OU o campo hasReplacedComponents é true.
check Aceitar o endereço	A resposta da API Address Validation indica um endereço de excelente qualidade. Fluxo de trabalho Prossiga com o endereço retornado. Sinais de veredito Todas as seguintes opções se aplicam: validationGranularity contém PREMISE ou mais. Consulte valores de granularity. addressComplete é true. Nenhum componente inferido ou substituído.

Diretrizes para implementação

Ao projetar como o sistema responde aos sinais da API Address Validation, as recomendações a seguir podem ajudar você a criar um modelo de resposta mais eficaz. No entanto, essas são apenas recomendações. Portanto, tenha em mente que sua implementação deve 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 entre a solicitação de correções e a aceitação do endereço inserido.	A API Address Validation retorna uma variedade de sinais que você pode incorporar ao seu 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 exemplos de endereço.
Aceitar endereços	É recomendável permitir que o sistema aceite a entrada original se o cliente não responder aos comandos.	Nesses casos, o cliente pode ter inserido um endereço que não está no sistema, como para uma obra nova.
Enviar feedback	Ao reemitir uma solicitação de validação de endereço, também é possível enviar uma solicitação para o endpoint provideValidationFeedback.	Isso informa ao Google 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ê emite novamente seu 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 de validação e componentes ausentes

Estes dois sinais são os melhores indicadores de um endereço problemático:

• Sempre que o campo validationGranularity for OTHER, o sistema precisará investigar os indicadores dos componentes de endereço para saber mais sobre onde o erro ocorreu e como corrigi-lo.
• Sempre que o objeto address pós-processado retorna um campo missingComponentTypes, o sistema precisa verificar esse componente. Componentes ausentes também renderizam um endereço incompleto e não entregue.

2. Outros indicadores

A API Address Validation também fornece os 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. Sinais 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 dos Estados Unidos.

Corrigir exemplos de endereço

Confirmar um endereço

Você confirma um endereço quando o veredito indica que a API Address Validation foi inferida ou feita mudanças nos componentes de endereço para produzir um endereço validado. Nesses casos, você tem um endereço de entrega, mas prefere ter maior 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 aplicada ao componente, como inferred, replaced ou spellCorrected. Consulte AddressComponent na referência.

Confirmar indicadores

A API Address Validation fornece vários sinais para informar se um endereço precisa ser confirmado.

1. Granularidade de validação

Um validationGranularity de ROUTE ou melhor é aceitável, mas PREMISE ou SUBPREMISE oferece 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 serão investigados:

Dados inferidos	Quando o campo hasInferredComponents for true, você saberá 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 considerados válidos.

3. Sinais 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. Qualquer uma das seguintes condições se aplica:

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

Confirmar exemplos de endereço

Aceitar um endereço

Um endereço é aceito quando o veredito fornece um alto grau de confiança de que ele pode ser entregue e pode ser usado sem mais interações com o cliente no processo downstream.

Aceitar indicadores

A API Address Validation fornece vários sinais para informar se um endereço precisa ser confirmado.

1. Granularidade de validação

Um validationGranularity igual ou superior a PREMISE é 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 incluir o seguinte:

• Nenhum dado substituído. Nesse caso, hasReplacedComponents: FALSE.
• Nenhum componente inferido. Nesse caso, hasInferredComponents: FALSE.

3. Sinais 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 dpvConfirmation, consulte Processar endereços dos Estados Unidos.

Aceitar exemplos de endereço