# 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…

- Página: <https://www.datafirefly.com/es/documentation/dfaddresslookup/>
- Idioma: es
- Actualizado el: 2026-08-25
- Otros idiomas: [fr](https://www.datafirefly.com/documentation/dfaddresslookup/index.md), [en](https://www.datafirefly.com/en/documentation/dfaddresslookup/index.md), [de](https://www.datafirefly.com/de/documentation/dfaddresslookup/index.md), [it](https://www.datafirefly.com/it/documentation/dfaddresslookup/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfaddresslookup/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfaddresslookup/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfaddresslookup/index.md)
- Índice: <https://www.datafirefly.com/es/documentation/llms.txt>

## 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 (data.geopf.fr/geocodage), 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.

**Ningún dato pasa por su servidor ni por DataFirefly.** Las peticiones van directamente del navegador del cliente a la API BAN o a Google Places. El módulo no crea ninguna tabla SQL y no sobrecarga ninguna plantilla Smarty.

## 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 (New)_ 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 data.geopf.fr/geocodage 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](https://console.cloud.google.com/) y seleccione o cree un proyecto.
2. En **APIs y servicios → Biblioteca**, active **Places API (New)** 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 (New) y Maps JavaScript API.
5. Pegue la clave en la configuración del módulo y guarde.

No despliegue nunca una clave de Google sin restricción de referente HTTP: podría ser utilizada por cualquier sitio de terceros y generar facturación a su cargo.

## 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.1.0 — 23 de agosto de 2026

- Migración del motor Google a Places API (New): API programática AutocompleteSuggestion con tokens de sesión y Place.fetchFields; el widget legacy no está disponible para los nuevos clientes de Google Cloud desde marzo de 2025
- Las sugerencias de Google se muestran en el menú propio del módulo: UX unificada, navegación por teclado, resaltado, restricción al país seleccionado
- Francia puede ser atendida completamente por Google Places desactivando el motor BAN

### 1.0.3 — 23 de agosto de 2026

- Corrección: en algunos temas, un script de terceros restauraba el texto tecleado en el campo calle tras seleccionar una sugerencia, dejando la dirección sin rellenar; la calle se escribe ahora en último lugar y su valor se reafirma si es sobrescrito
- La protección contra la reapertura del menú de sugerencias usa ahora una ventana temporal

### 1.0.2 — 23 de agosto de 2026

- Corrección: el menú de sugerencias permanecía abierto tras seleccionar una dirección, ya que la búsqueda se relanzaba por los eventos sintéticos emitidos al rellenar los campos

### 1.0.1 — 1 de julio de 2026

- Migración del motor francés al servicio de geocodificación Géoplateforme (data.geopf.fr/geocodage, IGN), tras la retirada del antiguo endpoint api-adresse.data.gouv.fr a finales de enero de 2026
- API iso-funcional: mismos parámetros, misma respuesta GeoJSON, mismo límite de 50 peticiones por segundo y por IP
- Etiquetas del back office y atribución de las sugerencias actualizadas

### 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