Changelog

Esta página registra as alterações relevantes da API de emissão de notas do FazNota e desta documentação. Mudanças seguem o padrão SemVer: alterações breaking incrementam o major (v3 → v4) e recebem comunicação prévia.

2026-05-13 — Modernização de DX (v3 mantida)

Esta release mantém compatibilidade total com o contrato existente. Nada quebra. Novas capacidades são puramente aditivas.

Adicionado

• Header X-Request-Id em todas as respostas. Idêntico ao novo campo meta.request_id no body. Cite ao acionar o suporte.
• Headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset em respostas autenticadas. Permitem auto-regulação do consumo.
• Bloco meta em todas as respostas com request_id e timestamp (ISO-8601 UTC).
• Endpoint GET /health sem autenticação. Retorna 200 OK quando aplicação + banco saudáveis; 503 quando degradado.
• Paginação por query string (?page=&page_size=) em todas as listagens, como alternativa ao path-based legado. Veja Paginação.
• Campo numero-origem (com hífen) aceito em emissões, equivalente ao legado numero_origem (com underscore). Os dois formatos funcionam.
• Header Access-Control-Expose-Headers expõe X-Request-Id e os X-RateLimit-* para clientes browser conseguirem lê-los.

Melhorado

• Mensagens de erro internas mais seguras: stack traces e detalhes de infraestrutura não vazam mais ao cliente. Mensagens de validação (em português, começando com "Campo <recurso>@<campo>...") permanecem idênticas.
• Logs estruturados (interno) via SLF4J + Logback. Cada log contém requestId= para correlação. Sem impacto no cliente.
• Health check de DB real em GET /health (não apenas ping de aplicação).
• OPTIONS preflight respondido imediatamente sem exigir autenticação, melhorando integrações browser.

Corrigido (interno)

• Bug histórico que impedia gravação no log de uso da API (tb_uso_api). Logs passam a ser gravados corretamente.
• Vulnerabilidade SQL injection no provider de log (uso de PreparedStatement).
• Duplicação de headers CORS nos resources (centralizado no filter).

Documentação

• Nova documentação completa com a estrutura de 12 seções (esta versão).
• Spec OpenAPI 3.0.3 publicada em openapi/nota-fiscal.yaml.
• 7 recipes práticos cobrindo os principais fluxos.
• Coleção Postman/Insomnia oficial.

Versões anteriores

A documentação consolidada começou nesta versão. Mudanças anteriores estão registradas no Painel FazNota e em comunicados por e-mail aos integradores.

Política de breaking changes

A v3 está congelada em contrato — nenhuma mudança quebrante será introduzida sem:

1. Comunicação prévia com prazo adequado (mínimo 90 dias).
2. Janela de retrocompatibilidade com versão antiga funcionando em paralelo.
3. Documentação clara do que mudou e como migrar.

Veja Políticas operacionais para o regramento completo.

Como acompanhar

• 📧 E-mail: os contatos cadastrados no Painel FazNota recebem comunicados.
• 🌐 Painel: avisos importantes aparecem ao logar.
• 📄 Esta página: consulte periodicamente.