Address API - Guía de integración

Cómo conectar los endpoints de sugerencia y validación de DQE para obtener la mejor calidad de dirección con el mínimo de llamadas API innecesarias.

Patrones de integración

DQE recomienda un enfoque en dos niveles:

• Nivel 1 - Sugerencia de dirección - elija línea única o escritura progresiva según el diseño de su formulario
• Nivel 2 - Red de seguridad de validación RNVP - actívela solo cuando el usuario haya escrito texto libre o modificado una sugerencia de DQE

Flujo de integración

Campo Label - solo para visualización

El campo Label tiene un formato pensado únicamente para la lista desplegable de sugerencias. Su formato varía según el país y puede incluir separadores, paréntesis o números entre corchetes. No lo utilice para rellenar los campos de dirección - use siempre los campos estructurados que se devuelven junto a él.

Los números de calle entre corchetes (p. ej. [30] RUE DE LA PAIX) indican que el número no se encontró en la base de referencia de DQE. Aun así, DQE devuelve el resto de la dirección correctamente formateada para que los usuarios puedan continuar. Se recomienda mostrar los números entre corchetes con un estilo atenuado para señalar que el número puede necesitar verificación - podría aparecer en una futura actualización de la base de datos.

Posición del número de calle

La API devuelve Numero y Voie como campos estructurados independientes (RESTful: StreetNumber y Street). Concaténelos en el orden definido por el país de destino.

Nota: si Numero está vacío, muestre solo Voie - sin separador.

Calle seleccionada sin número

Cuando un usuario selecciona una calle sin introducir un número, la API devuelve la coincidencia de la calle pero indica que existen números para esa calle. Detecte este caso y muestre los números disponibles a partir de la respuesta ya recibida - no se necesita ninguna llamada API adicional. Esto se aplica a todos los modos de autocompletado: API Standard SINGLEV2 y ADR, RESTful SINGLE y FunnelAddress.

Condición de detección

Campo Complement

Asocie su campo de formulario de complemento a Complement (Classic: SINGLEV2 / ADR) o AdditionalAddress (RESTful: single / funneladdress).

Después de que el usuario seleccione una dirección, llame al paso de complemento dedicado - COMPLV2 / COMPL (Classic) o compl / funnelcompl (RESTful) - y muestre las opciones devueltas al usuario.

Idioma de los resultados devueltos

Para la mayoría de los países, los datos de dirección existen en un único idioma y el idioma de los resultados devueltos depende completamente de la base de referencia - no se puede modificar.

Para algunos países, la base de datos contiene entradas en varios idiomas o escrituras. En este caso, el parámetro Langue actúa como un filtro de idioma estricto: solo se devuelven los resultados que coinciden con el idioma solicitado. Sin este parámetro, se pueden devolver todas las versiones lingüísticas simultáneamente.

Países donde Langue filtra por idioma

Corrección de dirección (RNVP)

Cuando se activa una llamada RNVP, muestre la corrección al usuario en una ventana emergente, preservando siempre la posibilidad de conservar su entrada original. Añada Modification=O a la solicitud para recibir un desglose campo por campo.

Mensajes de usuario recomendados por código de validación

El código de validación (DQECodeDetail en la API Classic, DQEDetailCode en la API RESTful) indica la calidad de la dirección devuelta por la API. La siguiente tabla asocia cada código con una descripción interna (para los equipos de soporte e integración) y un mensaje recomendado para el usuario final.