DataFirefly Address Lookup — Documentatie

Overzicht

DataFirefly Address Lookup voegt automatische adresaanvulling toe aan de formulieren van PrestaShop 8 en 9: het afrekenproces, de pagina “Mijn adres”, de pagina “Mijn gegevens” en het registratieformulier. De module steunt op twee motoren: de Franse BAN-API (data.geopf.fr/geocodage), gratis en zonder sleutel, standaard ingeschakeld voor Frankrijk, en Google Places als optie voor internationale adressen.

Het traject van de klant is eenvoudig: hij typt zijn postcode, de plaats wordt automatisch ingevuld (of er verschijnt een keuzelijst met gemeenten als er meerdere passen); hij begint zijn straat te typen, de suggesties verschijnen; met een klik worden straat, postcode en plaats in een keer gevuld met een genormaliseerd adres.

Vereisten

• PrestaShop 8.0 tot 9.x (Classic-thema, Hummingbird of de meeste externe thema’s)
• PHP 7.4 of hoger
• Alleen voor Google Places: een Google Cloud API-sleutel met de Places API (New) en de Maps JavaScript API ingeschakeld

Installatie

1. Open in de backoffice van PrestaShop Modules → Modulebeheer.
2. Klik op Een module uploaden en sleep het bestand dfaddresslookup.zip erin.
3. PrestaShop installeert de module en registreert automatisch de hooks actionFrontControllerSetMedia en displayHeader.
4. Klik op Configureren om het instellingenscherm te openen.

Direct na de installatie is de aanvulfunctie actief voor Frankrijk, zonder enige configuratie: de BAN-API staat standaard aan en heeft geen sleutel nodig. Voor Nederlandse adressen schakelt u daarnaast Google Places in.

Configuratie

Franse BAN-API

Franse BAN-API inschakelen — zet de Franse motor aan of uit. Standaard ingeschakeld. De API data.geopf.fr/geocodage is een gratis openbare dienst: geen sleutel, geen abonnement, een richtlimiet van 50 aanvragen per seconde per IP, ruim boven wat een checkout nodig heeft.

Plaats automatisch invullen vanuit de postcode — wanneer de klant een Franse postcode van 5 cijfers typt, wordt de plaats automatisch ingevuld als er een enkele gemeente bij past; anders verschijnt er een keuzelijst met gemeenten onder het veld. De module overschrijft nooit een plaats die de klant al heeft getypt.

Google Places (optioneel)

Google Places inschakelen — zet de internationale motor aan. Vereist een geldige API-sleutel; anders wordt het opslaan van de configuratie geweigerd.

Google API-sleutel — uw Google Cloud-sleutel. Zie de volgende sectie om die aan te maken en te beveiligen.

Toegestane landen — lijst van ISO 3166-1 alpha-2 codes, gescheiden door komma’s (bijv. NL,BE,DE). Google Places wordt alleen geactiveerd voor deze landen; een leeg veld betekent alle landen. Dit is de belangrijkste hendel om uw Google Cloud-facturatie in de hand te houden.

Gedrag

Minimaal aantal tekens — aantal tekens voordat de suggesties starten (2 tot 10, standaard 3).

Debounce (ms) — wachttijd tussen de laatste toetsaanslag en de API-aanvraag (80 tot 2000 ms, standaard 250). Verhoog de waarde om het aantal aanvragen te beperken, verlaag hem voor snellere suggesties.

Overeenkomsten oplichten — zet de door de klant getypte tekst vet in elke suggestie.

Een Google Places-sleutel verkrijgen

1. Open de Google Cloud Console en selecteer of maak een project.
2. Schakel onder APIs & Services → Bibliotheek de Places API (New) en de Maps JavaScript API in.
3. Maak onder APIs & Services → Inloggegevens een API-sleutel aan.
4. Beperk de sleutel: Applicatiebeperkingen → “HTTP-verwijzers” → voeg uw domein toe (bijv. *.uwwinkel.nl/*); API-beperkingen → beperk tot Places API (New) en Maps JavaScript API.
5. Plak de sleutel in de configuratie van de module en sla op.

Technische werking

Automatisch wisselen tussen de motoren

De module leest het land dat is gekozen in het veld id_country van het formulier. Frankrijk → BAN-motor. Een ander land dat op de lijst met toegestane landen staat → Google Places. Een land buiten de lijst of geen toepasbare motor → de aanvulfunctie schakelt zichzelf stil uit en het formulier blijft een gewoon invoerformulier. Het wisselen gebeurt onmiddellijk bij elke landwijziging, zonder de pagina te herladen.

Compatibiliteit met de one-page checkout en het opnieuw opbouwen

De checkout van PrestaShop bouwt het adresformulier bij elke stapwissel opnieuw op. De module houdt de DOM in de gaten met een MutationObserver en luistert naar de native events updatedAddressForm, updatedAddress, updatedDeliveryForm en changedCheckoutStep: de aanvulfunctie koppelt zich bij elke heropbouw automatisch opnieuw. Elk formulier wordt na de koppeling gemarkeerd om dubbele koppelingen te voorkomen.

Meerdere formulieren

Staan er meerdere adresformulieren tegelijk in beeld (bezorging en facturatie), dan krijgt elk zijn eigen, onafhankelijke aanvulfunctie, met een eigen suggestielijst en een eigen status.

Toetsenbordbediening en toegankelijkheid

De suggestielijst is volledig met het toetsenbord te bedienen: pijltjes omhoog en omlaag om te navigeren, Enter om te kiezen, Escape om te sluiten. De suggesties dragen de ARIA-attributen role="listbox" en role="option".

Nette terugval

Is de API onbereikbaar (storing, klant offline, netwerkblokkade), dan wordt er geen foutmelding getoond: het formulier blijft een gewoon formulier voor handmatige invoer. De aanvulfunctie is een progressieve verbetering, nooit een blokkade in het afrekenproces.

AVG en privacy

• De aanvraag voor het aanvullen gaat rechtstreeks vanuit de browser van de klant naar de BAN-API (Franse openbare dienst) of naar Google Places.
• Er lopen tijdens het typen geen gegevens via uw PrestaShop-server.
• Er lopen nooit gegevens via de servers van DataFirefly.
• De module plaatst geen enkele cookie.
• Schakelt u Google Places in, vermeld Google dan in uw privacybeleid als ontvanger van de adresinvoer voor de betrokken landen. Voor een winkel gericht op de Nederlandse markt betreft dat het overgrote deel van de bestellingen.

Probleemoplossing

De suggesties verschijnen niet

• Controleer of de betreffende motor is ingeschakeld in de configuratie van de module.
• Controleer het minimale aantal tekens: de suggesties starten pas vanaf de ingestelde drempel.
• Leeg de PrestaShop-cache (Geavanceerde instellingen → Prestaties) om het herladen van de JS- en CSS-bestanden af te dwingen.
• Open de browserconsole: een CORS-fout of een blokkade door een extensie (adblocker, privacybescherming) kan de API-aanvragen tegenhouden.

Google Places wordt niet geactiveerd

• Controleer of het gekozen land op de lijst met toegestane landen staat (of dat de lijst leeg is).
• Controleer in de browserconsole of het Google Maps-script zonder fout laadt: een ongeldige sleutel, een niet-ingeschakelde API of een te strikte verwijzerbeperking geeft een duidelijke Google Maps JavaScript API error.
• Controleer of de facturering is ingeschakeld op uw Google Cloud-project: de Places-API’s weigeren aanvragen zonder actief factureringsaccount.

De plaats wordt niet ingevuld vanuit de postcode

• Deze functie geldt alleen voor de BAN-motor (Frankrijk) en schakelt zichzelf uit als het plaatsveld al een door de klant getypte waarde bevat. Voor Nederlandse postcodes verzorgt Google Places het invullen bij de adressuggestie.
• Sommige postcodes dekken meerdere gemeenten: de module toont dan een keuzelijst in plaats van automatisch in te vullen.

Conflict met een externe checkoutmodule

De module vindt de velden via hun standaard name-attributen (address1, postcode, city, id_country). Externe one-page checkouts die deze veldnamen behouden, werken zonder configuratie. Hernoemt een externe module de velden, dan schakelt de aanvulfunctie zichzelf stil uit zonder het afrekenproces te breken — neem contact op met de support en vermeld de naam van de betreffende module.

FAQ

Vertraagt de module mijn winkel?

Nee. De JS en CSS laden alleen op de 4 pagina’s met een adresformulier, en alle aanvraag voor het aanvullen worden uitgevoerd door de browser van de klant, nooit door uw server.

Kan ik alleen de Franse API gebruiken, zonder Google?

Ja, dat is de standaardmodus. Google Places is strikt optioneel en laadt pas wanneer het is ingeschakeld met een geldige sleutel. Voor Nederlandse adressen blijft het echter noodzakelijk.

Werkt de module in multishop?

Ja. De configuratie wordt beheerd via de native configuratietabel van PrestaShop en respecteert de standaard multishop-context.

Wat gebeurt er bij het verwijderen?

Alle configuratiesleutels worden gewist. Omdat er geen tabel is aangemaakt, laat het verwijderen geen enkel spoor achter.

Changelog

1.1.0 — 23 augustus 2026

• Migratie van de Google-motor naar Places API (New): programmatische AutocompleteSuggestion-API met sessietokens en Place.fetchFields; de legacy-widget is sinds maart 2025 niet meer beschikbaar voor nieuwe Google Cloud-klanten
• Google-suggesties verschijnen in de eigen lijst van de module: uniforme UX, toetsenbordbediening, oplichten van overeenkomsten, beperking tot het gekozen land
• Frankrijk kan volledig door Google Places worden bediend door de BAN-motor uit te schakelen

1.0.3 — 23 augustus 2026

• Opgelost: bij sommige thema’s zette een extern script na het kiezen van een suggestie de getypte tekst terug in het straatveld, waardoor het adres niet werd ingevuld; de straat wordt nu als laatste geschreven en de waarde wordt opnieuw gezet bij overschrijving
• De bescherming tegen het heropenen van de suggestielijst gebruikt nu een tijdvenster

1.0.2 — 23 augustus 2026

• Opgelost: de suggestielijst bleef open na het kiezen van een adres, doordat de zoekopdracht opnieuw werd gestart door de synthetische events die bij het invullen van de velden worden afgevuurd

1.0.1 — 1 juli 2026

• Migratie van de Franse motor naar de geocodeerdienst Géoplateforme (data.geopf.fr/geocodage, IGN), nadat het oude endpoint api-adresse.data.gouv.fr eind januari 2026 werd uitgeschakeld
• Iso-functionele API: dezelfde parameters, hetzelfde GeoJSON-antwoord, dezelfde limiet van 50 aanvragen per seconde per IP
• Bijgewerkte backoffice-labels en bronvermelding van de suggesties

1.0.0 — 15 mei 2026

• Eerste publieke versie
• Franse BAN-API standaard ingebouwd (gratis, zonder sleutel)
• Google Places als optie, met een API-sleutel en een lijst toegestane landen
• Automatisch invullen van postcode, plaats en straat
• Compatibel met PrestaShop 8.0 tot 9.x, one-page checkout en afrekenen in stappen
• Toetsenbordbediening, oplichten van overeenkomsten, instelbare debounce
• Geen enkele overschreven template en geen enkele SQL-tabel