Autocomplete de moradas no checkout WooCommerce

O cliente começa a escrever a rua, escolhe a morada numa lista e o código postal (CP7) e a localidade preenchem-se sozinhos — o código certo para a etiqueta de envio, escolhido pelo número de porta. Grátis, sem chave de API, para moradas de Portugal.

Plugin para WooCommerce

O plugin Moradas para WooCommerce está publicado no diretório oficial do wordpress.org: instale-o em Plugins › Adicionar novo, pesquisando «Moradas», e as atualizações chegam ao painel como para qualquer plugin. Em alternativa, instala-se a partir do ficheiro, abaixo. Instala-se e ativa-se como qualquer plugin, sem nada para configurar:

• Funciona no checkout em blocos (o padrão atual) e no checkout clássico.
• As sugestões só aparecem quando o país escolhido é Portugal, e todos os campos continuam editáveis.
• Se o serviço não responder, o checkout continua a funcionar como um formulário normal.
• Não acrescenta campos à encomenda e não guarda dados.

Instalar já a partir do ficheiro

1. No painel do WordPress: Plugins › Adicionar novo › Carregar plugin.
2. Escolha o ZIP descarregado › Instalar agora › Ativar.
3. Faça uma encomenda de teste com Portugal como país: ao escrever a rua aparecem as sugestões; código postal e localidade preenchem-se ao escolher.

Requisitos: WordPress 6.5 ou superior, PHP 7.4 ou superior, WooCommerce 9.9 ou superior para o checkout em blocos (em versões anteriores do WooCommerce, o plugin usa a sua própria lista de sugestões no checkout clássico).

Atualizações: o plugin está no diretório wordpress.org, por isso o WordPress avisa de novas versões no painel, como para qualquer outro plugin — também quando foi instalado a partir deste ZIP, porque a pasta do plugin é a mesma. Em alternativa, descarregue o ZIP novo e carregue-o da mesma forma — o WordPress oferece «Substituir o atual pelo carregado».

Para verificar o ficheiro descarregado: shasum -a 256 moradas-address-autocomplete-0.3.1.zip (macOS/Linux) ou certutil -hashfile moradas-address-autocomplete-0.3.1.zip SHA256 (Windows) deve dar o valor acima.

Sem plugin: o widget JS no checkout clássico

Se preferir não instalar um plugin, o widget do Moradas liga-se ao checkout clássico (o shortcode [woocommerce_checkout]) com um pequeno snippet. Cole-o no functions.php do tema filho ou num plugin de snippets:

add_action('wp_enqueue_scripts', function () {
    if (!function_exists('is_checkout') || !is_checkout()) {
        return;
    }
    wp_enqueue_script('moradas-widget', 'https://moradas.dev/widget.js', [], null, true);
    wp_add_inline_script('moradas-widget', <<<'JS'
['billing', 'shipping'].forEach(function (prefix) {
  var input = document.getElementById(prefix + '_address_1');
  if (!input) return;
  PTAddress.attach(input, {
    fill: { postal: '#' + prefix + '_postcode', city: '#' + prefix + '_city' },
    onSelect: function () {
      if (window.jQuery) jQuery(document.body).trigger('update_checkout');
    }
  });
});
JS);
});

• O widget preenche o código postal e a localidade, e a morada escolhida fica na primeira linha do endereço. Depois da escolha, o WooCommerce recalcula os portes.
• Numa rua com vários códigos postais, o CP7 exato vem com o número de porta: o cliente escreve, por exemplo, «av liberdade lisboa 196» e escolhe a sugestão.
• As sugestões são só de moradas portuguesas, por isso o snippet serve lojas que enviam para Portugal. No checkout em blocos o snippet não faz nada — aí, use o plugin.

Loja à medida ou outra plataforma

O mesmo widget funciona em qualquer formulário onde possa incluir um script, e a API REST serve integrações no servidor. Exemplos prontos a copiar em curl, JavaScript, PHP, Python e C# no início rápido da API.

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. Pode remeter para a página de privacidade na política da sua loja.