Changelog e versionamento API — Portugal
Versões da API datadas, política de descontinuação e alterações recentes — REST API para Portugal.
Arquitectura — Modelo de versionamento da API Portugal
Usamos versões da API datadas: Accept-Version: 2026-03-15. Dentro de uma versão, mudanças são apenas aditivas (novos campos, novos endpoints, novos enums atrás de flags opt-in). Breaking changes saem como nova versão datada. A conta fica pinned à versão activa no registo a menos que faças upgrade explícito. Mudanças no canal AT são versionadas separadamente e expostas no payload da factura.
Como integrar — Política de descontinuação
As descontinuações são anunciadas com ≥12 meses de antecedência por três canais: banner no dashboard, email mensal de changelog e cabeçalho Sunset nos endpoints afectados. Nunca removemos campos em silêncio. No fim de vida a versão antiga devolve 410 Gone com cabeçalho Link para o guia de migração. IVA 23% e os outros campos fiscais Portugal são estáveis em v1 e v2.
Operação e casos extremos — Alterações recentes (excerto)
2026-03-15: adicionado partial_ok em encomendas, novo evento order.partially_shipped. 2026-01-10: adicionado id de notificação AT no payload da factura. 2025-11-04: chaves de idempotência agora obrigatórias em POST /v1/orders (breaking; v2). Changelog completo em /docs/changelog com feeds RSS e Atom. Adições ao schema Portal das Finanças (AT) são não-breaking em versões pinned.
Perguntas frequentes
Como são pinned as versões?
Default da conta no registo; override por pedido via Accept-Version. Testa a nova versão com header antes de mudar o default.
Como anunciam mudanças?
Banner no dashboard, email mensal e cabeçalho Sunset nos endpoints afectados. Nunca alteramos comportamento em silêncio numa versão pinned.
Há feed RSS?
Sim — /docs/changelog.rss e feed Atom em /docs/changelog.atom.
Durante quanto tempo são suportadas versões antigas?
Mínimo 24 meses desde o sucessor; aviso de 12 meses antes do EOL.
Alterações no canal AT?
Acompanhadas no mesmo changelog. IVA 23% e outros campos fiscais são estáveis em v1 e v2.