Compila la lógica de validación

En este documento, se describe un proceso para compilar un sistema de verificación de direcciones que controle una variedad de respuestas de la API de Address Validation. En ella, se explica cómo compilar tu lógica para usar correctamente la respuesta, investigar otros indicadores de la API y cuándo y cómo solicitarles más información a tus clientes.

En general, la respuesta de la API determina las siguientes formas en que tu sistema debe controlar una dirección:

  • Solución: La dirección es de baja calidad. Debes solicitar más información.
  • Confirmar: La dirección es de alta calidad, pero tiene cambios con respecto a la dirección de entrada. Es posible que solicites confirmación.
  • Aceptar: La dirección es de alta calidad. Puedes aceptar la dirección proporcionada.

Propósito clave

En este documento, encontrarás ayuda para modificar tu sistema y analizar mejor la respuesta de la API y determinar las próximas acciones que debes realizar con las direcciones proporcionadas. En el siguiente pseudcódigo, se ilustra un posible flujo.

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 lógica exacta depende de tu situación. Consulta la Guía de implementación para obtener más detalles. También puedes usar nuestra implementación de código abierto de esta lógica, que se encuentra en la Biblioteca de componentes extendidos.

Descripción general del flujo de trabajo

En la siguiente tabla, se resumen dos acciones para tu sistema:

  1. El flujo de trabajo que se usará según el comportamiento de corrección, confirmación y aceptación.
  2. Los primeros indicadores que se deben verificar en la respuesta. Los indicadores que se describen aquí provienen de la propiedad verdict y no son los únicos indicadores que se deben verificar, pero proporcionan un indicador inicial de la calidad de la dirección. Cada tipo de comportamiento corresponde a una sección de este documento en la que se describen otros indicadores que también podrías necesitar investigar.
El comportamiento de tu sistema
Cómo corregir la dirección

La respuesta de verdict indica información importante que falta y que se debe proporcionar. Es posible que la dirección devuelta por la API de Address Validation no tenga la calidad de entregable.

Flujo de trabajo

  1. Investiga los componentes de la dirección si es necesario.
  2. Pídele al cliente que solucione los problemas relacionados con la dirección.
  3. Solicita la validación de la dirección actualizada.
  4. Envía una solicitud al extremo de comentarios de la API (opcional). Consulta Cómo controlar las direcciones actualizadas.
  5. Continúa con la dirección.

Indicadores de veredicto

Alguna de las siguientes situaciones:

Confirmar la dirección

La respuesta de verdict indica una dirección de entrega, pero realizó cambios en la entrada original: infiere datos que se corrigieron ortográficamente o datos que se pueden confirmar.

Flujo de trabajo

  1. Correcciones necesarias:
    1. Investiga los componentes de la dirección si es necesario.
    2. Solicita la validación de la dirección actualizada.
    3. (Opcional) Envía una solicitud al extremo de comentarios de la API. Consulta Cómo controlar las direcciones actualizadas.
    4. Continúa con la dirección.
  2. No se necesitan correcciones:
    1. Envía una solicitud al extremo de comentarios de la API (opcional). Consulta Cómo controlar las direcciones actualizadas.
    2. Continúa con la dirección.

Indicadores de veredicto

Se cumplen todos los siguientes requisitos:

  • validationGranularity contiene ROUTE o una versión superior. Consulta los valores de granularidad.
  • addressComplete es true.
  • El campo hasInferredComponents es true O el campo hasReplacedComponents es true.
Aceptar la dirección

La respuesta de la API de Address Validation indica una dirección de excelente calidad.

Flujo de trabajo

Continúa con la dirección de devolución.

Indicadores de veredicto

Se cumplen todos los siguientes requisitos:

  • validationGranularity contiene PREMISE o una versión superior. Consulta los valores de detallado.
  • addressComplete es true.
  • No se infirieron ni reemplazaron componentes.

Asesoramiento para la implementación

Cuando diseñas la manera en que tu sistema responde a las señales de la API de Address Validation, las siguientes recomendaciones pueden ayudarte a crear un modelo de respuesta más eficaz. Sin embargo, estas son solo recomendaciones, por lo que debes tener en cuenta que tu implementación debe adaptarse a tu modelo de negocio.

Orientación Detalles
Nivel de riesgo

Ten en cuenta el nivel de tolerancia a la situación cuando generes el equilibrio entre solicitar correcciones y aceptar la dirección tal como se ingresó.

La API de Address Validation muestra una variedad de indicadores que puedes incorporar a tu nivel de riesgo para optimizar el proceso de validación.

Por ejemplo, si una dirección tiene un número de calle no confirmado, puedes aceptarla. Por otro lado, si la operación de tu empresa requiere una mayor precisión en la dirección, puedes solicitarle al usuario que la proporcione. Para ver un ejemplo que podría pertenecer a cualquiera de las categorías, consulta Número de calle no confirmado fuera de EE.UU. en Ejemplos de direcciones aceptadas.

Aceptar direcciones

Se recomienda permitir que el sistema acepte la entrada original si el cliente no responde a las indicaciones.

En estos casos, es posible que el cliente haya ingresado una dirección que no está en el sistema, como en el caso de una construcción nueva.

Proporcionar comentarios

Cuando vuelvas a emitir una solicitud de validación de dirección, también puedes enviar una solicitud al extremo provideValidationFeedback.

Esto permite que Google sepa cómo manejaste la respuesta final en última instancia. Consulta Cómo controlar las direcciones actualizadas.

Corregir una dirección

Corrige una dirección cuando los resultados indiquen claramente que no se puede entregar. Luego, tu sistema puede solicitarle al cliente que proporcione la información necesaria y, después, volver a emitir tu flujo de trabajo para obtener una dirección de entrega.

Cómo corregir indicadores

La API de Address Validation proporciona una serie de indicadores para informarte si se debe corregir una dirección.

1. Nivel de detalle de la validación y componentes faltantes

Estos dos indicadores proporcionan la mejor indicación de una dirección problemática:

  • Cada vez que el campo validationGranularity sea OTHER, el sistema debe investigar los indicadores de componentes de dirección para obtener más información sobre dónde se produjo el error y cómo corregirlo.
  • Cada vez que el objeto address procesado después muestra un campo missingComponentTypes, el sistema debe buscar ese componente. Los componentes faltantes también hacen que una dirección esté incompleta y no se pueda entregar.

2. Otros indicadores

La API de Address Validation también proporciona los otros indicadores para ayudar a diagnosticar problemas específicos:

Componentes sospechosos Cuando el nivel de confirmación enum de un componente es UNCOMFIRMED_AND_SUSPICIOUS, es probable que el componente sea incorrecto.
Componente sin resolver Un unresolvedToken es una parte de la entrada que no se reconoce como parte válida de una dirección.

3. Indicadores de direcciones de EE.UU.

Algunos campos que solo se aplican a direcciones de EE.UU. proporcionan un indicador útil de que la dirección no se puede entregar y debe corregirse. En el caso de una dirección que requiera corrección, deberías ver lo siguiente:

dpvConfirmation Puede ser N, D o vacío.

Para obtener detalles sobre dpvConfirmation, consulta Cómo administrar direcciones de Estados Unidos.

Ejemplos de direcciones corregidas

Cómo confirmar una dirección

La confirmación de una dirección se confirma cuando el veredicto indica que la API de Address Validation infirió o realizó cambios en los componentes de dirección para producir una dirección validada. En estos casos, tienes una dirección de entrega, pero prefieres tener una mayor confianza de que la dirección resultante es la que el cliente desea.

Para proporcionarle al cliente la indicación correcta, tu lógica identificaría los componentes marcados por el servicio para determinar qué acción o marca aplicó la API al componente, como inferred, replaced o spellCorrected. Consulta AddressComponent en la referencia.

Confirma los indicadores

La API de Address Validation proporciona una serie de indicadores para informarte si se debe confirmar una dirección.

1. Nivel de detalle de la validación

Un validationGranularity de ROUTE o mejor es aceptable, pero tanto PREMISE como SUBPREMISE proporcionan un indicador de entrega más sólido.

2. Otros indicadores

Cuando decidas confirmar la entrada de la dirección con el cliente, el veredicto también proporciona la siguiente información para determinar qué componentes investigar:

Datos inferidos Cuando el campo hasInferredComponents es true, sabes que la API completó la información que recopiló de otros componentes de la dirección.
Datos reemplazados Cuando el campo hasReplacedComponents es true, la API reemplaza los datos ingresados por los datos que consideró para que la dirección sea válida.

3. Indicadores de dirección de EE.UU.

Ciertos campos que solo se aplican a las direcciones de EE.UU. indican que tu lógica debe confirmar los detalles con el cliente. Se aplica alguna de las siguientes opciones:

dpvConfirmation S

Para obtener detalles sobre dpvConfirmation, consulta Cómo administrar direcciones de Estados Unidos.

Cómo responder Contiene el campo missingComponentType con el valor de subpremise.

Ejemplos de direcciones confirmadas

Cómo aceptar una dirección

Se acepta una dirección cuando el veredicto proporciona un alto grado de confianza en que la dirección es entregable y se puede usar sin más interacción con el cliente en el proceso posterior.

Acepta indicadores

La API de Address Validation proporciona una serie de indicadores para informarte si se debe confirmar una dirección.

1. Nivel de detalle de la validación

Se acepta un validationGranularity de PREMISE o mejor, pero, en algunos casos, ROUTE aún indica una dirección de entrega.

2. Otros indicadores

Un veredicto de dirección de alta calidad también debe proporcionar lo siguiente:

  • No hay datos reemplazados. En este caso, es hasReplacedComponents: FALSE.
  • No hay componentes inferidos. En este caso, es hasInferredComponents: FALSE.

3. Indicadores de dirección de EE.UU.

Algunos campos que solo se aplican a las direcciones de EE.UU. indican una dirección de alta calidad a la que se puede realizar la entrega. Para que una dirección de EE.UU. sea aceptable, deberías ver lo siguiente:

dpvConfirmation Y

Para obtener más información sobre dpvConfirmation, consulta Cómo controlar direcciones de Estados Unidos.

Ejemplos de direcciones aceptadas