DataFirefly Address Lookup — Documentación
Instalación, ajustes y solución de problemas de las sugerencias de direcciones: servicio gratuito de la Géoplateforme (IGN, datos BAN) para Francia y ultramar, Google Places API (New) opcional para los demás países.
Presentación
DataFirefly Address Lookup sugiere direcciones mientras el cliente escribe en los formularios de dirección de PrestaShop: el proceso de compra (clientes e invitados, dirección de entrega y de facturación) y Mi cuenta > Mis direcciones. El cliente escribe el principio de su dirección, elige una sugerencia y el módulo rellena la calle, el código postal, la ciudad y, en los países que los tienen, el estado o la provincia.
Hay dos proveedores, que se eligen país por país:
- Géoplateforme: servicio de geocodificación del IGN (instituto geográfico nacional de Francia) basado en la base nacional de direcciones (BAN),
data.geopf.fr/geocodage. Gratuito, sin clave. Sustituye aapi-adresse.data.gouv.fr, desactivada a finales de enero de 2026. - Google Places API (New): opcional, con su propia clave de Google Maps Platform, para los países que la Géoplateforme no cubre.
Novedades de la 2.0.0: proveedor por país, territorios de ultramar atendidos por la Géoplateforme, Google cargado solo cuando se usa, estado/provincia rellenado, lista de sugerencias totalmente usable con el teclado y los lectores de pantalla, botón «Introducir mi dirección manualmente», vista previa y pruebas en el back office, aviso de privacidad, estadísticas sin datos personales, 8 idiomas, compatibilidad ampliada a PrestaShop 1.7.8.
Requisitos y compatibilidad
- PrestaShop 1.7.8 a 9.x, PHP 7.1 o superior.
- Temas Classic y Hummingbird, y los temas que conservan los nombres de campo estándar (
address1,postcode,city,id_country,id_state). No requiere jQuery. - Módulos de proceso de compra que muestran el formulario de dirección estándar, por ejemplo DataFirefly Simple Checkout.
- Solo para Google Places: una clave de Google Cloud con Places API (New) y Maps JavaScript API activadas y la facturación activa.
Instalación y actualización
- En Módulos > Gestor de módulos, haga clic en Subir un módulo y deposite
dfaddresslookup-2.0.0.zip. - Haga clic en Configurar. Sin más ajustes, Francia y los territorios de ultramar reciben las sugerencias de la Géoplateforme.
Actualización desde la 1.0.x o la 1.1.0: suba el nuevo zip sobre el anterior. Se conservan todos los ajustes; la lista «Países permitidos (Google)» de la 1.x se convierte en la tabla de proveedores por país, de modo que los mismos países conservan las mismas sugerencias. El script de actualización también vacía la caché CSS combinada de PrestaShop, que si no seguiría sirviendo la hoja de estilos antigua.
Resumen
La primera pestaña resume lo que ven los clientes: número de países por proveedor, páginas, aviso de privacidad, módulos de proceso de compra detectados y contadores de los últimos 30 días.

Países y proveedores
Cada país activado en la tienda tiene su propia opción: Automático, Géoplateforme, Google Places o Sin sugerencias. En automático, la Géoplateforme atiende los países donde tiene direcciones; para los demás, el ajuste «Países que la Géoplateforme no cubre» elige Google Places (si hay una clave) o ninguna sugerencia. La columna Resultado se actualiza en directo.
La Géoplateforme cubre Francia metropolitana, Guadalupe, Martinica, Guayana Francesa, Reunión, Mayotte, San Pedro y Miquelón, San Bartolomé y San Martín, y en parte Nueva Caledonia y la Polinesia Francesa. No tiene datos de Wallis y Futuna ni de Mónaco. Una dirección de ultramar escrita con el país «Francia» también se encuentra.

Ajustes de búsqueda
- Mínimo de caracteres (2 a 10, 3 por defecto; la Géoplateforme necesita al menos 3).
- Espera antes de buscar (80 a 2000 ms, 250 por defecto): pausa tras la última tecla.
- Número de sugerencias (1 a 10, 6 por defecto) y tiempo máximo (1000 a 15000 ms) tras el cual se abandona la búsqueda.
- Resaltar el texto escrito, ciudad a partir del código postal, botón Introducir mi dirección manualmente.
- Páginas: proceso de compra y/o Mis direcciones. El script solo se carga en estas páginas, y en ninguna si ningún país tiene proveedor. Un campo avanzado acepta los controladores de un módulo de proceso de compra con página propia.
- Color de acento: vacío, se usa el color principal del tema.

Clave de Google Places
El módulo solo usa Places API (New): el antiguo widget Places Autocomplete ya no se ofrece a los nuevos proyectos de Google Cloud. El script de Google solo se carga cuando un cliente escribe una dirección en un país atendido por Google.
- En la consola de Google Cloud, cree o elija un proyecto con la facturación activada.
- En API y servicios, active Places API (New) y Maps JavaScript API.
- Cree una clave de API en Credenciales.
- Restricciones de aplicaciones: Sitios web. Añada los referentes que muestra el módulo (dominios de la tienda y del back office, botón Copiar).
- Restricciones de API: limite la clave a Places API (New) y Maps JavaScript API.
- Pegue la clave, active Google Places, guarde y haga clic en Probar la clave.
Facturación: el módulo agrupa las búsquedas de una misma dirección en un token de sesión, cerrado por una única petición Place Details limitada a los campos de dirección (categoría Essentials). Google factura este uso en su cuenta según su tarifa vigente; el número de sesiones aparece en la pestaña Estadísticas. Por defecto solo se sugieren direcciones (números, edificios, calles), no comercios.
Una clave de Maps JavaScript es visible en las páginas de la tienda: no la despliegue nunca sin restricción de referente HTTP.

Vista previa y prueba
La pestaña Vista previa y prueba reproduce un formulario de dirección con los ajustes actuales, incluso antes de guardar. Los botones de prueba consultan la Géoplateforme y Google Places desde su navegador, como lo haría un cliente, e indican el tiempo de respuesta o la causa de un fallo (clave rechazada, red, directiva CSP).

Lado del cliente
Sugerencias y teclado
Las sugerencias aparecen bajo el campo Dirección, por encima de la página: el formulario no se mueve. Cada línea muestra la calle y luego el código postal, la ciudad y la región. Las flechas arriba y abajo recorren la lista, Intro elige, Esc cierra sin borrar lo escrito; el número de sugerencias se anuncia a los lectores de pantalla.


Relleno del formulario
Los campos solo se rellenan cuando el cliente elige una sugerencia y se resaltan brevemente. El complemento de dirección nunca se sustituye, y la ciudad a partir del código postal solo rellena un campo vacío. Los formularios de entrega y de facturación funcionan por separado, y el proveedor sigue el país elegido, también cuando PrestaShop recarga el formulario.

Ciudad a partir del código postal
En los países atendidos por la Géoplateforme, un código postal de 5 cifras rellena la ciudad cuando solo coincide un municipio, o muestra la lista de municipios cuando hay varios.

Sin resultados, error, introducción manual
Cuando ninguna dirección coincide, o cuando el servicio está lento, saturado (respuesta 429) o no disponible, la lista lo indica y recuerda que la introducción manual sigue siendo posible. El botón Introducir mi dirección manualmente (o la tecla Esc) cierra la lista; el pedido nunca se bloquea.

Google Places para los demás países
En un país atendido por Google, las sugerencias proceden de Google Places y llevan la mención «Google Maps». Al elegir, el estado o la provincia también se selecciona en la lista de PrestaShop cuando el país la tiene.

Móvil y Mis direcciones
En el móvil, las líneas miden al menos 48 px de alto y la lista queda dentro de la pantalla. Las mismas sugerencias están disponibles cuando un cliente añade o modifica una dirección en su cuenta.


Privacidad
El texto escrito en el campo Dirección sale del navegador del cliente hacia el proveedor del país: la Géoplateforme (data.geopf.fr, sin cookie) o Google (maps.googleapis.com, solo para los países atendidos por Google y solo cuando el cliente escribe). Nada pasa por DataFirefly. Bajo el campo se muestra un aviso, en cada idioma, con el nombre del proveedor ({provider}) y un enlace opcional a una página CMS. Este aviso informa al cliente; no sustituye su propio análisis de sus obligaciones.

Estadísticas
El módulo cuenta, por día y por proveedor, las búsquedas, las direcciones elegidas, las búsquedas sin resultado, los errores y las sesiones de Google. No se guarda ninguna dirección, dirección IP ni identificador de cliente. El recuento se puede desactivar y restablecer.

Seguridad y Content Security Policy
- Las sugerencias se construyen como texto: ningún dato del proveedor se inserta como HTML.
- El módulo no usa scripts inline ni
evaly no tiene proxy en el servidor. - Si su tienda envía una cabecera CSP:
connect-src https://data.geopf.frpara la Géoplateforme; para Google, las directivas de la pestaña Ayuda (el nonce de la página se transmite al script de Google cuando existe).
Solución de problemas
No aparece ninguna sugerencia
- Compruebe que el módulo está activado y que la página forma parte de las páginas elegidas.
- En Países y proveedores, compruebe la columna Resultado del país elegido en el formulario.
- Lance la prueba de la Géoplateforme en Vista previa y prueba: un fallo suele indicar un bloqueo de red o una directiva
connect-src. - Tras una actualización manual de archivos, vacíe la caché en Parámetros avanzados > Rendimiento.
Google Places no responde
- El botón Probar la clave indica si Google rechaza la clave: API no activada, facturación inactiva o dominio ausente de los referentes.
- El dominio del back office debe figurar en los referentes para la prueba y la vista previa.
Un módulo de proceso de compra de terceros
Los procesos de compra que conservan los nombres de campo estándar funcionan sin ajustes. Si tienen página propia, añada su controlador en Otros controladores. Si renombran los campos, la introducción sigue siendo manual, sin errores.
Preguntas frecuentes
¿Hace falta una clave para Francia?
No. La Géoplateforme es gratuita y sin clave. Google Places es opcional.
¿Se carga el script en todas las páginas?
No: solo en el proceso de compra y en la página de dirección (según sus ajustes), y el script de Google solo cuando un cliente escribe en un país atendido por Google.
¿Qué ocurre al desinstalar?
Se eliminan los ajustes y la tabla de estadísticas.
Historial de versiones
2.0.0 — 8 de noviembre de 2026
- Proveedor por país (automático, Géoplateforme, Google Places, ninguno); territorios de ultramar creados como países distintos atendidos por la Géoplateforme
- Google: script cargado bajo demanda, solo direcciones, token de sesión cerrado por una petición Essentials, estado/provincia rellenado, atribución Google Maps, detección de clave rechazada
- Nueva lista de sugerencias: estados de carga, sin resultados, error y pausa, botón de introducción manual, patrón ARIA combobox completo, tamaños móviles
- Peticiones obsoletas canceladas, tiempo máximo, caché, pausa ante respuestas 429
- Back office rehecho: vista previa, pruebas de conexión, ayuda para la clave, aviso de privacidad, estadísticas; 8 idiomas
- Compatible con PrestaShop 1.7.8 a 9; actualización desde la 1.0.x y la 1.1.0 sin perder ajustes
1.1.0 — 23 de agosto de 2026
- Motor de Google migrado a Places API (New)
1.0.3 y 1.0.2 — 23 de agosto de 2026
- Calle conservada tras la selección; la lista ya no se vuelve a abrir tras la elección
1.0.1 — 1 de julio de 2026
- Paso a la Géoplateforme (data.geopf.fr/geocodage)
1.0.0 — 15 de mayo de 2026
- Primera versión pública