Pular para o conteúdo
API de emissão de notas do FazNota

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-08-06 — Resumo diário e download de XMLs por período

Mudança puramente aditiva: dois recursos novos, nenhum endpoint existente foi alterado.

Adicionado

  • GET /resumo?data-inicial=&data-final= — totais por dia de NFe e NFCe emitidas, canceladas e denegadas, mais as falhas de emissão. Reflete tudo que a empresa emitiu, inclusive pela tela do ERP. Período máximo de 92 dias. Atenção: canceladas é subconjunto de emitidas — não some os dois campos. Veja Resumo diário de emissões.
  • POST /xml/solicitacao e GET /xml/solicitacao/{protocolo} — download em lote dos XMLs de um período, em fluxo assíncrono (solicita → consulta protocolo → baixa do link temporário, válido por 7 dias). Período máximo de 92 dias, até 3 solicitações simultâneas por empresa. O arquivo também é enviado por e-mail. Veja Baixar XMLs por período.
  • Status novos no envelope: 006 (processado sem resultado), 007 (falha no processamento assíncrono) e 400 (parâmetro inválido — erro do chamador, repetir a requisição não resolve).

2026-08-04 — NFSe: informações complementares e ISS retido

Mudança puramente aditiva. Requisições que não enviem os novos campos continuam se comportando exatamente como antes.

Adicionado

  • Campo informacoes-complementares (NFSe, opcional, até 2.000 caracteres) em POST /nfse/emissao e PUT /nfse/{id}. Texto livre que sai na seção “Informações Complementares” do DANFSe/XML. É uma seção diferente da discriminação do serviço (observacao) — os dois convivem na mesma nota. Omitido: nota emitida sem informações complementares (comportamento anterior).
  • Campo iss-retido (NFSe, opcional) em POST /nfse/emissao e PUT /nfse/{id}. "1" = ISS retido pelo tomador (substituição tributária), "2" = não retido. Padrão "2" quando omitido (comportamento anterior). É informação da nota, não do item; mesmo com ISS retido a alíquota e o valor do ISS continuam no XML. Valor diferente de "1"/"2" é rejeitado com mensagem de validação.

Veja Emitir uma NFSe.

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.