Autocomplete de moradas no Shopkit
O Shopkit deixa o lojista acrescentar JavaScript à loja em Aparência › Avançado, e os temas oficiais usam ids fixos nos campos de morada do checkout. O widget liga-se sem app e sem tocar no tema.
Funciona no checkout: Sim
Nos temas oficiais do Shopkit (default, mosaic, minimal, boxie) o formulário de dados da encomenda tem os campos delivery_address, delivery_zip_code e delivery_city (e billing_address, billing_zip_code, billing_city para a faturação). O JavaScript personalizado corre no fim de todas as páginas, depois de os campos existirem.
Para que serve o widget no Shopkit: morada de envio e de faturação no checkout; também a página de contacto ou outros formulários do tema.
Não testado numa loja real: baseado na documentação e nos temas públicos do Shopkit (2 de outubro de 2026).
Passos
- No painel da loja, abra Aparência › Avançado. Na secção HTML › Head, cole
<script src="https://moradas.dev/widget.js"></script>. - Na secção JavaScript, cole o código abaixo — sem tags
<script>, porque o Shopkit já o coloca dentro de um script no fim da página. - Guarde e faça uma encomenda de teste: ao escrever a rua no campo da morada aparecem as sugestões; o código postal e a localidade preenchem-se ao escolher.
(function () {
function attach(prefix) {
var input = document.getElementById(prefix + '_address');
if (!input) return;
PTAddress.attach(input, {
fill: { postal: '#' + prefix + '_zip_code', city: '#' + prefix + '_city' }
});
}
function init() {
if (!window.PTAddress) return;
attach('delivery');
attach('billing');
}
if (window.PTAddress) init(); else window.addEventListener('load', init);
})();
- Os campos de faturação estão sempre na página, mas ficam escondidos enquanto «faturação igual à entrega» estiver ligado; o código ignora os que não encontrar.
- Os campos do tema trazem o atributo
data-places, que sugere um autocomplete do Google integrado na plataforma. Se na sua loja já aparecer uma lista do Google ao escrever a morada, fique com um dos dois para o cliente não ver duas listas. - Num tema à medida, confirme os ids dos campos no HTML da página de dados (botão direito › Inspecionar) e ajuste o código.
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.