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 verificar…

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.

widget 0.3.0OpenAPI 1.2.0plugin WooCommerce 0.2.1

02.10.2026

Pesquisa — corrige gralhas quando não há resultado («rua agusta lisboa» → Rua Augusta, Lisboa); a sugestão traz corrected: true em data.
Pesquisa — o início do nome de um concelho («Lisb») devolve o próprio concelho 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 corrected descrito; llms.txt e a ferramenta MCP suggest_address atualizados.
API — POST /batch: até 100 moradas num só pedido, para programas com listas (importação de encomendas, CRM); cada linha devolve ok com o CP7, ambiguous ou not_found e 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.txt e 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çalho X-Moradas-Hint com 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: false desliga-o. widget.js passa a ser servido com charset=utf-8 e CORS aberto.
OpenAPI 1.1.0 — /cp/{cp4}, /widget-error e exemplos com respostas reais; llms.txt atualizado.
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 input e change); 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) e llms.txt; dados estruturados (JSON-LD) na página inicial.
API — /cp passa a ter um limite próprio, mais folgado, separado do limite geral.
API — count em /suggest aceita 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, /suggest e /resolve servidas a partir da cache da rede: /cp até 24 horas, /suggest e /resolve até 1 hora, 404 durante 10 minutos. /health, /mcp e /feedback nunca ficam em cache; Cache-Control: no-cache no 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 (ferramentas suggest_address, resolve_postal_code, postal_code_info).
Widget — widget.js servido 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 /v2 separado e ficariam registadas nesta página.
Limites. Cerca de 50 pedidos por 10 segundos por IP; /cp tem um limite próprio, mais folgado. Respostas servidas da cache da rede não contam. Acima do limite, a resposta é 429 com o cabeçalho Retry-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.

Beta. URL base: https://moradas.dev. Documentação: /docs.