Crea 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. 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 solicitar 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:

• Corregir: 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 una confirmación.
• Aceptar: La dirección es de alta calidad. Puedes aceptar la dirección proporcionada.

Propósito clave

Este documento te ayuda a modificar tu sistema para analizar mejor la respuesta de la API y determinar las próximas acciones que se deben realizar con las direcciones proporcionadas. El siguiente pseudocódigo ilustra un flujo posible.

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 Asesoramiento para la 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 debe 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 que describe otros indicadores que también podrías necesitar investigar.

Comportamiento del sistema
Corregir la dirección	La respuesta de verdict indica que falta información importante que se debe proporcionar. Es posible que la dirección que muestra la API no sea de calidad entregable. Flujo de trabajo Investiga los componentes de la dirección si es necesario. Pídele al cliente que corrija los problemas de la dirección. Solicita la validación de la dirección actualizada. Continúa con la dirección. Indicadores de veredicto Se aplica cualquiera de las siguientes opciones: validationGranularity se establece en OTHER. addressComplete es false.
Confirmar la dirección	La respuesta de verdict indica una dirección entregable pero realizó cambios en la entrada original: infiere datos que se corrigieron ortográficamente o datos que se pueden confirmar. Flujo de trabajo Correcciones necesarias: Investiga los componentes de la dirección si es necesario. Solicita la validación de la dirección actualizada. Continúa con la dirección. No se necesitan correcciones: Continúa con la dirección. Indicadores de veredicto Se aplican todas las siguientes opciones: validationGranularity contiene ROUTE. addressComplete es true. hasInferredComponents el campo es true O hasReplacedComponents el campo 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 que se mostró. Indicadores de veredicto Se aplican todas las siguientes opciones: validationGranularity contiene PREMISE o un valor mejor. addressComplete es true. No se infirieron ni reemplazaron componentes.

Asesoramiento para la implementación

Cuando diseñes la forma en que tu sistema responde a los indicadores de validación de direcciones, 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 para tu situación cuando encuentres un 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 con tu nivel de riesgo para optimizar el proceso de validación Por ejemplo, si una dirección tiene un número de calle sin confirmar, puedes aceptarla. Por otro lado, si tu operación comercial requiere una mayor precisión de la dirección, puedes solicitarle al usuario que la corrija. Para ver un ejemplo que podría entrar en cualquiera de las categorías, consulta Número de calle sin confirmar que no es de EE.UU. en Aceptar dirección: ejemplos.
Aceptar direcciones	Es una buena práctica permitir que tu sistema acepte la entrada original si el cliente no responde a las solicitudes.	En estos casos, es posible que el cliente haya ingresado una dirección que no está en el sistema, como una construcción nueva.

Prueba la demostración. En el resto de este documento, se usan varios ejemplos para ayudarte a comprender el proceso de flujo de corrección, confirmación y aceptación que se describió anteriormente. Para explorar los resultados de estos ejemplos, ingrésalos en la demostración de Address Validation en la API de Maps JavaScript.

Corregir una dirección

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

Indicadores de corrección

La API de Address Validation proporciona varias señales 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 validationGranularity campo sea OTHER, tu sistema debe investigar los indicadores de los componentes de la dirección para obtener más información sobre dónde ocurrió el error y cómo corregirlo.
• Cada vez que el objeto address procesado posteriormente muestre un campo missingComponentTypes, tu sistema debe verificar ese componente. Los componentes faltantes también hacen que una dirección esté incompleta y no sea entregable.

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 enum de nivel de confirmación 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 una parte válida de una dirección.

3. Indicadores de direcciones de EE.UU.

Ciertos campos aplicables solo a direcciones de EE.UU. proporcionan un indicador útil de que la dirección no es entregable y se debe corregir. Para una dirección que requiere corrección, deberías ver lo siguiente:

dpvConfirmation	N, D o vacío

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

Ejemplos de corrección de direcciones

Confirmar una dirección

Confirmas una dirección cuando el veredicto indica que la API de Address Validation infirió o realizó cambios en los componentes de la dirección para producir una dirección validada. En estos casos, tienes una dirección entregable, pero prefieres tener más confianza en que la dirección resultante sea la que el cliente desea.

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

Nota: Ten en cuenta tu nivel de riesgo cuando decidas si confirmar la dirección con el cliente o aceptarla como válida.

Indicadores de confirmación

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

1. Nivel de detalle de la validación

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

2. Otros indicadores

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

Datos inferidos	Cuando el hasInferredComponents campo es true, sabes que la API completó la información que obtuvo de otros componentes de la dirección.
Datos reemplazados	Cuando el hasReplacedComponents campo es true, la API reemplazó los datos ingresados por datos que consideró que harían que la dirección fuera válida.

3. Indicadores de direcciones de EE.UU.

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

dpvConfirmation	S Para obtener detalles sobre dpvConfirmation, consulta Cómo administrar direcciones de Estados Unidos.
Respuesta de la dirección	Contiene el campo missingComponentTypes con el valor de subpremise. Nota: Si el campo contiene tipos distintos de subpremise, la acción entraría en la categoría de corrección de direcciones. Consulta la lista completa de tipos de direcciones en la documentación de Geocoding.

Ejemplos de confirmación de direcciones

Aceptar una dirección

Aceptas 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 del cliente en el proceso descendente.

Indicadores de aceptación

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

1. Nivel de detalle de la validación

Un validationGranularity de PREMISE o un valor mejor es aceptable, pero, en algunos casos, ROUTE aún indica una dirección entregable.

2. Otros indicadores

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

• No se reemplazaron datos. En este caso, hasReplacedComponents: FALSE.
• No se infirieron componentes. En este caso, hasInferredComponents: FALSE.

3. Indicadores de direcciones de EE.UU.

Ciertos campos aplicables solo a direcciones de EE.UU. indican una dirección de alta calidad que se puede entregar. Para una dirección aceptable de EE.UU., deberías ver lo siguiente:

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

Ejemplos de aceptación de direcciones