DataFirefly Address Lookup: documentação

Apresentação

O DataFirefly Address Lookup acrescenta o preenchimento automático de moradas aos formulários do PrestaShop 8 e 9: processo de encomenda, página «A minha morada», página «Os meus dados» e formulário de registo. O módulo assenta em dois motores: a API francesa BAN (data.geopf.fr/geocodage), gratuita e sem chave, ativada por predefinição para a França, e o Google Places, opcional, para as moradas internacionais.

O percurso do lado do cliente é simples: escreve o código postal, a localidade preenche-se automaticamente (ou aparece um seletor de freguesias, se houver várias correspondências); começa a escrever a rua e as sugestões aparecem; um clique preenche de uma vez a rua, o código postal e a localidade com uma morada normalizada.

Pré-requisitos

• PrestaShop 8.0 a 9.x (tema Classic, Hummingbird ou a maioria dos temas de terceiros)
• PHP 7.4 ou superior
• Apenas para o Google Places: uma chave de API do Google Cloud com as APIs Places API (New) e Maps JavaScript API ativadas

Instalação

1. No back-office do PrestaShop, abra Módulos → Gestor de módulos.
2. Clique em Instalar um módulo e carregue o ficheiro dfaddresslookup.zip.
3. O PrestaShop instala o módulo e regista automaticamente os hooks actionFrontControllerSetMedia e displayHeader.
4. Clique em Configurar para abrir o ecrã de definições.

Logo após a instalação, o preenchimento automático está ativo para a França sem qualquer configuração: a API BAN vem ativada por predefinição e não exige chave. Para qualquer outro país, incluindo Portugal, é preciso configurar o Google Places.

Configuração

API francesa BAN

Ativar a API BAN francesa — ativa ou desativa o motor francês. Ativado por predefinição. A API data.geopf.fr/geocodage é um serviço público gratuito: sem chave, sem subscrição e com um limite indicativo de 50 pedidos por segundo e por IP, muito acima das necessidades de um checkout. Se não vender para França, pode desativá-lo sem qualquer consequência.

Preencher a localidade a partir do código postal — quando o cliente escreve um código postal francês de 5 dígitos, a localidade preenche-se automaticamente se corresponder a uma única comuna; caso contrário, aparece um seletor por baixo do campo. O módulo nunca substitui uma localidade já escrita pelo cliente. Esta função é específica do motor BAN e, por isso, do formato francês.

Google Places (opcional)

Ativar o Google Places — ativa o motor internacional. Exige uma chave de API válida, sem a qual a gravação da configuração é recusada.

Chave de API da Google — a sua chave do Google Cloud. Ver a secção seguinte para a criar e proteger.

Países autorizados — lista de códigos ISO 3166-1 alfa-2 separados por vírgulas (por exemplo, PT,ES,FR). O Google Places só é acionado nesses países; campo vazio = todos os países. É a alavanca principal para controlar a sua faturação do Google Cloud.

Comportamento

Caracteres mínimos — número de caracteres antes de as sugestões serem acionadas (2 a 10, predefinição 3).

Debounce (ms) — intervalo entre a última tecla e a chamada à API (80 a 2000 ms, predefinição 250). Aumente-o para reduzir o número de pedidos, diminua-o para sugestões mais reativas.

Realçar as correspondências — coloca a negrito o texto escrito pelo cliente em cada sugestão.

Obter uma chave do Google Places

1. Abra a Google Cloud Console e selecione ou crie um projeto.
2. Em APIs & Services → Biblioteca, ative a Places API (New) e a Maps JavaScript API.
3. Em APIs & Services → Credenciais, crie uma chave de API.
4. Restrinja a chave: Restrições de aplicação → «Referenciadores HTTP» → acrescente o seu domínio (por exemplo, *.aminhaloja.pt/*); Restrições de API → limite à Places API (New) e à Maps JavaScript API.
5. Cole a chave na configuração do módulo e grave.

Funcionamento técnico

Alternância automática entre motores

O módulo lê o país selecionado no campo id_country do formulário. França → motor BAN. Outro país presente na lista de países autorizados → Google Places. País fora da lista ou nenhum motor aplicável → o preenchimento automático desativa-se silenciosamente e o formulário mantém-se um formulário de introdução normal. A alternância é imediata a cada mudança de país, sem recarregar a página.

Compatibilidade com checkout de página única e com novas renderizações

O checkout do PrestaShop volta a apresentar o formulário de morada a cada mudança de etapa. O módulo vigia o DOM com um MutationObserver e subscreve os eventos nativos updatedAddressForm, updatedAddress, updatedDeliveryForm e changedCheckoutStep: o preenchimento automático volta a ligar-se em cada nova renderização. Cada formulário é marcado depois da ligação, para evitar qualquer ligação em duplicado.

Formulários múltiplos

Se forem apresentados vários formulários de morada em simultâneo (entrega + faturação), cada um recebe o seu próprio preenchimento automático independente, com a sua lista de sugestões e o seu próprio estado.

Navegação por teclado e acessibilidade

A lista de sugestões é totalmente controlável pelo teclado: setas para cima e para baixo para navegar, Enter para selecionar, Esc para fechar. As sugestões têm os atributos ARIA role="listbox" e role="option".

Degradação suave

Se a API estiver inacessível (avaria, cliente sem ligação, bloqueio de rede), não é apresentado qualquer erro: o formulário mantém-se um formulário de introdução manual normal. O preenchimento automático é uma melhoria progressiva, nunca um ponto de bloqueio do checkout.

RGPD e privacidade

• Os pedidos de preenchimento automático partem diretamente do navegador do cliente para a API BAN (serviço público francês) ou para o Google Places.
• Nenhum dado passa pelo seu servidor PrestaShop durante a escrita.
• Nenhum dado passa pelos servidores da DataFirefly, nunca.
• O módulo não deposita qualquer cookie.
• Se ativar o Google Places, mencione a Google na sua política de privacidade como destinatária das moradas introduzidas nos países em causa. Numa loja portuguesa que sirva Portugal através do Google Places, isso abrange praticamente todas as moradas introduzidas no checkout.

Resolução de problemas

As sugestões não aparecem

• Verifique se o motor em causa está ativado na configuração do módulo.
• Verifique o número de caracteres mínimos: as sugestões só são acionadas a partir do limiar configurado.
• Limpe a cache do PrestaShop (Parâmetros avançados → Desempenho) para forçar o recarregamento dos recursos JS e CSS.
• Abra a consola do navegador: um erro de CORS ou um bloqueio por uma extensão (adblock, proteção de privacidade) pode impedir as chamadas à API.

O Google Places não é acionado

• Verifique se o país selecionado consta da lista de países autorizados (ou se a lista está vazia). Numa loja portuguesa, confirme que PT está mesmo lá.
• Verifique na consola do navegador se o script do Google Maps carrega sem erro: uma chave inválida, uma API não ativada ou uma restrição de referenciador demasiado estrita produzem um erro explícito Google Maps JavaScript API error.
• Verifique se a faturação está ativada no seu projeto do Google Cloud: as APIs Places recusam os pedidos sem conta de faturação ativa.

A localidade não se preenche a partir do código postal

• Esta função só diz respeito ao motor BAN (França) e desativa-se se o campo da localidade já tiver um valor escrito pelo cliente.
• Alguns códigos postais franceses cobrem várias comunas: o módulo apresenta então um seletor em vez de preencher automaticamente.
• Com códigos postais portugueses, não há preenchimento a partir do código postal isolado: a localidade chega ao selecionar uma sugestão de morada do Google Places.

Conflito com um módulo de checkout de terceiros

O módulo identifica os campos pelos seus atributos name padrão (address1, postcode, city, id_country). Os checkouts de página única de terceiros que mantenham estes nomes de campo funcionam sem configuração. Se um módulo de terceiros mudar o nome dos campos, o preenchimento automático desativa-se silenciosamente sem partir o checkout; contacte o apoio ao cliente indicando o nome do módulo em causa.

FAQ

O módulo torna a minha loja mais lenta?

Não. O JS e o CSS só são carregados nas 4 páginas que contêm um formulário de morada, e todos os pedidos de preenchimento automático são executados pelo navegador do cliente, nunca pelo seu servidor.

Posso usar apenas a API francesa, sem a Google?

Sim, é o modo predefinido, mas nesse caso só as moradas francesas beneficiam do preenchimento automático. Para servir Portugal, o Google Places é indispensável.

O módulo funciona em multiloja?

Sim. A configuração é gerida pela tabela de configuração nativa do PrestaShop e respeita o contexto multiloja padrão.

O que acontece na desinstalação?

Todas as chaves de configuração são eliminadas. Como não foi criada qualquer tabela, a desinstalação não deixa rasto.

Registo de alterações

1.1.0 — 23 de agosto de 2026

• Migração do motor da Google para a Places API (New): API programática AutocompleteSuggestion com session tokens e Place.fetchFields; o widget legacy deixou de estar disponível para os novos clientes do Google Cloud desde março de 2025
• As sugestões da Google passam a aparecer no menu do módulo: experiência unificada, navegação por teclado, realce e restrição ao país selecionado
• A França pode ser servida inteiramente pelo Google Places, desativando o motor BAN

1.0.3 — 23 de agosto de 2026

• Correção: em certos temas, um script de terceiros repunha o texto escrito no campo da rua depois da seleção de uma sugestão, deixando a morada por preencher; a rua passa a ser escrita em último lugar e o seu valor é reafirmado se for sobreposto
• Proteção contra a reabertura do menu de sugestões, baseada numa janela temporal

1.0.2 — 23 de agosto de 2026

• Correção: o menu de sugestões ficava aberto depois da seleção de uma morada, porque a pesquisa era relançada pelos eventos sintéticos emitidos ao preencher os campos

1.0.1 — 1 de julho de 2026

• Migração do motor francês para o serviço de geocodificação Géoplateforme (data.geopf.fr/geocodage, IGN), depois de o antigo endpoint api-adresse.data.gouv.fr ter sido desativado no fim de janeiro de 2026
• API isofuncional: mesmos parâmetros, mesma resposta GeoJSON, mesmo limite de 50 pedidos por segundo e por IP
• Legendas do back-office e atribuição das sugestões atualizadas

1.0.0 — 15 de maio de 2026

• Primeira versão pública
• API francesa BAN integrada por predefinição (gratuita, sem chave)
• Google Places opcional, com chave de API e lista de países autorizados
• Preenchimento código postal → localidade → rua
• Compatível com o PrestaShop 8.0 a 9.x, checkout de página única e de várias etapas
• Navegação por teclado, realce das correspondências e debounce configurável
• Sem sobreposição de templates e sem tabelas SQL