PS PrestaShop PrestaShop Principiante

DataFirefly Address Lookup — Documentazione

Installazione, configurazione e risoluzione dei problemi del completamento automatico degli indirizzi al checkout: API BAN francese gratuita e Google Places opzionale.

Aggiornato Versione del modulo 1.0.0

Panoramica

DataFirefly Address Lookup aggiunge il completamento automatico degli indirizzi ai moduli di PrestaShop 8 e 9: il checkout, la pagina «Il mio indirizzo», la pagina «I miei dati» e il modulo di registrazione. Il modulo si basa su due motori: l’API francese BAN (api-adresse.data.gouv.fr), gratuita e senza chiave, attivata di default per la Francia, e Google Places come opzione per gli indirizzi internazionali.

Il flusso del cliente è semplice: digita il codice postale, la città si compila automaticamente (o appare un selettore di comuni se più di uno corrisponde); inizia a digitare la via, i suggerimenti appaiono; un clic compila in una volta via, codice postale e città con un indirizzo normalizzato.

Nessun dato passa dal vostro server né da DataFirefly. Le richieste vanno direttamente dal browser del cliente all’API BAN o a Google Places. Il modulo non crea alcuna tabella SQL e non sovrascrive alcun template Smarty.

Requisiti

  • PrestaShop da 8.0 a 9.x (tema Classic, Hummingbird o la maggior parte dei temi di terze parti)
  • PHP 7.4 o superiore
  • Solo per Google Places: una chiave API di Google Cloud con le API Places API e Maps JavaScript API attivate

Installazione

  1. Nel back office di PrestaShop, aprite Moduli → Gestione moduli.
  2. Cliccate su Carica un modulo e trascinate il file dfaddresslookup.zip.
  3. PrestaShop installa il modulo e registra automaticamente gli hook actionFrontControllerSetMedia e displayHeader.
  4. Cliccate su Configura per aprire la schermata delle impostazioni.

Subito dopo l’installazione, il completamento automatico è attivo per la Francia senza alcuna configurazione: l’API BAN è attivata di default e non richiede chiave.

Configurazione

API francese BAN

Attivare l’API BAN francese — attiva o disattiva il motore francese. Attivato di default. L’API api-adresse.data.gouv.fr è un servizio pubblico gratuito: nessuna chiave, nessun abbonamento, limite indicativo di 50 richieste al secondo per IP, ben oltre le esigenze di un checkout.

Compilare la città dal codice postale — quando il cliente digita un codice postale francese a 5 cifre, la città si compila automaticamente se un solo comune corrisponde; altrimenti appare un selettore di comuni sotto il campo. Il modulo non sostituisce mai una città già digitata dal cliente.

Google Places (opzionale)

Attivare Google Places — attiva il motore internazionale. Richiede una chiave API valida; in caso contrario il salvataggio della configurazione viene rifiutato.

Chiave API Google — la vostra chiave Google Cloud. Vedere la sezione successiva per crearla e proteggerla.

Paesi consentiti — elenco di codici ISO 3166-1 alpha-2 separati da virgole (es. BE,CH,LU,DE). Google Places si attiva solo per questi paesi; campo vuoto = tutti i paesi. È la leva principale per tenere sotto controllo la fatturazione Google Cloud.

Comportamento

Caratteri minimi — numero di caratteri prima che i suggerimenti si attivino (da 2 a 10, default 3).

Debounce (ms) — ritardo tra l’ultima digitazione e la chiamata API (da 80 a 2000 ms, default 250). Aumentatelo per ridurre il numero di richieste, riducetelo per suggerimenti più reattivi.

Evidenziare le corrispondenze — mette in grassetto il testo digitato dal cliente in ogni suggerimento.

Ottenere una chiave Google Places

  1. Aprite la Google Cloud Console e selezionate o create un progetto.
  2. In API e servizi → Libreria, attivate Places API e Maps JavaScript API.
  3. In API e servizi → Credenziali, create una chiave API.
  4. Limitate la chiave: Restrizioni delle applicazioni → «Referrer HTTP» → aggiungete il vostro dominio (es. *.mionegozio.it/*); Restrizioni API → limitate a Places API e Maps JavaScript API.
  5. Incollate la chiave nella configurazione del modulo e salvate.

Non distribuite mai una chiave Google senza restrizione di referrer HTTP: potrebbe essere utilizzata da qualsiasi sito di terze parti e generare fatturazione a vostro carico.

Funzionamento tecnico

Cambio automatico tra i motori

Il modulo legge il paese selezionato nel campo id_country del modulo. Francia → motore BAN. Altro paese presente nell’elenco dei paesi consentiti → Google Places. Paese fuori elenco o nessun motore applicabile → il completamento automatico si disattiva silenziosamente e il modulo resta un classico modulo di inserimento. Il cambio è immediato a ogni cambio di paese, senza ricaricare la pagina.

Compatibilità con checkout one-page e ri-rendering

Il checkout di PrestaShop ri-visualizza il modulo indirizzo a ogni cambio di passaggio. Il modulo sorveglia il DOM con un MutationObserver e si iscrive agli eventi nativi updatedAddressForm, updatedAddress, updatedDeliveryForm e changedCheckoutStep: il completamento automatico si ricollega automaticamente a ogni ri-rendering. Ogni modulo viene contrassegnato dopo il collegamento per evitare doppi collegamenti.

Moduli multipli

Se più moduli indirizzo sono visualizzati contemporaneamente (spedizione + fatturazione), ciascuno riceve il proprio completamento automatico indipendente, con il proprio menu e il proprio stato.

Il menu dei suggerimenti si controlla interamente da tastiera: frecce su/giù per navigare, Invio per selezionare, Esc per chiudere. I suggerimenti portano gli attributi ARIA role="listbox" e role="option".

Degradazione elegante

Se l’API è irraggiungibile (guasto, cliente offline, blocco di rete), non viene mostrato alcun errore: il modulo resta un classico modulo di inserimento manuale. Il completamento automatico è un miglioramento progressivo, mai un punto di blocco del checkout.

GDPR e privacy

  • Le richieste di completamento automatico vanno direttamente dal browser del cliente all’API BAN (servizio pubblico francese) o a Google Places.
  • Nessun dato passa dal vostro server PrestaShop durante la digitazione.
  • Nessun dato passa mai dai server DataFirefly.
  • Il modulo non imposta alcun cookie.
  • Se attivate Google Places, menzionate Google nella vostra informativa sulla privacy come destinatario degli inserimenti di indirizzo per i paesi interessati.

Risoluzione dei problemi

I suggerimenti non appaiono

  • Verificate che il motore interessato sia attivato nella configurazione del modulo.
  • Verificate il numero di caratteri minimi: i suggerimenti si attivano solo a partire dalla soglia configurata.
  • Svuotate la cache di PrestaShop (Parametri avanzati → Prestazioni) per forzare il ricaricamento degli asset JS/CSS.
  • Aprite la console del browser: un errore CORS o un blocco da parte di un’estensione (adblock, protezione privacy) può impedire le chiamate all’API.

Google Places non si attiva

  • Verificate che il paese selezionato figuri nell’elenco dei paesi consentiti (o che l’elenco sia vuoto).
  • Verificate nella console del browser che lo script di Google Maps si carichi senza errori: una chiave non valida, un’API non attivata o una restrizione di referrer troppo severa producono un errore esplicito Google Maps JavaScript API error.
  • Verificate che la fatturazione sia attivata sul vostro progetto Google Cloud: le API Places rifiutano le richieste senza account di fatturazione attivo.

La città non si compila dal codice postale

  • Questa funzione riguarda solo il motore BAN (Francia) e si disattiva se il campo città contiene già un valore digitato dal cliente.
  • Alcuni codici postali coprono più comuni: il modulo mostra allora un selettore invece di compilare automaticamente.

Conflitto con un modulo di checkout di terze parti

Il modulo individua i campi tramite i loro attributi name standard (address1, postcode, city, id_country). I checkout one-page di terze parti che mantengono questi nomi di campo funzionano senza configurazione. Se un modulo di terze parti rinomina i campi, il completamento automatico si disattiva silenziosamente senza rompere il checkout — contattate il supporto indicando il nome del modulo interessato.

FAQ

Il modulo rallenta il mio negozio?

No. JS e CSS si caricano solo sulle 4 pagine che contengono un modulo indirizzo, e tutte le richieste di completamento automatico vengono eseguite dal browser del cliente, mai dal vostro server.

Posso usare solo l’API francese senza Google?

Sì, è la modalità di default. Google Places è strettamente opzionale e non si carica finché non viene attivato con una chiave valida.

Il modulo funziona in multi-negozio?

Sì. La configurazione è gestita dalla tabella di configurazione nativa di PrestaShop e rispetta il contesto multi-negozio standard.

Cosa succede alla disinstallazione?

Tutte le chiavi di configurazione vengono eliminate. Non essendo stata creata alcuna tabella, la disinstallazione non lascia alcuna traccia.

Changelog

1.0.0 — 15 maggio 2026

  • Prima versione pubblica
  • API francese BAN integrata di default (gratuita, senza chiave)
  • Google Places opzionale con chiave API ed elenco di paesi consentiti
  • Compilazione codice postale → città → via
  • Compatibile con PrestaShop da 8.0 a 9.x, checkout one-page e multi-step
  • Navigazione da tastiera, evidenziazione delle corrispondenze, debounce configurabile
  • Nessuna sovrascrittura di template, nessuna tabella SQL
Questa pagina ti è stata utile?

Ancora bloccato? Contatta l'assistenza