DataFirefly Address Lookup — Documentación

Presentación

DataFirefly Address Lookup añade el autocompletado de direcciones a los formularios de PrestaShop 8 y 9: el proceso de compra, la página «Mi dirección», la página «Mis datos» y el formulario de registro. El módulo se apoya en dos motores: la API francesa BAN (api-adresse.data.gouv.fr), gratuita y sin clave, activada por defecto para Francia, y Google Places como opción para direcciones internacionales.

El flujo del cliente es simple: teclea su código postal, la ciudad se rellena automáticamente (o aparece un selector de municipios si varios coinciden); empieza a escribir su calle, las sugerencias aparecen; un clic rellena a la vez la calle, el código postal y la ciudad con una dirección normalizada.

Requisitos

• PrestaShop 8.0 a 9.x (tema Classic, Hummingbird o la mayoría de temas de terceros)
• PHP 7.4 o superior
• Sólo para Google Places: una clave de API de Google Cloud con las APIs Places API y Maps JavaScript API activadas

Instalación

1. En el back office de PrestaShop, abra Módulos → Gestor de módulos.
2. Haga clic en Subir un módulo y suelte el archivo dfaddresslookup.zip.
3. PrestaShop instala el módulo y registra automáticamente los hooks actionFrontControllerSetMedia y displayHeader.
4. Haga clic en Configurar para abrir la pantalla de ajustes.

Nada más instalarlo, el autocompletado está activo para Francia sin ninguna configuración: la API BAN está activada por defecto y no requiere clave.

Configuración

API francesa BAN

Activar la API BAN francesa — activa o desactiva el motor francés. Activado por defecto. La API api-adresse.data.gouv.fr es un servicio público gratuito: sin clave, sin suscripción, límite indicativo de 50 peticiones por segundo y por IP, muy por encima de las necesidades de un checkout.

Rellenar la ciudad desde el código postal — cuando el cliente teclea un código postal francés de 5 dígitos, la ciudad se rellena automáticamente si un solo municipio coincide; si no, aparece un selector de municipios bajo el campo. El módulo nunca sustituye una ciudad ya escrita por el cliente.

Google Places (opcional)

Activar Google Places — activa el motor internacional. Requiere una clave de API válida; de lo contrario se rechaza el guardado de la configuración.

Clave de API de Google — su clave de Google Cloud. Vea la sección siguiente para crearla y protegerla.

Países permitidos — lista de códigos ISO 3166-1 alfa-2 separados por comas (ej. BE,CH,LU,DE). Google Places sólo se activa para esos países; campo vacío = todos los países. Es la palanca principal para controlar su facturación de Google Cloud.

Comportamiento

Caracteres mínimos — número de caracteres antes de que se disparen las sugerencias (2 a 10, por defecto 3).

Debounce (ms) — retardo entre la última pulsación y la llamada a la API (80 a 2000 ms, por defecto 250). Auméntelo para reducir el número de peticiones, redúzcalo para sugerencias más reactivas.

Resaltar coincidencias — pone en negrita el texto tecleado por el cliente dentro de cada sugerencia.

Obtener una clave de Google Places

1. Abra la Google Cloud Console y seleccione o cree un proyecto.
2. En APIs y servicios → Biblioteca, active Places API y Maps JavaScript API.
3. En APIs y servicios → Credenciales, cree una clave de API.
4. Restrinja la clave: Restricciones de aplicaciones → «Referentes HTTP» → añada su dominio (ej. *.mitienda.es/*); Restricciones de API → limite a Places API y Maps JavaScript API.
5. Pegue la clave en la configuración del módulo y guarde.

Funcionamiento técnico

Cambio automático entre motores

El módulo lee el país seleccionado en el campo id_country del formulario. Francia → motor BAN. Otro país presente en la lista de países permitidos → Google Places. País fuera de la lista o ningún motor aplicable → el autocompletado se desactiva silenciosamente y el formulario sigue siendo un formulario de entrada clásico. El cambio es inmediato con cada cambio de país, sin recargar la página.

Compatibilidad con checkout one-page y re-renderizados

El checkout de PrestaShop vuelve a mostrar el formulario de dirección en cada cambio de paso. El módulo vigila el DOM con un MutationObserver y se suscribe a los eventos nativos updatedAddressForm, updatedAddress, updatedDeliveryForm y changedCheckoutStep: el autocompletado se vuelve a vincular automáticamente en cada re-renderizado. Cada formulario se marca tras la vinculación para evitar dobles vinculaciones.

Formularios múltiples

Si se muestran varios formularios de dirección simultáneamente (envío + facturación), cada uno recibe su propio autocompletado independiente, con su propio menú y su propio estado.

Navegación por teclado y accesibilidad

El menú de sugerencias se maneja completamente con el teclado: flechas arriba/abajo para navegar, Intro para seleccionar, Escape para cerrar. Las sugerencias llevan los atributos ARIA role="listbox" y role="option".

Degradación elegante

Si la API es inalcanzable (caída, cliente sin conexión, bloqueo de red), no se muestra ningún error: el formulario sigue siendo un formulario de entrada manual clásico. El autocompletado es una mejora progresiva, nunca un punto de bloqueo del checkout.

RGPD y privacidad

• Las peticiones de autocompletado van directamente del navegador del cliente a la API BAN (servicio público francés) o a Google Places.
• Ningún dato pasa por su servidor PrestaShop durante la escritura.
• Ningún dato pasa jamás por los servidores de DataFirefly.
• El módulo no coloca ninguna cookie.
• Si activa Google Places, mencione a Google en su política de privacidad como destinatario de las entradas de dirección para los países afectados.

Solución de problemas

Las sugerencias no aparecen

• Compruebe que el motor correspondiente está activado en la configuración del módulo.
• Compruebe el número de caracteres mínimos: las sugerencias sólo se disparan a partir del umbral configurado.
• Vacíe la caché de PrestaShop (Parámetros avanzados → Rendimiento) para forzar la recarga de los assets JS/CSS.
• Abra la consola del navegador: un error CORS o un bloqueo por una extensión (adblock, protección de privacidad) puede impedir las llamadas a la API.

Google Places no se activa

• Compruebe que el país seleccionado figura en la lista de países permitidos (o que la lista está vacía).
• Compruebe en la consola del navegador que el script de Google Maps se carga sin error: una clave inválida, una API no activada o una restricción de referente demasiado estricta producen un error explícito Google Maps JavaScript API error.
• Compruebe que la facturación está activada en su proyecto de Google Cloud: las APIs de Places rechazan las peticiones sin cuenta de facturación activa.

La ciudad no se rellena desde el código postal

• Esta función sólo afecta al motor BAN (Francia) y se desactiva si el campo ciudad ya contiene un valor escrito por el cliente.
• Algunos códigos postales cubren varios municipios: el módulo muestra entonces un selector en lugar de rellenar automáticamente.

Conflicto con un módulo de checkout de terceros

El módulo apunta a los campos por sus atributos name estándar (address1, postcode, city, id_country). Los checkouts one-page de terceros que conservan estos nombres de campo funcionan sin configuración. Si un módulo de terceros renombra los campos, el autocompletado se desactiva silenciosamente sin romper el checkout — contacte con el soporte indicando el nombre del módulo afectado.

FAQ

¿El módulo ralentiza mi tienda?

No. El JS y el CSS sólo se cargan en las 4 páginas que contienen un formulario de dirección, y todas las peticiones de autocompletado las ejecuta el navegador del cliente, nunca su servidor.

¿Puedo usar sólo la API francesa sin Google?

Sí, es el modo por defecto. Google Places es estrictamente opcional y no se carga mientras no esté activado con una clave válida.

¿Funciona el módulo en multi-tienda?

Sí. La configuración se gestiona mediante la tabla de configuración nativa de PrestaShop y respeta el contexto multi-tienda estándar.

¿Qué ocurre al desinstalar?

Se eliminan todas las claves de configuración. Al no haberse creado ninguna tabla, la desinstalación no deja rastro alguno.

Changelog

1.0.0 — 15 de mayo de 2026

• Primera versión pública
• API francesa BAN integrada por defecto (gratuita, sin clave)
• Google Places opcional con clave de API y lista de países permitidos
• Rellenado código postal → ciudad → calle
• Compatible con PrestaShop 8.0 a 9.x, checkout one-page y multi-paso
• Navegación por teclado, resaltado de coincidencias, debounce configurable
• Sin sobrecarga de plantillas, sin tablas SQL