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 interpretar la respuesta de la API para determinar cuándo y cómo solicitarles más información a los clientes.

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

• Corregir: Es posible que la dirección contenga problemas importantes.
  Considera pedirle más información al cliente.
• Agregar subpredios: Es posible que a la dirección le falte un subpredio.
  Pídele al cliente que agregue un número de unidad.
• Confirmar: Es posible que la dirección tenga problemas menores.
  Pídele al cliente que confirme que la dirección es correcta.
• Aceptar: Es posible que la dirección no tenga problemas.
  Considera usar la dirección sin más indicaciones, bajo tu propia responsabilidad.

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 (verdict.possibleNextAction == FIX)
    Prompt the user to fix the address.
else if (verdict.possibleNextAction == CONFIRM_ADD_SUBPREMISES)
    Prompt the user to add a unit number.
else if (verdict.possibleNextAction == CONFIRM)
    Confirm with the user that the address is correct.
else
    Continue with the address returned by the API.

La lógica exacta depende de tu situación. Consulta Cómo personalizar tu lógica de validación para obtener más información.

Posibles flujos de trabajo

En la siguiente tabla, se resumen los posibles flujos de trabajo que podrías implementar para solicitarle al cliente información según la respuesta de la API.

El comportamiento de tu sistema
Cómo corregir la dirección	La respuesta de verdict indica que puede haber problemas significativos con la dirección. Por ejemplo, verdict.possibleNextAction es FIX. Considera pedirle más información a tu cliente. Flujo de trabajo Investiga los componentes de la dirección si es necesario. Pídele al cliente que corrija los problemas con la dirección. Solicita la validación de la dirección actualizada. (Opcional) Envía una solicitud al extremo de comentarios de la API. Consulta Cómo controlar las direcciones actualizadas. Continúa con la dirección.
Agrega subpredios	La respuesta de verdict indica que a la dirección le podría faltar un subpredio. Por ejemplo, verdict.possibleNextAction es CONFIRM_ADD_SUBPREMISES. Considera pedirle al cliente que agregue un número de unidad. Flujo de trabajo Pídele al cliente que agregue un número de unidad. Solicita la validación de la dirección actualizada. (Opcional) Envía una solicitud al extremo de comentarios de la API. Consulta Cómo controlar las direcciones actualizadas. Continúa con la dirección.
Confirma la dirección	La respuesta de verdict indica que puede haber problemas menores con la dirección. Por ejemplo, verdict.possibleNextAction es CONFIRM. Considera pedirle al cliente que revise la dirección. Flujo de trabajo Correcciones necesarias: Investiga los componentes de la dirección si es necesario. Solicita la validación de la dirección actualizada. (Opcional) Envía una solicitud al extremo de comentarios de la API. Consulta Cómo controlar las direcciones actualizadas. Continúa con la dirección. No se necesitan correcciones: (Opcional) Envía una solicitud al extremo de comentarios de la API. Consulta Cómo controlar las direcciones actualizadas. Continúa con la dirección.
Aceptar la dirección	La respuesta de verdict indica que es posible que no haya problemas con la dirección. Por ejemplo, verdict.possibleNextAction es ACCEPT. Considera continuar con la dirección como lo harías para tu nivel de riesgo. Flujo de trabajo Continúa con la dirección de devolución.

Nota: Cuando repites las solicitudes a la API de Address Validation para la misma dirección, puedes llamar a provideValidationFeedback para indicar el resultado. Consulta Cómo controlar las direcciones actualizadas.

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

Personaliza tu lógica de validación

Si bien puedes usar los resultados del campo verdict.possibleNextAction para determinar cómo tu sistema continúa con la respuesta de la API, también puedes considerar crear una lógica personalizada, por ejemplo, para controlar las necesidades específicas de la empresa.

El objetivo de esta sección es ilustrar cómo puedes desarrollar tu propia lógica personalizada para interpretar la respuesta de la API y determinar si quieres solicitarle algo al cliente y cómo hacerlo. En esta sección, se describen los niveles de riesgo y los indicadores de respuesta de la API adicionales que debes tener en cuenta para tu personalización.

Dicho esto, incluso si solo te basas en verdict.possibleNextAction para decidir los próximos pasos, los indicadores adicionales que se describen a continuación pueden ayudarte a comprender los detalles sobre posibles problemas con la dirección.

Tolerancia al riesgo

Cuando diseñes la forma en que tu sistema responde a los indicadores 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 ten 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 equilibres 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.

Ejemplo de un flujo de confirmación de la compra que evita riesgos

Si deseas reducir el riesgo de que se produzcan entregas fallidas, puedes personalizar tu lógica para que les solicites a los clientes con más frecuencia. Por ejemplo, en lugar de usar la lógica que se describe en la sección Propósito de la clave, puedes usar la siguiente lógica.

if (verdict.possibleNextAction == FIX or verdict.validationGranularity
== OTHER or verdict.validationGranularity == ROUTE)
  Prompt customer to fix their address.
else if (verdict.possibleNextAction == CONFIRM_ADD_SUBPREMISES)
  Prompt customer to add a unit number.
else if (verdict.possibleNextAction == CONFIRM or verdict.validationGranularity
== PREMISE_PROXIMITY or verdict.hasSpellCorrectedComponents or
verdict.hasReplacedComponents or verdict.hasInferredComponents)
  Prompt customer to confirm their address.
else
  Proceed with the returned address.

Ejemplo de un flujo de confirmación de la compra sin fricciones

Si deseas reducir los inconvenientes en el flujo de confirmación de la compra, puedes personalizar tu lógica para solicitarles a los clientes con menos frecuencia. Por ejemplo, en lugar de usar la lógica que se describe en la sección Propósito de la clave, puedes usar la siguiente lógica.

if (verdict.possibleNextAction == FIX)
  Prompt customer to fix their address.
else if (verdict.hasReplacedComponents)
  Prompt customer to confirm their address.
else
  Proceed with the returned address.

Indicadores FIX

Corrige una dirección cuando los resultados indiquen claramente que es posible que no se pueda 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.

Los siguientes campos de la respuesta de la API de Address Validation se pueden usar además de verdict.possibleNextAction para determinar si una dirección tiene problemas importantes y cuáles son.

Nivel de detalle de la validación	Cuando la enumeración de nivel de detalle de validación de una dirección es OTHER, es probable que la dirección sea incorrecta.
Faltan componentes	Cuando address.missingComponentTypes no está vacío, es probable que a la dirección le falte información clave.
Componentes sospechosos	Cuando la enumeración de nivel de confirmación de un componente es UNCONFIRMED_AND_SUSPICIOUS, es probable que el componente sea incorrecto.
Componentes sin resolver	Un unresolvedToken es una parte de la entrada que no se reconoce como parte válida de una dirección.
Confirmación de DPV de USPS	Cuando uspsData.dpvConfirmation es N o está vacío, es posible que haya un problema con la dirección. Este campo solo está disponible para direcciones de EE.UU. Para obtener más detalles sobre uspsData.dpvConfirmation, consulta Cómo controlar las direcciones de Estados Unidos.

Ejemplos de direcciones corregidas

Indicadores CONFIRM_ADD_SUBPREMISES (solo para direcciones de EE.UU.)

Le pides al cliente que revise la dirección y que considere agregar un número de unidad cuando la respuesta de la API de Address Validation indique que es posible que le falte un subpredio. En estos casos, es probable que la dirección del edificio sea válida, pero quieres tener más confianza en que la dirección resultante sea la que desea el cliente.

Los siguientes campos de la respuesta de la API de Address Validation se pueden usar además de verdict.possibleNextAction para determinar si es probable que a una dirección le falte un subpredio.

Missing subpremise component	Cuando el campo address.missingComponentTypes contiene un valor de subpremise, significa que falta un número de unidad en la dirección. Nota: Si el campo contiene tipos distintos de subpremise, la acción se incluirá en la categoría FIX. Consulta la lista completa de los tipos de componentes en la documentación de geocodificación.
Confirmación de DPV de USPS	Cuando uspsData.dpvConfirmation es S, significa que el número principal de la dirección coincide con una dirección de la base de datos de USPS. Sin embargo, se esperaba que la dirección también incluyera un número secundario. Este campo solo está disponible para direcciones de EE.UU. Para obtener más detalles sobre uspsData.dpvConfirmation, consulta Cómo controlar direcciones de Estados Unidos.

Agrega ejemplos de direcciones de subpredios

Indicadores de CONFIRM

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 generar 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.

Los siguientes campos de la respuesta de la API de Address Validation se pueden usar además de verdict.possibleNextAction para determinar si una dirección tiene problemas menores y cuáles son.

Nivel de detalle de la validación	Cuando validationGranularity de una dirección es ROUTE o PREMISE_PROXIMITY, es posible que la dirección sea incorrecta.
Datos inferidos	Cuando el campo hasInferredComponents es true, significa 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.
Correcciones ortográficas	Cuando el campo hasSpellCorrectedComponents es true, la API corrigió la ortografía de algunos componentes con errores ortográficos.

Ejemplos de direcciones de confirmación

Indicadores de ACCEPT

Puedes aceptar una dirección cuando la respuesta de la API de Address Validation API proporciona un grado de confianza alto de que la dirección se puede entregar y se puede usar sin más interacción del cliente en el proceso descendente.

Nota: Ten en cuenta tu nivel de riesgo cuando decidas si aceptar una dirección o pedirle más información al cliente.

Los siguientes campos de la respuesta de la API de Address Validation se pueden usar además de verdict.possibleNextAction para determinar si una dirección es de calidad aceptable.

Nivel de detalle de la validación	A menudo, se acepta un validationGranularity de PREMISE, aunque un valor de ROUTE aún puede indicar una dirección de entrega.
No hay datos inferidos	Cuando el campo hasInferredComponents es false, significa que no se infirió ningún componente en el resultado.
No hay datos reemplazados	Cuando el campo hasReplacedComponents es false, sabes que no se reemplazaron datos de entrada.
No hay correcciones ortográficas	Cuando el campo hasSpellCorrectedComponents es false, significa que no se realizaron correcciones ortográficas.
Confirmación de DPV de USPS	Cuando uspsData.dpvConfirmation es Y, significa que la dirección coincide con una dirección de la base de datos del USPS. Este campo solo está disponible para direcciones de EE.UU. Para obtener más detalles sobre uspsData.dpvConfirmation, consulta Cómo controlar direcciones de Estados Unidos.

Ejemplos de direcciones aceptadas