PS PrestaShop PrestaShop Débutant

DataFirefly Address Lookup — Documentation

Installation, configuration et dépannage de l'autocomplétion d'adresse au checkout : API BAN française gratuite et Google Places en option.

Mis à jour Version du module 1.0.0

Présentation

DataFirefly Address Lookup ajoute l’autocomplétion d’adresse aux formulaires de PrestaShop 8 et 9 : tunnel de commande, page « Mon adresse », page « Mes informations » et formulaire d’inscription. Le module s’appuie sur deux moteurs : l’API française BAN (api-adresse.data.gouv.fr), gratuite et sans clé, activée par défaut pour la France, et Google Places en option pour les adresses internationales.

Le workflow côté client est simple : il saisit son code postal, la ville se remplit automatiquement (ou un sélecteur de communes s’affiche si plusieurs correspondent) ; il commence à taper sa rue, les suggestions apparaissent ; un clic remplit d’un coup la rue, le code postal et la ville avec une adresse normalisée.

Aucune donnée ne transite par votre serveur ni par DataFirefly. Les requêtes partent directement du navigateur du client vers l’API BAN ou Google Places. Le module ne crée aucune table SQL et ne surcharge aucun template Smarty.

Prérequis

  • PrestaShop 8.0 à 9.x (thème Classic, Hummingbird ou la plupart des thèmes tiers)
  • PHP 7.4 ou supérieur
  • Pour Google Places uniquement : une clé d’API Google Cloud avec les APIs Places API et Maps JavaScript API activées

Installation

  1. Dans le back-office PrestaShop, ouvrez Modules → Gestionnaire de modules.
  2. Cliquez sur Installer un module et déposez le fichier dfaddresslookup.zip.
  3. PrestaShop installe le module et enregistre automatiquement les hooks actionFrontControllerSetMedia et displayHeader.
  4. Cliquez sur Configurer pour ouvrir l’écran de réglages.

Dès l’installation, l’autocomplétion est active pour la France sans aucune configuration : l’API BAN est activée par défaut et ne nécessite pas de clé.

Configuration

API française BAN

Activer l’API BAN française — active ou désactive le moteur français. Activé par défaut. L’API api-adresse.data.gouv.fr est un service public gratuit : pas de clé, pas d’abonnement, limite indicative de 50 requêtes par seconde et par IP, très au-delà des besoins d’un checkout.

Pré-remplir la ville depuis le code postal — quand le client saisit un code postal français à 5 chiffres, la ville se remplit automatiquement si une seule commune correspond ; sinon un sélecteur de communes s’affiche sous le champ. Le module ne remplace jamais une ville déjà saisie par le client.

Google Places (optionnel)

Activer Google Places — active le moteur international. Nécessite une clé d’API valide, sans quoi l’enregistrement de la configuration est refusé.

Clé d’API Google — votre clé Google Cloud. Voir la section suivante pour la créer et la sécuriser.

Pays autorisés — liste de codes ISO 3166-1 alpha-2 séparés par des virgules (ex. BE,CH,LU,DE). Google Places ne se déclenche que pour ces pays ; champ vide = tous les pays. C’est le levier principal pour maîtriser votre facturation Google Cloud.

Comportement

Caractères minimum — nombre de caractères avant le déclenchement des suggestions (2 à 10, défaut 3).

Debounce (ms) — délai entre la dernière frappe et l’appel API (80 à 2000 ms, défaut 250). Augmentez-le pour réduire le nombre de requêtes, diminuez-le pour des suggestions plus réactives.

Surligner les correspondances — met en gras le texte tapé par le client dans chaque suggestion.

Obtenir une clé Google Places

  1. Ouvrez la Google Cloud Console et sélectionnez ou créez un projet.
  2. Dans APIs & Services → Bibliothèque, activez Places API et Maps JavaScript API.
  3. Dans APIs & Services → Identifiants, créez une clé d’API.
  4. Restreignez la clé : Restrictions relatives aux applications → « Référents HTTP » → ajoutez votre domaine (ex. *.maboutique.fr/*) ; Restrictions relatives aux API → limitez à Places API et Maps JavaScript API.
  5. Collez la clé dans la configuration du module et enregistrez.

Ne déployez jamais une clé Google sans restriction de référent HTTP : elle serait utilisable par n’importe quel site tiers et pourrait générer une facturation à votre charge.

Fonctionnement technique

Bascule automatique entre moteurs

Le module lit le pays sélectionné dans le champ id_country du formulaire. France → moteur BAN. Autre pays présent dans la liste des pays autorisés → Google Places. Pays hors liste ou aucun moteur applicable → l’autocomplétion se désactive silencieusement et le formulaire reste un formulaire de saisie classique. La bascule est immédiate à chaque changement de pays, sans rechargement de page.

Compatibilité checkout one-page et re-rendus

Le checkout de PrestaShop ré-affiche le formulaire d’adresse à chaque changement d’étape. Le module surveille le DOM avec un MutationObserver et s’abonne aux événements natifs updatedAddressForm, updatedAddress, updatedDeliveryForm et changedCheckoutStep : l’autocomplétion se ré-attache automatiquement à chaque re-rendu. Chaque formulaire est marqué après liaison pour éviter tout double-attachement.

Formulaires multiples

Si plusieurs formulaires d’adresse sont affichés simultanément (livraison + facturation), chacun reçoit son propre autocomplete indépendant, avec son propre dropdown et son propre état.

Le dropdown de suggestions se pilote entièrement au clavier : flèches haut/bas pour naviguer, Entrée pour sélectionner, Échap pour fermer. Les suggestions portent les attributs ARIA role="listbox" et role="option".

Dégradation gracieuse

Si l’API est injoignable (panne, client hors ligne, blocage réseau), aucune erreur n’est affichée : le formulaire reste un formulaire de saisie manuelle classique. L’autocomplétion est une amélioration progressive, jamais un point de blocage du checkout.

RGPD et confidentialité

  • Les requêtes d’autocomplétion partent directement du navigateur du client vers l’API BAN (service public français) ou Google Places.
  • Aucune donnée ne transite par votre serveur PrestaShop pendant la saisie.
  • Aucune donnée ne transite par les serveurs DataFirefly, jamais.
  • Le module ne dépose aucun cookie.
  • Si vous activez Google Places, mentionnez Google dans votre politique de confidentialité comme destinataire des saisies d’adresse pour les pays concernés.

Dépannage

Les suggestions n’apparaissent pas

  • Vérifiez que le moteur concerné est activé dans la configuration du module.
  • Vérifiez le nombre de caractères minimum : les suggestions ne se déclenchent qu’à partir du seuil configuré.
  • Videz le cache PrestaShop (Paramètres avancés → Performances) pour forcer le rechargement des assets JS/CSS.
  • Ouvrez la console navigateur : une erreur CORS ou un blocage par une extension (adblock, protection vie privée) peut empêcher les appels à l’API.

Google Places ne se déclenche pas

  • Vérifiez que le pays sélectionné figure dans la liste des pays autorisés (ou que la liste est vide).
  • Vérifiez dans la console navigateur que le script Google Maps se charge sans erreur : une clé invalide, une API non activée ou une restriction de référent trop stricte produisent une erreur explicite Google Maps JavaScript API error.
  • Vérifiez que la facturation est activée sur votre projet Google Cloud : les APIs Places refusent les requêtes sans compte de facturation actif.

La ville ne se remplit pas depuis le code postal

  • Cette fonction ne concerne que le moteur BAN (France) et se désactive si le champ ville contient déjà une valeur saisie par le client.
  • Certains codes postaux couvrent plusieurs communes : le module affiche alors un sélecteur au lieu de remplir automatiquement.

Conflit avec un module de checkout tiers

Le module cible les champs par leurs attributs name standards (address1, postcode, city, id_country). Les checkouts one-page tiers qui conservent ces noms de champs fonctionnent sans configuration. Si un module tiers renomme les champs, l’autocomplétion se désactive silencieusement sans casser le checkout — contactez le support avec le nom du module concerné.

FAQ

Le module ralentit-il ma boutique ?

Non. Le JS et le CSS ne sont chargés que sur les 4 pages contenant un formulaire d’adresse, et toutes les requêtes d’autocomplétion sont exécutées par le navigateur du client, jamais par votre serveur.

Puis-je utiliser uniquement l’API française sans Google ?

Oui, c’est le mode par défaut. Google Places est strictement optionnel et ne se charge pas tant qu’il n’est pas activé avec une clé valide.

Le module fonctionne-t-il en multi-boutique ?

Oui. La configuration est gérée par la table de configuration native de PrestaShop et respecte le contexte multi-boutique standard.

Que se passe-t-il à la désinstallation ?

Toutes les clés de configuration sont supprimées. Aucune table n’ayant été créée, la désinstallation ne laisse aucune trace.

Changelog

1.0.0 — 15 mai 2026

  • Première version publique
  • API française BAN intégrée par défaut (gratuite, sans clé)
  • Google Places en option avec clé d’API et liste de pays autorisés
  • Pré-remplissage code postal → ville → rue
  • Compatible PrestaShop 8.0 à 9.x, checkout one-page et multi-étapes
  • Navigation clavier, surlignage des correspondances, debounce configurable
  • Aucune surcharge de template, aucune table SQL
Cette page vous a-t-elle été utile ?

Toujours bloqué ? Contactez le support