PS PrestaShop Principiante

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.

Actualizado Versión del módulo 2.0.0

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 a api-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

  1. En Módulos > Gestor de módulos, haga clic en Subir un módulo y deposite dfaddresslookup-2.0.0.zip.
  2. 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.

Resumen del módulo: países atendidos por la Géoplateforme y por Google Places, estado de las páginas y contadores de los últimos 30 días
Resumen del módulo

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.

Proveedor de cada país: Géoplateforme para Francia, Guadalupe y Reunión, Google Places para los países que no cubre
Proveedor de cada país

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.
Ajustes de búsqueda: mínimo de caracteres, espera antes de buscar, número de sugerencias, tiempo máximo, páginas y color
Ajustes de búsqueda

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.

  1. En la consola de Google Cloud, cree o elija un proyecto con la facturación activada.
  2. En API y servicios, active Places API (New) y Maps JavaScript API.
  3. Cree una clave de API en Credenciales.
  4. 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).
  5. Restricciones de API: limite la clave a Places API (New) y Maps JavaScript API.
  6. 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.

Clave de Google Places API (New): activación, solo direcciones, facturación por sesión y pasos para restringir la clave
Clave de Google Places API (New)

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).

Vista previa y prueba de conexión: sugerencias de la Géoplateforme y respuesta de Google Places desde el back office
Vista previa y prueba de conexión

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.

Sugerencias de dirección en el proceso de compra: plazas del Hôtel de Ville con código postal, ciudad y región
Sugerencias de dirección en el proceso de compra
Navegación con el teclado: flechas para recorrer las sugerencias, Intro para elegir, Esc para cerrar
Navegación con el teclado

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.

Formulario rellenado tras la elección: dirección, código postal y ciudad resaltados, complemento sin tocar
Formulario rellenado tras la elección

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.

Código postal compartido por varios municipios: lista de ciudades bajo el campo Código postal
Código postal compartido por varios municipios

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.

Ninguna dirección encontrada: mensaje claro y botón de introducción manual, el pedido nunca se bloquea
Ninguna dirección encontrada

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.

Dirección en Estados Unidos: sugerencias de Google Places (New) con la atribución Google Maps
Dirección en Estados Unidos

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.

En el móvil: sugerencias bajo el campo, zonas táctiles amplias y botón de introducción manual
En el móvil
Mi cuenta, Mis direcciones: las mismas sugerencias para añadir o modificar una dirección
Mi cuenta, Mis direcciones

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.

Aviso bajo el campo Dirección: texto por idioma, enlace a una página y destino de los datos escritos
Aviso bajo el campo Dirección

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.

Estadísticas de uso: búsquedas, direcciones elegidas, sin resultados, errores y sesiones de Google, sin datos personales
Estadísticas de uso

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 eval y no tiene proxy en el servidor.
  • Si su tienda envía una cabecera CSP: connect-src https://data.geopf.fr para 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
¿Te ha resultado útil esta página?

¿Sigues atascado? Contacta con soporte