Quando eu li a NT-008 versão 1.01, publicada em 30/06/2026, a primeira coisa que pensei foi simples: quem gera NFS-e Nacional no próprio sistema não pode tratar o PDF como um detalhe visual. O novo DANFSe passou a exigir consistência de layout, origem correta dos dados no XML, regras de exibição e cuidado real com QR Code, chave, tributos e supressão de blocos. Se o seu produto é um ERP, uma software house ou uma plataforma fiscal, isso afeta diretamente a sua camada de apresentação.
O DANFSe atualizado não é só um arquivo bonito, mas uma representação padronizada e verificável da NFS-e Nacional.
Eu também vi muita confusão entre emissão da nota, armazenamento do XML autorizado e geração do documento auxiliar em PDF. Na prática, são etapas próximas, mas diferentes. E foi justamente por isso que decidi organizar este guia de forma técnica e direta, pensando em quem precisa transformar XML válido em HTML e depois em PDF sem ruído, sem improviso e sem divergência visual.
Segundo a publicação da Nota Técnica nº 008/2026 com regras para emissão do DANFSe, o objetivo do documento é dar consulta rápida às informações da nota e atender às exigências legais de documentação em papel com maior uniformidade nacional. Já a prorrogação do prazo para adequação ao novo leiaute do DANFSe confirmou dois marcos que eu considero obrigatórios no planejamento técnico: a API anterior de geração foi descontinuada em 15/07/2026 e a geração atualizada entrou em produção em 03/08/2026. No dia da publicação deste artigo, vale conferir o portal oficial para validar se houve novo ajuste operacional.
O que mudou com a NT-008 na prática
A NT-008 versão 1.01 não mudou só o desenho do documento. Ela definiu um padrão mais rígido para o documento auxiliar da NFS-e Nacional. Isso afeta o mapeamento de campos, a renderização e os testes do seu motor de geração. Eu costumo dividir as mudanças em cinco frentes.
- Padronização visual do layout nacional.
- Definição mais clara de blocos obrigatórios e opcionais.
- Inclusão de informações ligadas a IBS e CBS quando presentes no XML.
- Regras para chave de acesso e QR Code.
- Diretrizes de tipografia, margens e supressão de áreas vazias.
A maior mudança foi a passagem de um PDF “adaptado pelo fornecedor” para um documento auxiliar com expectativa real de uniformidade nacional.
Na minha experiência, isso muda o trabalho do time de produto e também do time de back-end. Antes, muita empresa tratava o DANFSe quase como um relatório. Agora, ele precisa seguir um contrato visual e semântico. Se o XML diz uma coisa e o PDF mostra outra, o problema não é de estilo. É de conformidade.
PDF fiscal não é relatório livre.
De onde cada dado deve sair
Se eu tivesse que apontar o erro mais comum em projetos de DANFSe v2.0, seria este: buscar dados de múltiplas fontes paralelas, como banco interno, cache e parâmetros de tela, em vez de tomar o XML autorizado como base principal. Para reduzir divergência, eu recomendo que o documento seja gerado sempre a partir do XML da NFS-e Nacional já validado no fluxo oficial.
O XML autorizado deve ser a fonte de verdade para a montagem do DANFSe.
Esse cuidado evita diferenças entre o que foi transmitido, o que foi autorizado e o que o cliente vê no PDF. Em implementações mais maduras, eu gosto de usar um parser que lê o XML e transforma tudo em um modelo tipado de domínio. Só depois disso eu entrego os dados ao template HTML.
Os grupos de dados que normalmente entram no documento são estes:
- Identificação da NFS-e, incluindo número, série, data e ambiente.
- Prestador, tomador e, quando houver, intermediador.
- Discriminação do serviço.
- Valores da operação, retenções e total líquido.
- Tributos ligados ao modelo nacional, incluindo IBS e CBS quando enviados.
- Chave de acesso, link de consulta e QR Code.
Quando trabalho em revisão de layout fiscal, eu insisto numa regra simples: nenhum campo exibido no PDF deve existir sem rastreabilidade clara até um nó do XML ou uma regra explícita da NT. Isso reduz retrabalho e ajuda muito na auditoria.
Se você quiser reforçar essa base de integração antes de tratar o PDF, vale acompanhar conteúdos sobre APIs fiscais e integrações e também um material mais amplo sobre NFS-e, emissão e integração via API, porque isso ajuda a organizar o pipeline desde a autorização até a visualização.
Blocos obrigatórios e blocos que podem ser suprimidos
Uma dúvida que apareceu bastante nas minhas leituras foi sobre o que sempre precisa aparecer e o que pode ser omitido quando não houver conteúdo. Aqui a resposta passa por duas camadas: a regra da NT-008 e a presença efetiva da informação no XML.
Bloco opcional não é bloco livre. Ele só pode sumir quando a ausência de dado permitir essa supressão.
Na prática, eu separo assim:
- Blocos sempre presentes, como identificação do documento, dados centrais da nota e mecanismo de validação visual.
- Blocos condicionais, como intermediador, informações complementares, retenções específicas e tributos que só aparecem se informados.
- Blocos que podem ser compactados ou suprimidos para evitar espaços mortos, desde que a leitura permaneça íntegra.
Isso tem um efeito direto no HTML. Se o seu template estiver cheio de contêineres vazios, o PDF final vai parecer quebrado. Eu já vi documento com margem estourada só porque um bloco opcional ficou reservado por CSS mesmo sem conteúdo. O certo é condicionar a renderização do trecho inteiro, e não só esconder o texto.
Em times que usam Notaas para automatizar emissão e retorno em tempo real, esse ponto costuma ficar mais simples quando o payload de visualização já nasce estruturado a partir do XML processado. A vantagem é reduzir a lógica espalhada entre back-end e front-end.
IBS e CBS no documento auxiliar
A chegada de campos ligados a IBS e CBS exige atenção extra. Muita gente pensa apenas no cálculo, mas a exibição também precisa seguir ordem, rotulagem e contexto corretos. Quando esses dados existirem no XML, o DANFSe deve refletir a operação com clareza.
IBS e CBS não devem ser “encaixados” em campos antigos de tributos; eles precisam respeitar a estrutura nova prevista para a NFS-e Nacional.
Na minha leitura, há três cuidados que evitam erro:
- Separar a camada de cálculo da camada de apresentação.
- Preservar nomes e agrupamentos fiscais de acordo com o leiaute.
- Exibir somente o que estiver no XML autorizado e no contexto da operação.
Esse tema fica ainda mais sensível quando o seu sistema gera versões em tela e em PDF. Se a tela usa um agrupamento e o PDF usa outro, o usuário interpreta como divergência fiscal. Não deveria acontecer. Eu prefiro um modelo tipado único para abastecer os dois canais.
Chave de acesso, QR Code e validação visual
Em documento fiscal, o trecho de validação visual é um dos mais sensíveis. A chave de acesso e o QR Code não estão ali por estética. Eles apoiam consulta, conferência e uso prático do DANFSe em circulação digital ou impressa.
Se a chave ou o QR Code estiverem errados, o problema deixa de ser visual e passa a ser funcional.
Eu recomendo tratar esses dois elementos como artefatos gerados a partir dos dados finais, nunca como textos montados manualmente na view. O fluxo que costumo aplicar é:
- Validar a presença e o formato da chave no modelo tipado.
- Montar a URL ou payload de consulta conforme a regra vigente.
- Gerar o QR Code em resolução suficiente para tela e impressão.
- Testar leitura por diferentes dispositivos e em PDFs comprimidos.
Esse ponto parece simples até o dia em que um PDF sai com reamostragem agressiva de imagem. Já passei por isso. O QR Code ficou bonito, mas não lia. Desde então, eu sempre incluo teste de leitura real no checklist visual.
Tipografia, margens e consistência entre HTML e PDF
Se eu pudesse dar um conselho curto para quem vai implementar o DANFSe v2.0, seria este: não deixe a camada de impressão para o fim. É nela que surgem problemas de quebra de página, corte de texto, blocos desalinhados e fontes renderizadas de forma diferente.
Um DANFSe correto em HTML pode sair incorreto no PDF se a estratégia de renderização não for controlada.
Eu trabalho com algumas regras práticas:
- Escolher uma família tipográfica estável no motor de PDF adotado.
- Fixar tamanhos mínimos para legibilidade de campos fiscais.
- Definir margens consistentes para A4, pensando em impressão real.
- Evitar dependência de recursos externos de fonte em tempo de renderização.
- Controlar quebra de bloco para não separar título e conteúdo.
Também gosto de limitar variações de CSS. Quanto mais “criativo” o template, maior a chance de o PDF sair diferente entre ambientes. Em contexto fiscal, previsibilidade vale mais que liberdade visual. Curto e direto.
Se a sua equipe ainda está amadurecendo a parte de endpoints e retorno de documentos, eu sugiro revisar um guia prático de endpoint API com foco em integração e segurança. Isso ajuda a desenhar melhor a entrega do HTML renderizado, do binário PDF ou do link assinado.
Pipeline recomendado para geração
Ao longo dos anos, eu vi muito projeto misturar leitura de XML, regra fiscal e HTML na mesma função. Funciona por pouco tempo. Depois vira um ponto frágil. Para o novo leiaute, eu recomendo um pipeline com separação clara de etapas.
O fluxo mais estável para gerar o DANFSe é XML → parser → modelo tipado → HTML → PDF.
Na prática, esse pipeline fica assim:
- Receber o XML autorizado da NFS-e Nacional.
- Fazer parsing com validação estrutural e tratamento de namespaces.
- Popular um modelo tipado com campos normalizados.
- Aplicar regras de presença, formatação e supressão de blocos.
- Renderizar o HTML com template previsível.
- Converter para PDF em ambiente controlado.
- Executar testes visuais e funcionais antes de publicar.
Eu gosto desse desenho porque ele separa responsabilidades. O parser não decide CSS. O template não adivinha regra tributária. O gerador de PDF não corrige inconsistência de dados. Cada parte faz só o que deve.
Para quem trabalha com automação fiscal em escala, conteúdos sobre automação de processos ajudam a pensar em fila assíncrona, reprocessamento e rastreabilidade. Isso conversa bem com a proposta da Notaas, que já nasce voltada para emissão automatizada via API e retorno em tempo real.
Checklist visual antes de subir para produção
Antes de publicar qualquer implementação, eu sempre faço uma revisão visual guiada. Não é exagero. É o tipo de cuidado que evita chamado de cliente por erro que passou ileso nos testes de unidade.
Checklist visual não substitui teste automatizado, mas captura falhas que o parser e a tipagem não enxergam.
Meu checklist costuma incluir:
- Logo, título do documento e identificação da nota no lugar previsto.
- Datas e valores com formatação correta.
- Discriminação do serviço sem corte indevido.
- Blocos condicionais exibidos apenas quando houver dados.
- IBS e CBS posicionados conforme o modelo atual.
- Chave visível e QR Code legível.
- Margens preservadas em impressão A4.
- Ausência de páginas extras em branco.
Eu também comparo HTML e PDF lado a lado. Se houver diferença de quebra, alinhamento ou ocultação de campo, o problema precisa ser corrigido antes da entrega. Esse cuidado pesa muito em plataformas que distribuem DANFSe em grande volume.
Testes com XMLs reais anonimizados
Se existe uma prática que eu nunca abro mão, é testar com XMLs reais anonimizados. XML sintético ajuda, mas não mostra toda a variedade de casos. No mundo real, aparecem descrições longas, tomadores estrangeiros, retenções específicas, campos ausentes e combinações tributárias pouco frequentes.
XML real anonimidado expõe casos de borda que quase nunca aparecem em massa de teste montada à mão.
Eu costumo montar uma suíte com grupos como estes:
- Notas simples sem retenção.
- Notas com muitos itens descritivos.
- Operações com intermediador.
- Notas com IBS e CBS.
- Casos com informações complementares extensas.
- Documentos que forçam quebra de página.
Depois disso, gero snapshots HTML, PDFs de referência e leitura de QR Code por rotina. Em times pequenos, isso já reduz bastante o risco. Em times maiores, vira parte do pipeline de CI.
Não confunda DANFSe com DANFE e DANFE NFC-e
Eu ainda encontro documentação interna misturando conceitos que deveriam estar separados. DANFSe é o documento auxiliar da Nota Fiscal de Serviços eletrônica. DANFE está ligado à NF-e de produto. Já o DANFE NFC-e atende a Nota Fiscal ao Consumidor eletrônica. São documentos parecidos na ideia de representar visualmente um XML fiscal, mas cada um tem finalidade, leiaute e regras próprias.
DANFSe, DANFE e DANFE NFC-e não são variações cosméticas do mesmo arquivo; eles pertencem a documentos fiscais diferentes.
Se a sua operação também emite nota de produto, vale manter essa separação clara até na arquitetura do sistema. Um bom ponto de apoio é acompanhar conteúdos sobre NF-e e seus fluxos específicos, sem misturar isso com a NFS-e Nacional na mesma camada de template.
Conclusão
Depois de estudar a NT-008 e revisar o que entrou em produção em 03/08/2026, minha leitura é objetiva: gerar o novo DANFSe com qualidade exige tratar o XML autorizado como fonte de verdade, estruturar um modelo tipado confiável, respeitar blocos obrigatórios e opcionais, renderizar HTML previsível e validar o PDF final com testes visuais reais. Quando isso é feito com método, o documento deixa de ser um ponto frágil do sistema.
Eu penso que este é o melhor momento para revisar sua implementação, ainda mais se você vinha usando a API anterior, descontinuada em 15/07/2026. Se quiser acelerar essa adaptação, minha sugestão é testar a biblioteca aberta @notaas/danfse-viewer ou conhecer a visualização oferecida pela Notaas, que conversa de forma natural com fluxos de emissão, automação e entrega via API.
Perguntas frequentes
O que é o DANFSe v2.0?
O DANFSe v2.0 é a versão atualizada do documento auxiliar da NFS-e Nacional, ajustada às regras da NT-008. Eu resumo assim: ele é o PDF ou a representação visual padronizada da nota de serviço eletrônica, com campos, blocos e elementos de validação organizados de forma uniforme. Ele não substitui o XML da nota, mas apresenta suas informações de forma legível e padronizada.
Como gerar o PDF da NFS-e Nacional?
Eu recomendo seguir um fluxo técnico simples: receber o XML autorizado, processar esse XML com um parser, transformar os dados em um modelo tipado, renderizar o HTML conforme o leiaute vigente e então converter esse HTML em PDF. Depois disso, revise QR Code, chave, margens, blocos opcionais e quebra de página. O caminho mais seguro para gerar o PDF é usar o XML autorizado como origem e não dados dispersos do sistema.
Qual a diferença entre DANFSe e NFS-e?
A NFS-e é o documento fiscal eletrônico em si, normalmente representado juridicamente pelo XML autorizado. O DANFSe é o documento auxiliar que apresenta essa nota em formato visual, como PDF ou impressão. Eu costumo explicar assim para equipes de produto: a nota é o dado fiscal eletrônico, e o DANFSe é sua visualização padronizada. NFS-e e DANFSe não são a mesma coisa, embora um dependa do outro.
Onde encontro exemplos de DANFSe v2.0?
Os melhores exemplos vêm de XMLs reais anonimizados e de implementações que seguem fielmente a NT-008 versão 1.01. Eu prefiro trabalhar com casos variados, incluindo retenções, descrições longas e tributos novos, porque isso mostra o comportamento do layout em cenários de produção. Se você quiser validar a renderização com mais rapidez, pode olhar a biblioteca aberta @notaas/danfse-viewer, que foi pensada justamente para esse tipo de conferência técnica.
Como configurar meu sistema para DANFSe v2.0?
Na minha experiência, a configuração correta passa por cinco pontos: atualizar o mapeamento do XML da NFS-e Nacional, separar parser de template, criar um modelo tipado para abastecer tela e PDF, ajustar CSS para impressão A4 e montar testes com XMLs reais anonimizados. Também vale confirmar a situação operacional no portal oficial no dia da publicação. Configurar o sistema para o novo DANFSe significa alinhar dados, regras de exibição e renderização no mesmo pipeline.
