# DataFirefly Address Lookup — Documentazione

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

- Pagina: <https://www.datafirefly.com/it/documentation/dfaddresslookup/>
- Lingua: it
- Aggiornato il: 2026-08-25
- Altre lingue: [fr](https://www.datafirefly.com/documentation/dfaddresslookup/index.md), [en](https://www.datafirefly.com/en/documentation/dfaddresslookup/index.md), [es](https://www.datafirefly.com/es/documentation/dfaddresslookup/index.md), [de](https://www.datafirefly.com/de/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)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

## 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 (data.geopf.fr/geocodage), 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 (New)_ 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 data.geopf.fr/geocodage è 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](https://console.cloud.google.com/) e selezionate o create un progetto.
2. In **API e servizi → Libreria**, attivate **Places API (New)** 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 (New) 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.

### Navigazione da tastiera e accessibilità

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

- Migrazione del motore Google a Places API (New): API programmatica AutocompleteSuggestion con session token e Place.fetchFields; il widget legacy non è più disponibile per i nuovi clienti Google Cloud da marzo 2025
- I suggerimenti Google appaiono nel menu del modulo: UX unificata, navigazione da tastiera, evidenziazione, restrizione al paese selezionato
- La Francia può essere servita interamente da Google Places disattivando il motore BAN

### 1.0.3 — 23 agosto 2026

- Correzione: su alcuni temi, uno script di terze parti ripristinava il testo digitato nel campo via dopo la selezione di un suggerimento, lasciando l'indirizzo non compilato; la via viene ora scritta per ultima e il suo valore riaffermato se sovrascritto
- La protezione contro la riapertura del menu dei suggerimenti usa ora una finestra temporale

### 1.0.2 — 23 agosto 2026

- Correzione: il menu dei suggerimenti restava aperto dopo la selezione di un indirizzo, poiché la ricerca veniva rilanciata dagli eventi sintetici emessi durante la compilazione dei campi

### 1.0.1 — 1 luglio 2026

- Migrazione del motore francese al servizio di geocodifica Géoplateforme (data.geopf.fr/geocodage, IGN), dopo la dismissione del vecchio endpoint api-adresse.data.gouv.fr a fine gennaio 2026
- API iso-funzionale: stessi parametri, stessa risposta GeoJSON, stesso limite di 50 richieste al secondo per IP
- Etichette del back office e attribuzione dei suggerimenti aggiornate

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