Estado e alterações
O que está a funcionar agora, quando os dados mudam, o que mudou na API, no widget e no plugin, e com o que pode contar da nossa parte.
Estado
A verificação é feita pelo seu browser com um pedido a GET /health, o mesmo endpoint que qualquer integração pode usar. «Operacional» significa que a API respondeu com ok: true; «Indisponível», que não respondeu ou respondeu com erro. Se a sua própria ligação falhar, também verá «Indisponível». A hora é a do seu dispositivo.
Dados
Os dados de moradas e códigos postais são atualizados semanalmente. Cada atualização passa por uma verificação automática antes de entrar em produção; se a verificação falhar, a atualização não é aplicada e o serviço continua com os dados anteriores.
Depois de uma atualização, os valores de art_id mudam — use-os logo a seguir ao /suggest e nunca os guarde — e as respostas de /cp guardadas na cache da rede podem demorar até um dia a refletir os dados novos.
Uma morada não apareceu? Envie-a por POST /feedback (ver documentação) ou para dev@moradas.dev.
Alterações
Registo das alterações visíveis para quem integra: API, widget, plugin e documentação. As mais recentes primeiro.
15.11.2026
- Pesquisa — mais moradas completas que antes ficavam sem sugestões passam a ser encontradas. A descrição do prédio ou da fração escrita fora do sítio habitual («Lote 3», «Bloco B», «Edifício …», «Moradia», «R/C» sem número de porta antes) é ignorada, e os tipos de via abreviados como «Tv.» e «Lg.» são lidos como Travessa e Largo. Quando o tipo de via escrito não coincide com o oficial («Avenida» ou «Urbanização» em vez de «Rua»), a pesquisa procura o nome sem o tipo, e a sugestão traz
corrected: true; em/batchuma linha encontrada só com outro tipo de via ficaambiguous, nuncaok. As respostas que já tinham sugestões não mudam. OpenAPI 1.2.3 atualiza a descrição decorrected.
02.11.2026
- Widget 0.3.1, plugin WooCommerce 0.3.1 e módulo PrestaShop 0.2.2 — os pedidos a
/suggeste/resolvelevam o parâmetrofromcom o nome e a versão do plugin (por exemplowp-woo/0.3.1), para sabermos em quantos sites cada plugin está em uso; guardamos só o nome, sem dados pessoais (privacidade). As respostas da API não mudam. - Documentação — as tabelas da documentação deslizam na horizontal em ecrãs pequenos, sem alargar a página.
22.10.2026
- Pesquisa — quando a rua não é reconhecida mas a linha traz uma zona postal (os quatro primeiros dígitos, por exemplo «4700 Braga»), a pesquisa tenta primeiro a rua dentro dessa zona; se não existir, devolve as localidades da zona, assinaladas com
by_cp4: trueecp4. OpenAPI 1.2.2 descreve os campos. - Diretório wordpress.org — página do plugin reescrita: etiquetas, descrição, perguntas frequentes e cinco capturas de ecrã novas; a versão continua a 0.3.0.
21.10.2026
- Plugin WooCommerce 0.2.1 no wordpress.org — aprovado e publicado no diretório oficial: wordpress.org/plugins/moradas-address-autocomplete. Instala-se em Plugins › Adicionar novo, pesquisando «Moradas»; as atualizações passam a chegar pelo painel. O ZIP neste site continua disponível.
- Plugin WooCommerce 0.3.0 — traz o widget 0.3.0 (campos de checkout em React/Vue, o código postal não é apagado ao continuar a escrever, aviso quando o serviço não responde); publicado no wordpress.org, as lojas recebem a atualização pelo painel. ZIP com SHA-256 também neste site.
- Documentação — secção «Integrar sem o widget»: três receitas curtas em JavaScript para quem escreve o próprio código (código postal → campos, rua → sugestões, número de porta → código exato), tabela dos campos de
/cp, o significado dekind: "loc"e como ligar o widget quando o código postal e a rua são campos separados. - Transparência — quando alguém pede um código postal que não existe nos nossos dados, passamos a contar esse código (sem IP nem origem) para detetar falhas de cobertura; a página de privacidade foi atualizada.
- Pesquisa — quando o texto da rua não é reconhecido mas a linha contém um código postal válido, as sugestões vêm desse código, agora assinaladas com
by_cp7: truee com o número de porta aplicado (resolved_cp7). OpenAPI 1.2.1 descreve o campo.
06.10.2026
- Módulo PrestaShop 0.2.1 — intervalo de versões declarado explicitamente (PrestaShop 1.7.1 a 9, segundo a documentação oficial); o ZIP 0.2.0 foi substituído, SHA-256 novo na página do guia.
- Site — página para agências e freelancers que fazem lojas para clientes em Portugal.
- MCP 0.2.0 — nova ferramenta
verify_addresses: um agente de IA verifica uma lista de moradas numa só chamada (os mesmos resultados dePOST /batch).
05.10.2026
- Pesquisa — o nome completo de uma localidade grande («Fátima», «Monte Estoril», «Queluz de Baixo») devolve o próprio lugar primeiro, como já acontecia com os concelhos; o início do nome («carcav») faz o mesmo desde 02.10.
- Plugins — o plugin WooCommerce 0.2.1 e o módulo PrestaShop 0.2.0 podem ser descarregados diretamente do site (ZIP com SHA-256), sem esperar pelos diretórios; até lá, as atualizações são manuais.
- Site — guia para áreas de cliente, CRM e back-office (validação de registos e de bases de dados existentes).
02.10.2026
- Pesquisa — corrige gralhas quando não há resultado («rua agusta lisboa» → Rua Augusta, Lisboa); a sugestão traz
corrected: trueemdata. - Pesquisa — o início do nome de um concelho ou de uma localidade grande («Lisb», «Carcav») devolve o próprio lugar primeiro, os maiores à frente.
- Site — esta página de estado e alterações; guias de integração para Shopify, PrestaShop, Magento, Wix, Jumpseller e Shopkit.
- OpenAPI 1.1.1 — campo
correcteddescrito;llms.txte a ferramenta MCPsuggest_addressatualizados. - API —
POST /batch: até 100 moradas num só pedido, para programas com listas (importação de encomendas, CRM); cada linha devolveokcom o CP7,ambiguousounot_founde a primeira sugestão como no/suggest. Um pedido com N moradas conta como N pedidos no limite. OpenAPI 1.2.0 com os esquemas;llms.txte documentação atualizados.
30.09.2026
- API —
GET /cp/{cp4}: com só os quatro primeiros dígitos, devolve todos os códigos postais dessa zona, cada um com localidade, concelho e distrito (antes respondia 404). - API — os 404 em
/cp/…,/v1/…e/api/…trazem o cabeçalhoX-Moradas-Hintcom o motivo, legível a partir do browser. Os corpos das respostas não mudaram. - Pesquisa — ao escrever só o nome de uma localidade ou concelho («Lisboa»), a primeira sugestão é a própria localidade (
kind: "loc",art_id: 0,cp7: null), antes das ruas. - Widget 0.3.0 — relatório mínimo de erros quando o serviço não responde (sem morada nem texto escrito);
beacon: falsedesliga-o.widget.jspassa a ser servido comcharset=utf-8e CORS aberto. - OpenAPI 1.1.0 —
/cp/{cp4},/widget-errore exemplos com respostas reais;llms.txtatualizado. - Plugin WooCommerce 0.2.1 — textos em inglês com tradução pt-PT incluída, aviso quando o WooCommerce não está ativo, relatório de erros do widget desligado. Entregue para revisão no diretório wordpress.org; publicação em breve.
- Privacidade — página atualizada (PT e EN): relatórios de erro do widget e contagens de pesquisas sem resultado.
28.09.2026
- Widget 0.2.0 — funciona com React e Vue (os campos são preenchidos com eventos
inputechange); não apaga um CP7 já escrito; o número de porta escrito depois da escolha preenche o CP7 exato; Tab e a saída do campo contam como escolha; a lista avisa quando o serviço não responde. - Pesquisa — entende a escrita real das moradas: «nº 196» e «n.º», andar e lado, um CP7 dentro do texto, «, Portugal» no fim; o nome de um concelho encontra as ruas desse concelho.
- Site — pedidos
HEADàs páginas respondem 200 (alguns diretórios consideravam as ligações mortas). - Docs — tabela de opções do widget e secção React/Vue.
25.09.2026
- API — as respostas 429 trazem o cabeçalho
Retry-After. - Docs — «Começar em 2 minutos»: exemplos prontos a copiar em curl, JavaScript, PHP, Python e C#, verificados contra o serviço.
- Guias — Validar código postal, Autocomplete no WooCommerce, Alternativa ao Google Places.
- Pesquisa — correspondência de ruas mais precisa, medida numa bateria de moradas reais; o formato das respostas não mudou.
24.09.2026
- OpenAPI 1.0.0 —
openapi.json(OpenAPI 3.1) ellms.txt; dados estruturados (JSON-LD) na página inicial. - API —
/cppassa a ter um limite próprio, mais folgado, separado do limite geral. - API —
countem/suggestaceita 1 a 20 (um valor negativo deixou de ser lido como «sem limite»). - Docs — texto em português presente no HTML (legível sem JavaScript);
lang="pt"por defeito.
21.09.2026
- API — respostas de
/cp,/suggeste/resolveservidas a partir da cache da rede:/cpaté 24 horas,/suggeste/resolveaté 1 hora, 404 durante 10 minutos./health,/mcpe/feedbacknunca ficam em cache;Cache-Control: no-cacheno pedido força a resposta ao vivo.
31.08.2026
- Pesquisa — tolerância a grafias antigas e variantes (Baptista/Batista, ph, th, y…), intervalos e paridade dos números de porta, número de porta em qualquer posição do texto.
- Plugin WooCommerce 0.2.0 — Checkout Blocks e checkout clássico através da API oficial de autocomplete de moradas do WooCommerce (9.9 ou superior).
- Site — página Privacidade; compromisso de contrato estável v1 na documentação.
29.08.2026
- MCP — servidor MCP remoto em
POST /mcp(ferramentassuggest_address,resolve_postal_code,postal_code_info). - Widget —
widget.jsservido a partir de moradas.dev. - Site — bloco de integração para agentes de IA e FAQ na página inicial; guia Alternativa ao GeoAPI.pt.
28.08.2026 lançamento
- moradas.dev —
GET /suggest,GET /resolve,GET /cp/{cp7},POST /feedback,GET /health; página inicial com demo; documentação em português e inglês; widget 0.1.0.
Compromissos
- Contrato estável (v1). Os campos nunca são renomeados nem removidos, apenas acrescentados; as respostas 200 de
/cp/{cp7}não mudam. Alterações incompatíveis só sairiam como/v2separado e ficariam registadas nesta página. - Limites. Cerca de 50 pedidos por 10 segundos por IP;
/cptem um limite próprio, mais folgado. Respostas servidas da cache da rede não contam. Acima do limite, a resposta é 429 com o cabeçalhoRetry-After: espere esses segundos (ou cerca de 10, se o cabeçalho faltar) e repita; num campo de autocomplete não repita — a tecla seguinte faz um pedido novo. Em rajadas muito concentradas, a proteção da rede contra inundações pode responder antes do serviço. - Sem SLA. O Moradas é gratuito e está em beta: fazemos o melhor para o manter disponível — a disponibilidade é verificada periodicamente a partir do exterior e qualquer falha avisa-nos — mas não há garantia de disponibilidade nem compensações. Guarde em cache o que precisar e trate 429 e 5xx no seu código; os exemplos da documentação já o fazem.
- Dados. Atualização semanal com verificação automática antes de entrar em produção;
art_idé efémero. - Grátis, sem chave. Incluindo uso comercial; sem registo; CORS aberto.
- Privacidade. Sem cookies, sem dados pessoais — só contagens agregadas. Detalhes em Privacidade.
Contacto
Dúvidas, avarias ou uma morada em falta: dev@moradas.dev. Numa falha do serviço, indique a hora, o pedido feito (sem dados pessoais) e a resposta recebida — ajuda a encontrar a causa mais depressa.
https://moradas.dev. Documentação: /docs.