Cómo conectar los endpoints de sugerencia y validación de DQE para lograr una calidad de dirección óptima con el mínimo de llamadas API innecesarias.
Patrones de integración
DQE recomienda un enfoque de dos niveles:
- Nivel 1 - Sugerencia de dirección - elija línea única o progresivo según el diseño de su formulario
- Nivel 2 - Red de seguridad de validación RNVP - actívela solo cuando el usuario haya introducido texto libre o haya modificado una sugerencia de DQE
Flujo de integración
Campo Label - solo para visualización
El campo Label está formateado únicamente para el menú 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 devueltos junto con él.
Los números de calle entre corchetes (por ejemplo, [30] RUE DE LA PAIX) indican que el número no se encuentra en la base de datos de referencia de DQE. Aun así, DQE devuelve el resto de la dirección correctamente formateado para que los usuarios puedan continuar. Considere mostrar los números entre corchetes con un estilo atenuado para indicar que el número puede necesitar verificación - podría aparecer en una futura actualización de la base de datos.
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 presente los números disponibles a partir de la respuesta ya recibida - no es necesaria ninguna llamada adicional a la API. Esto se aplica a todos los modos de autocompletado: Standard API SINGLEV2 y ADR, RESTful SINGLE y FunnelAddress.
Condición de detección
| Campo | Valor | Significado |
|---|---|---|
| valid_num | "0" |
Ningún número válido coincidió |
| ListeNumero | no vacío | Existen números conocidos en esta calle |
Campo de complemento
Asocie su campo de complemento del formulario 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 presente al usuario las opciones devueltas.
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 datos de referencia - no se puede modificar.
Para algunos países, la base de datos contiene entradas en varios idiomas o alfabetos. En ese caso, el parámetro Langue actúa como un filtro de idioma estricto: solo se devuelven los resultados etiquetados con el idioma solicitado. Sin él, se pueden devolver simultáneamente todas las versiones de idioma.
Países en los que Langue filtra por idioma
| País | Valores admitidos | Efecto |
|---|---|---|
| Japón (JPN) |
JP · JK · EN
|
JP = kanji · JK = katakana · EN = romaji. Sin Langue, se devuelven los tres alfabetos. |
| Hong Kong (HKG) |
EN · ZH
|
EN = inglés · ZH = chino. Establecer Langue=EN con una entrada en chino (o viceversa) devuelve cero resultados. |
| Tailandia (THA) |
EN · TH
|
EN = transliteración latina · TH = alfabeto tailandés. Sin Langue, se devuelven simultáneamente ambas versiones de idioma (por ejemplo, la búsqueda por código postal devuelve resultados en tailandés e inglés mezclados). |
Langue no coincide con ninguna entrada de la base de datos para una entrada determinada, la API devuelve cero resultados. Asegúrese de que el idioma solicitado sea coherente con el alfabeto de la dirección introducida.Corrección de dirección (RNVP)
Cuando se activa una llamada RNVP, muestre la corrección al usuario en una ventana emergente, conservando siempre la opción de mantener su entrada original. Añada Modification=O a la solicitud para recibir un desglose campo por campo.
| Clave | Descripción | Valores |
|---|---|---|
| Status_Modification RESTful: IsAddressChanged |
Indica si DQE modificó la dirección. |
O / N (Classic) · 1 / 0 (RESTful) |
| Code_Modification RESTful: ChangedAddressTag |
Cadena binaria de 5 caracteres - una posición por campo (dirección adicional · dirección · localidad dependiente · código postal · ciudad). Consulte la referencia de CheckAddress. Ejemplo: 00011
|
Binario de 5 car. |
| DQECodeDetail RESTful: DQEDetailCode |
Código de resultado de validación de la dirección devuelta por DQE - no de la entrada original del usuario. Ejemplo: la entrada 12 RUE PAIX PARIS → DQE devuelve 12 RUE DE LA PAIX 75002 PARIS con DQECodeDetail=10 (válido). Lista completa con los mensajes de interfaz recomendados en la referencia de CheckAddress. |
Código numérico |
Mensajes recomendados para el usuario según el código de validación
El código de validación (DQECodeDetail en la API Classic, DQEDetailCode en 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.
| Código | Descripción | Descripción interna | Mensaje en la interfaz |
|---|---|---|---|
| 10 | Dirección correcta | Dirección válida | Dirección válida |
| 20 | Dirección correcta (calle no reconocida, pero se trata de un CEDEX o apartado de correos) | Dirección válida | Dirección válida |
| 21 | Población pequeña, número de calle fuera de rango | Confirme la dirección con el cliente (el número de calle no existe) | Compruebe su dirección postal |
| 22 | Población pequeña, falta el número de calle (el resto de la dirección es correcto) | Confirme la dirección con el cliente (falta el número de calle) | Compruebe su dirección postal |
| 23 | Ciudad grande, número de calle fuera de rango | Confirme la dirección con el cliente (el número de calle no existe) | Compruebe su dirección postal |
| 24 | Ciudad grande, falta el número de calle (el resto de la dirección es correcto) | Confirme la dirección con el cliente (falta el número de calle) | Compruebe su dirección postal |
| 25 | Dirección CEDEX desconocida para CEDEXA (si CEDEXA está activo) | Dirección válida | Dirección válida |
| 30 | Población pequeña, calle no reconocida | Confirme la dirección con el cliente (nombre de calle no encontrado) | Compruebe su dirección postal |
| 31 | Población pequeña - calle no reconocida o ausente; la información del distrito se reconoce pero es insuficiente para determinar la calle. Solo Francia. | Confirme la dirección con el cliente (nombre de calle no encontrado) | Compruebe su dirección postal |
| 40 | No se espera en los despliegues en la nube actuales. Definido por compatibilidad. | - | - |
| 41 | Población pequeña, falta la calle | Confirme la dirección con el cliente (falta el nombre de la calle) | Compruebe su dirección postal |
| 50 | Ciudad grande, calle no reconocida | Confirme la dirección con el cliente (nombre de calle no encontrado) | Compruebe su dirección postal |
| 51 | Ciudad grande - calle no reconocida o ausente (la información del distrito se reconoce pero es insuficiente para determinar la calle). Solo Francia. | Confirme la dirección con el cliente (nombre de calle no encontrado) | Compruebe su dirección postal |
| 60 | No se espera en los despliegues en la nube actuales. Definido por compatibilidad. | - | - |
| 61 | Ciudad grande, falta la calle | Confirme la dirección con el cliente (falta el nombre de la calle) | Compruebe su dirección postal |
| 70 | Código postal / ciudad no coinciden - calle presente | La dirección es incorrecta. El código postal y la ciudad no coinciden. | Compruebe su dirección postal |
| 71 | No se espera en los despliegues en la nube actuales. Definido por compatibilidad. | - | - |
| 80 | Código postal / ciudad no coinciden - falta la calle | La dirección es incorrecta. El código postal y la ciudad no coinciden. | Compruebe su dirección postal |
| 81 | Bloque de dirección de entrada vacío. No se devuelve para Francia. | Dirección no cumplimentada | Compruebe su dirección postal |
| 90 | Dirección internacional detectada - el código de país de entrada no parece coincidir con la dirección introducida. | La dirección parece internacional - el código de país no coincide | Compruebe su dirección postal |
| 95 | Código de país ausente o incorrecto | Compruebe y corrija el código de país en la entrada | Compruebe su dirección postal |
Relacionada con