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 él, 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:
- Corrección: La dirección es de baja calidad. Debes solicitar más información.
- Confirm: La dirección es de alta calidad, pero tiene cambios con respecto a la dirección de entrada. Es posible que se te solicite 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 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 orientación 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:
- El flujo de trabajo que se usará según el comportamiento de corregir, confirmar y aceptar.
- Los primeros indicadores que se deben verificar en la respuesta. Los indicadores que se describen aquí provienen de la propiedad
verdicty 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 investigar.
| El comportamiento del sistema | |||
|---|---|---|---|
| Corregir la dirección |
La respuesta de
|
||
| Confirma la dirección |
La respuesta de
|
||
| Aceptar la dirección |
La respuesta de la API de Address Validation indica que la dirección es de excelente calidad.
|
||
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 decidas si solicitar correcciones o aceptar la dirección tal como se ingresó. |
La API de Address Validation devuelve 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 sin confirmar, puedes aceptarla de todos modos. Por otro lado, si tu operación comercial requiere una mayor precisión de la dirección, puedes solicitarle al usuario que la proporcione. Para ver un ejemplo que podría entrar en cualquiera de las dos categorías, consulta Número de calle no confirmado de fuera de EE.UU. en Aceptar dirección: ejemplos. |
| 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 se encuentra en el sistema, como la de una construcción nueva. |
Corregir una dirección
Corregir una dirección cuando los resultados indican claramente que no se puede entregar. Luego, tu sistema puede solicitarle al cliente que proporcione la información necesaria, tras lo cual puedes volver a emitir tu flujo de trabajo para obtener una dirección de entrega.
Indicadores de corrección
La API de Address Validation proporciona varios indicadores para informarte si se debe corregir una dirección.
1. Granularidad de la validación y componentes faltantes
Estos dos indicadores proporcionan la mejor indicación de una dirección problemática:
- Siempre que el campo
validationGranularityseaOTHER, tu sistema debe investigar los indicadores de los componentes de la dirección para obtener más información sobre dónde se produjo el error y cómo corregirlo. - Cada vez que el objeto
addressprocesado posteriormente devuelva un campomissingComponentTypes, tu sistema debe verificar ese componente. Los componentes faltantes también hacen que una dirección esté incompleta y no se pueda realizar la entrega.
2. Otros indicadores
La API de Address Validation también proporciona 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.
Algunos campos aplicables solo a las direcciones de EE.UU. proporcionan un indicador útil de que la dirección no es apta para la entrega y se debe corregir. En el caso de 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 controlar direcciones de Estados Unidos.
Ejemplos de corrección de direcciones
Cómo 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 de entrega, pero prefieres tener más certeza de que la dirección resultante es la que el cliente quería.
Para proporcionar al cliente la instrucció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.
Confirmar indicadores
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
Se acepta un validationGranularity de ROUTE o superior, pero PREMISE o SUBPREMISE proporcionan un indicador más sólido de la capacidad de entrega.
2. Otros indicadores
Cuando se decide 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 campo
hasInferredComponents es true, sabes que la API completó la información que obtuvo de otros componentes de la dirección.
|
|---|---|
| Datos reemplazados | Cuando el campo
hasReplacedComponents 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.
Algunos campos aplicables solo a las direcciones de EE.UU. indican que tu lógica debe confirmar los detalles con el cliente. Se aplica una de las siguientes opciones:
dpvConfirmation
|
S
Para obtener detalles sobre |
|---|---|
| Respuesta de dirección | Contiene el campo missingComponentTypes con el valor de subpremise.
|
Ejemplos de direcciones confirmadas
Cómo aceptar una dirección
Aceptas una dirección cuando el veredicto proporciona un alto grado de confianza en que la dirección es apta para la entrega y se puede usar sin más interacción del cliente en el proceso posterior.
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 mejor es aceptable, pero, en algunos casos, ROUTE aún indica una dirección de entrega.
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, es
hasReplacedComponents: FALSE. - No se infirieron componentes. En este caso, es
hasInferredComponents: FALSE.
3. Indicadores de direcciones de EE.UU.
Algunos campos que solo se aplican a las direcciones de EE.UU. indican que se trata de una dirección de alta calidad a la que se puede realizar la entrega. En una dirección de EE.UU. aceptable, deberías ver lo siguiente:
dpvConfirmation
|
Y
Para obtener detalles sobre
|
|---|
Ejemplos de direcciones aceptadas