Autocomplete de moradas no PrestaShop

O formulário de morada do PrestaShop — no checkout e na área de cliente — tem nomes de campos estáveis (address1, postcode, city), e os módulos podem carregar scripts externos. Um módulo de dois ficheiros liga o widget; não há módulo Moradas publicado, por isso o código completo está nesta página.

Funciona no checkout: Sim — com um módulo pequeno

No PrestaShop 1.7 e 8, um módulo regista o script no hook actionFrontControllerSetMedia com registerJavascript e a opção server: remote. O formulário de morada usa os campos address1, postcode e city, no checkout e na área de cliente. Quando o cliente muda de país, o tema clássico recarrega o formulário por AJAX e o núcleo emite updatedAddressForm; o módulo volta a ligar o widget.

Para que serve o widget no PrestaShop: morada no checkout e moradas na área de cliente (tema clássico) — o mesmo módulo cobre ambos.

Não testado numa loja real: o módulo abaixo segue a documentação do PrestaShop 8 e o tema clássico (2 de outubro de 2026). Não existe módulo Moradas no PrestaShop Addons.

O módulo: dois ficheiros

Crie a pasta modules/moradasautocomplete/ com o ficheiro principal do mesmo nome e um ficheiro JavaScript em views/js/. O nome do módulo só pode ter letras minúsculas e dígitos.

<?php
// modules/moradasautocomplete/moradasautocomplete.php
if (!defined('_PS_VERSION_')) {
    exit;
}

class MoradasAutocomplete extends Module
{
    public function __construct()
    {
        $this->name = 'moradasautocomplete';
        $this->tab = 'front_office_features';
        $this->version = '1.0.0';
        $this->author = 'A sua loja';
        $this->need_instance = 0;
        $this->ps_versions_compliancy = ['min' => '1.7.0.0', 'max' => _PS_VERSION_];
        $this->bootstrap = true;
        parent::__construct();
        $this->displayName = $this->l('Moradas - autocomplete de moradas PT');
        $this->description = $this->l('Sugestoes de morada e CP7 exato no formulario de morada.');
    }

    public function install()
    {
        return parent::install() && $this->registerHook('actionFrontControllerSetMedia');
    }

    public function hookActionFrontControllerSetMedia()
    {
        // checkout (order) and the customer's address book (address)
        if (!in_array(Tools::getValue('controller'), ['order', 'address'], true)) {
            return;
        }
        $this->context->controller->registerJavascript(
            'moradas-widget',
            'https://moradas.dev/widget.js',
            ['server' => 'remote', 'position' => 'bottom', 'priority' => 150]
        );
        $this->context->controller->registerJavascript(
            'moradas-init',
            'modules/' . $this->name . '/views/js/moradas.js',
            ['position' => 'bottom', 'priority' => 151]
        );
    }
}

O ficheiro JavaScript liga o widget a cada campo address1 e preenche o código postal e a cidade do mesmo formulário; quando o país muda, destrói as ligações antigas e volta a ligar:

// modules/moradasautocomplete/views/js/moradas.js
(function () {
  var widgets = [];
  function init() {
    if (!window.PTAddress) return;
    widgets.forEach(function (w) { w.destroy(); });
    widgets = [];
    document.querySelectorAll('input[name="address1"]').forEach(function (input) {
      var form = input.closest('form') || document;
      widgets.push(PTAddress.attach(input, {
        fill: {
          postal: form.querySelector('input[name="postcode"]'),
          city: form.querySelector('input[name="city"]')
        }
      }));
    });
  }
  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', init); else init();
  // the theme reloads the address form when the country changes
  if (window.prestashop && typeof prestashop.on === 'function') prestashop.on('updatedAddressForm', init);
})();

Instalar e testar

  1. Comprima a pasta moradasautocomplete num zip (com a pasta dentro do zip) e carregue-o em Módulos › Gestor de módulos › Carregar um módulo; ou copie a pasta para /modules/ e instale a partir da lista de módulos.
  2. Faça uma encomenda de teste com Portugal como país: ao escrever a rua aparecem as sugestões; código postal e cidade preenchem-se ao escolher. Mude o país e volte a Portugal — o widget volta a ligar-se.

O que o widget faz

O widget.js carrega-se com uma linha e liga-se ao campo da morada com PTAddress.attach. Enquanto o cliente escreve aparecem sugestões de ruas e localidades portuguesas; ao escolher, os campos indicados em fill recebem o código postal, a localidade, o concelho e o distrito. Numa rua com vários códigos postais, o CP7 exato chega com o número de porta. Se o serviço não responder, o formulário continua a funcionar como antes. Todas as opções — endpoint, fill, onSelect, onResolve, lang, beacon — estão na documentação do widget.

Porque é que o CP7 exato importa

Em Portugal uma rua pode ter vários códigos postais, por troços e pela paridade dos números. Na Avenida da Liberdade, em Lisboa, o n.º 196 tem o código 1250-147, e os números ímpares de 1 a 57 têm o 1250-139. Uma gralha no código postal pode mandar a encomenda para a morada errada.

E os dados dos clientes?

O Moradas não usa cookies e não guarda o texto pesquisado — só contagens agregadas de utilização e, se o beacon ficar ligado, um relatório mínimo quando o serviço falha. Pode remeter para a página de privacidade na política da sua loja.

Fontes (verificadas a 2 de outubro de 2026)

Experimentar a demoDocumentação do widget