Introdução
No dia 15 de julho de 2026, o ecossistema de nota fiscal eletrônica de serviços no Brasil passará por uma mudança silenciosa, porém crítica. A Receita Federal e a Secretaria Executiva do Comitê Gestor da NFS-e Nacional desativarão em definitivo a API oficial do Visualizador ADN (Ambiente de Dados Nacional).
Para empresas de software, ERPs, contadores e desenvolvedores de soluções fiscais, essa data representa o fim de uma era de facilidades. Até então, bastava redirecionar o tomador de serviços para o link do governo federal ou fazer uma requisição simples via mTLS para obter o arquivo PDF formatado do Documento Auxiliar da Nota Fiscal de Serviço Eletrônica (DANFSe). A partir de meados de julho, qualquer sistema que dependa da infraestrutura pública para renderizar ou visualizar notas fiscais de serviço nacionais retornará erro, deixando clientes sem a representação gráfica de seus documentos.
Neste artigo abrangente, vamos analisar as razões por trás do desligamento da API ADN, os impactos diretos nos sistemas de faturamento brasileiros, os desafios técnicos impostos pelo novo layout da Nota Técnica NT-008 e, o mais importante, como implementar uma solução gratuita, offline e totalmente local utilizando a biblioteca open-source @notaas/danfse-viewer.
O que é a API ADN e por que ela será desativada?
O Sistema Nacional da NFS-e (SNNFSE) foi projetado para unificar a emissão de notas fiscais de serviço em todo o território nacional. No início da implantação, o governo federal disponibilizou a API do visualizador ADN como um facilitador técnico. O objetivo era acelerar a adoção do padrão nacional pelas prefeituras e emissores privados, permitindo que a renderização visual do DANFSe fosse feita de forma centralizada nos servidores da Receita Federal.
Sempre que uma nota fiscal era emitida com sucesso, o sistema gerava uma chave de acesso de 50 dígitos. Para exibir o DANFSe na tela do cliente ou gerar o PDF de impressão, o software emissor enviava a chave de acesso para o endpoint da API ADN e recebia o PDF pronto.
Contudo, essa centralização trouxe desafios imensos de infraestrutura. A quantidade de NFS-e emitidas no Brasil cresceu exponencialmente à medida que grandes capitais (como São Paulo, Rio de Janeiro e Belo Horizonte) integraram seus sistemas ao Ambiente de Dados Nacional. Manter servidores públicos capazes de renderizar milhões de arquivos PDF por dia em tempo real gerou custos elevados de processamento de dados e problemas de estabilidade nos horários de pico.
A Receita Federal decidiu, portanto, repassar a responsabilidade de geração do DANFSe para a iniciativa privada. A especificação do layout visual do DANFSe foi padronizada na Nota Técnica NT-008, e os desenvolvedores de software agora precisam implementar seus próprios motores de renderização local. O governo continuará fornecendo e assinando o arquivo XML autorizado da nota fiscal, mas a transformação desse XML em uma folha A4 organizada e legível para o usuário final deve ser resolvida localmente em cada ERP ou emissor.
O Impacto do Fim do Visualizador ADN nos ERPs
Se o seu sistema de emissão de notas fiscais ou o seu ERP ainda utiliza a API pública do governo para exibir a nota fiscal ao cliente, o impacto a partir de 15/07/2026 será imediato:
- Quebra de Links de Visualização: Os botões de "Visualizar Nota Fiscal" ou "Imprimir DANFSe" dentro do painel do cliente deixarão de funcionar, exibindo erros HTTP ou páginas em branco.
- Envio de Notas Sem PDF: Fluxos automatizados que buscam o PDF no portal federal para enviar ao cliente por e-mail ou WhatsApp vão travar ou enviar mensagens sem anexo.
- Sobrecarga no Suporte ao Cliente: A impossibilidade de gerar a guia de pagamento ou visualizar a nota fiscal gerará um volume maciço de chamados no suporte técnico de sistemas de faturamento.
- Perda de Credibilidade: Softwares que não se adaptarem a tempo perderão espaço no mercado B2B, onde a emissão e visualização de notas é um processo vital que não pode parar.
Para evitar esses problemas, a única alternativa viável é a migração para um gerador local e offline de DANFSe.
A Nova Realidade: DANFSe v2.0 e a Nota Técnica NT-008
A transição para a geração local não significa apenas copiar o layout antigo. A Receita Federal aproveitou a descentralização para lançar o DANFSe v2.0, cujas regras de diagramação e mapeamento de campos estão documentadas na Nota Técnica NT-008.
Diferente do layout tradicional de notas municipais (que costuma ser rígido e com tabelas fixas), o DANFSe v2.0 introduz o conceito de layout fluido ou flow-based. O objetivo principal é otimizar o espaço físico da folha de papel A4 para impressão ou exibição digital.
Principais características da NT-008:
- Supressão Automática de Blocos Vazios: Se uma NFS-e não contiver informações sobre impostos federais (PIS, COFINS, INSS), intermediários de serviço ou deduções, esses blocos inteiros devem ser omitidos do visualizador. O espaço que seria ocupado por eles é redistribuído, permitindo que a descrição do serviço ocupe uma área maior sem quebrar a nota em duas páginas de forma desnecessária.
- Mapeamento Estrito de Enums: O XML nacional armazena a maioria das configurações tributárias e de regime de apuração por meio de códigos numéricos (ex: 1 para Prestador, 2 para Tomador; ou 1 para Operação Tributável, 2 para Imunidade). O gerador visual deve decodificar esses números e exibir os termos exatos definidos na norma técnica em português.
- Exibição de Contingência e Cancelamento: Notas emitidas em contingência ou que foram canceladas após a autorização precisam de marcações visuais explícitas (marcas d'água ou cabeçalhos destacados) para evitar fraudes ou confusões financeiras.
Os Desafios Técnicos de Desenvolver um Renderizador do Zero
Muitos desenvolvedores subestimam a complexidade de criar um gerador de DANFSe local e tentam programar um layout em HTML/CSS do zero. Contudo, essa abordagem costuma esbarrar em diversos obstáculos difíceis de contornar:
- Dependência do Sistema de Arquivos (File System): Muitos geradores de PDF legados (como FPDF ou JasperReports) exigem ler arquivos de imagem de logotipos ou fontes diretamente do disco. Isso impede que o sistema funcione de forma eficiente em ambientes serverless ou edge functions (como AWS Lambda ou Cloudflare Workers), onde o acesso ao disco é limitado ou proibido.
- Lentidão no Processamento: Renderizar arquivos PDF a partir de layouts pesados pode consumir muita memória RAM e processamento de CPU. Em sistemas de alto volume, isso pode encarecer a infraestrutura de servidores rapidamente.
- Complexidade do XML: O XML da NFS-e Nacional é complexo e possui múltiplos namespaces. Parsear esses dados manualmente usando expressões regulares ou seletores manuais costuma gerar falhas quando o XML vem com pequenas variações de estrutura permitidas pelos schemas oficiais (como o
tiposSimples_v1.01.xsd). - Precisão de Impressão (A4 Retrato): Fazer com que o layout HTML seja convertido em um PDF com margens exatas de impressão A4 (210mm x 297mm) sem cortar textos ou criar páginas em branco adicionais exige um trabalho minucioso de CSS Paged Media.
A Solução: Biblioteca Open-Source @notaas/danfse-viewer
Para poupar a comunidade brasileira desse retrabalho de desenvolvimento, a equipe da Notaas lançou a biblioteca @notaas/danfse-viewer, licenciada sob a licença MIT e disponível publicamente no npm.
Esta biblioteca é o motor open-source de referência para geração do DANFSe v2.0 em conformidade com a NT-008. Ela resolve todos os problemas técnicos citados de forma simples e elegante:
- 100% Client-side e Serverless Ready: Não possui nenhuma dependência do Node.js ou do sistema de arquivos local (
fs). O logotipo oficial do SNNFSE e todos os ativos gráficos estão embutidos como constantes codificadas em Base64 no próprio código. Ela funciona nativamente no navegador (Vite/React/Vue), no Node.js tradicional, e em runtimes edge (como Cloudflare Workers/Pages e Vercel Edge). - Conformidade Total com a NT-008: O mapeamento de todos os enums tributários (como regimes especiais, tributação de ISSQN e regimes do Simples Nacional) foi validado contra a versão mais recente dos schemas oficiais (
v1.01). - Arquitetura OOP e Polimorfismo: Desenvolvida em TypeScript usando padrões de projeto orientados a objetos. A classe base do construtor de HTML (
DanfseHtmlBuilder) e o analisador de XML (DanfseXmlParser) podem ser facilmente herdados para que você injete o logotipo da sua empresa, altere fontes ou customize cores usando CSS customizado.
Como Implementar a Biblioteca no Seu Sistema (Passo a Passo)
A integração da biblioteca @notaas/danfse-viewer no seu fluxo de desenvolvimento pode ser feita em poucos minutos. A seguir, mostramos um guia prático para configurar a geração de HTML e PDF.
Passo 1: Instalar a Biblioteca
No diretório do seu projeto, execute o comando de instalação:
bashnpm install @notaas/danfse-viewer
Passo 2: Analisar o XML e Gerar o HTML do DANFSe
Crie um arquivo JavaScript ou TypeScript e adicione o seguinte código para extrair os dados do XML autorizado da NFS-e Nacional e transformá-lo em uma string HTML pronta para visualização:
typescriptimport { DanfseXmlParser, DanfseHtmlBuilder } from '@notaas/danfse-viewer';
import * as fs from 'fs';async function gerarHtmlNota() {
// 1. Ler o arquivo XML autorizado da NFS-e Nacional
const xmlString = fs.readFileSync('./exemplo-nfse.xml', 'utf-8'); // 2. Instanciar o Parser para ler os dados estruturados do XML
const parser = new DanfseXmlParser();
const dadosNfse = await parser.parse(xmlString); // 3. Instanciar o Builder para gerar o HTML do DANFSe v2.0
const builder = new DanfseHtmlBuilder();
const htmlResult = builder.build(dadosNfse); // 4. Salvar o HTML gerado ou enviar para o navegador
fs.writeFileSync('./danfse.html', htmlResult);
console.log('✅ HTML do DANFSe gerado com sucesso!');
}gerarHtmlNota();
Passo 3: Converter o HTML em PDF com Puppeteer (Local)
Para gerar o arquivo PDF pronto para download ou anexo de e-mail, você pode utilizar o Puppeteer (Chromium headless) para renderizar a string HTML que geramos no passo anterior e exportar como PDF A4:
typescriptimport puppeteer from 'puppeteer';
import * as fs from 'fs';
import { DanfseXmlParser, DanfseHtmlBuilder } from '@notaas/danfse-viewer';async function gerarPdfNota() {
const xmlString = fs.readFileSync('./exemplo-nfse.xml', 'utf-8');
const parser = new DanfseXmlParser();
const dados = await parser.parse(xmlString);
const builder = new DanfseHtmlBuilder();
const html = builder.build(dados); // Iniciar o navegador headless
const browser = await puppeteer.launch({ headless: true });
const page = await browser.newPage(); // Injetar o HTML diretamente na página
await page.setContent(html, { waitUntil: 'domcontentloaded' }); // Exportar como PDF com formato A4 e margens zeradas (o layout do CSS já cuida das margens)
const pdfBuffer = await page.pdf({
format: 'A4',
printBackground: true,
margin: { top: '0mm', right: '0mm', bottom: '0mm', left: '0mm' }
}); await browser.close(); // Salvar o buffer no disco
fs.writeFileSync('./danfse.pdf', pdfBuffer);
console.log('✅ PDF do DANFSe salvo localmente!');
}gerarPdfNota();
Este fluxo garante que você tenha total independência da infraestrutura de servidores públicos, rodando o processo de ponta a ponta na sua própria aplicação com alta performance e sem limitações de requisições.
Testando Online no Playground Gratuitamente
Se você quiser validar a renderização visual do seu XML antes de começar a codificar, nós disponibilizamos um playground online gratuito:
🔗 Visualizador DANFSe Online (danfse.notaas.com.br)
Neste portal, você pode arrastar e soltar o XML da sua NFS-e Nacional para ver o resultado do layout instantaneamente no navegador, além de testar o recurso de impressão e exportação para PDF de forma totalmente interativa e client-side (seus dados fiscais nunca saem do seu navegador e não são enviados a nenhum servidor externo, garantindo conformidade com a LGPD).
O Próximo Passo: Emissão Escalável com a Notaas Platform
A biblioteca open-source @notaas/danfse-viewer resolve de forma brilhante a dor da visualização e geração de PDFs após a desativação do visualizador ADN do governo. No entanto, se o seu desafio for a esteira de emissão completa da NFS-e Nacional, a complexidade é muito maior.
Emitir notas fiscais em larga escala no padrão nacional exige:
- Gerenciamento seguro de certificados digitais A1 de múltiplos clientes (multi-tenant).
- Assinatura digital XMLDSig e criptografia utilizando chaves privadas e certificados vigentes.
- Transmissão assíncrona de lotes via SOAP para o Ambiente de Dados Nacional da NFS-e.
- Tratamento de contingência automática (como o uso de chave de contingência e envio tardio quando os servidores da Receita Federal estão instáveis).
- Webhooks para notificar seu sistema sobre a autorização, rejeição ou cancelamento de notas em tempo real.
Para simplificar essa jornada e permitir que você foque no core-business do seu produto, desenvolvemos a Notaas Platform. A nossa plataforma oferece APIs REST modernas, rápidas e documentadas que abstraem toda a burocracia dos protocolos governamentais.
Com uma única chamada de API, você envia os dados do serviço e nós cuidamos da validação do schema, assinatura, transmissão para a prefeitura ou portal nacional, armazenamento seguro do XML no Cloudflare R2 e envio automático do PDF formatado do DANFSe v2.0 para o seu cliente.
Conheça os nossos planos e acelere o desenvolvimento fiscal do seu sistema acessando www.notaas.com.br.
