Guia Completo da Nota Técnica NT-008: Mapeamento de XML e Layout Fluido do DANFSe v2.0

Introdução

A padronização dos documentos fiscais no Brasil é um processo complexo que envolve o alinhamento de milhares de prefeituras com legislações municipais distintas. A criação da Nota Fiscal de Serviço Eletrônica (NFS-e) de padrão nacional foi um marco para a simplificação tributária do país. Contudo, essa transição exige atualizações constantes por parte dos desenvolvedores que mantêm sistemas de faturamento e ERPs.

Atualmente, a principal referência normativa para a exibição visual deste documento é a Nota Técnica NT-008, que regulamenta as diretrizes do DANFSe v2.0 (Documento Auxiliar da NFS-e). Entre as principais novidades introduzidas por esta nota técnica estão a reformulação completa do layout do documento de serviço para um modelo dinâmico e flexível (conhecido como layout fluido ou flow-based) e a padronização rígida de decodificação dos campos tributários.

Neste guia técnico detalhado, vamos explorar a fundo os aspectos de engenharia de software da Nota Técnica NT-008, detalhando como realizar o mapeamento correto do XML com base no schema oficial tiposSimples_v1.01.xsd, como programar a lógica de supressão de blocos vazios e como construir um renderizador extensível e sustentável utilizando os conceitos de Programação Orientada a Objetos (OOP) em TypeScript.

A Estrutura de Dados do XML da NFS-e Nacional

Para construir um parser confiável, é preciso compreender de onde vêm os dados. O XML da NFS-e Nacional é estruturado sob o namespace oficial do SPED (http://www.sped.fazenda.gov.br/nfse). Diferente dos padrões antigos das prefeituras (que utilizavam o layout ABRASF puro), o XML nacional organiza as informações de forma hierárquica e otimizada.

A raiz do documento autorizado contém a tag <NFSe>, que abriga os detalhes da nota autorizada, o protocolo de homologação e a assinatura digital da Receita Federal. Dentro dela, a tag <infNFSe> agrupa as informações essenciais:

• Emitente (<emit>): Dados do prestador do serviço (CNPJ/CPF, Inscrição Municipal, Razão Social, Endereço e E-mail).
• Valores (<valores>): O valor total do serviço e a base de cálculo de impostos aplicados.
• DPS (<DPS>): Declaração de Prestação de Serviço que deu origem à nota fiscal. Contém as informações detalhadas do tomador (<toma>), do serviço executado (<serv>) e das alíquotas de tributação municipal e federal (<valores>).

A validação de cada campo do XML é regida pelo arquivo de definições tiposSimples_v1.01.xsd (e seus arquivos auxiliares de schemas). Qualquer alteração nos campos fiscais do sistema deve estar em conformidade estrita com as definições deste arquivo XSD para evitar rejeições na transmissão de dados.

Decodificando Enums Tributários Segundo o XSD Oficial

Um dos principais erros cometidos por desenvolvedores na hora de renderizar o DANFSe é a exibição de strings incorretas nos campos de regimes fiscais e tipos de tributação. A Nota Técnica NT-008 estabelece mapeamentos específicos para decodificar as tags numéricas do XML em texto legível no PDF final.

Abaixo, detalhamos os seis principais mapeamentos de enums fiscais que você precisa programar no seu parser de acordo com o padrão v1.01 dos schemas nacionais:

1. Ambiente Gerador (<ambGer>)

Indica a origem geradora do documento fiscal. Diferencia se a nota foi emitida por meio do portal nacional, de contingência ou diretamente pelo sistema municipal.

• Código 1: Prefeitura (indica que a emissão foi processada e enviada via canal municipal ou contingência local).
• Código 2: Produção Nacional (indica emissão direta pelo Ambiente de Dados Nacional).
• Código 3: Produção em Contingência Nacional (emissão realizada em contingência centralizada).

2. Tipo de Ambiente (<tpAmb>)

Define a validade jurídica do documento para fins fiscais.

• Código 1: Produção (nota válida perante o Fisco).
• Código 2: Homologação (nota de teste, sem validade fiscal ou financeira). Deve conter a inscrição visível "SEM VALOR FISCAL" em todo o documento auxiliar.

3. Regime de Apuração Tributária pelo Simples Nacional (<regApTribSN>)

Define a forma de recolhimento de impostos para empresas enquadradas no Simples Nacional.

• Código 1: MEI - Microempreendedor Individual (recolhimento unificado via DAS-MEI).
• Código 2: ME ou EPP (Microempresa ou Empresa de Pequeno Porte, com recolhimento baseado nas tabelas anexas da LC 123/2006).
• Código 3: Não Optante (empresas tributadas pelo Lucro Presumido ou Lucro Real).

4. Regime Especial de Tributação (<regEspTrib>)

Mapeia regimes de tributação diferenciados para determinados tipos de prestadores de serviços.

• Código 0: Nenhum (tributação padrão sem incentivos ou condições especiais).
• Código 1: Microempresa Municipal.
• Código 2: Estimativa.
• Código 3: Sociedade de Profissionais (como escritórios de advocacia ou contabilidade tributados por valores fixos).
• Código 4: Cooperativa.
• Código 5: Microempresário Individual (MEI).
• Código 6: Microempresário e Empresa de Pequeno Porte (ME/EPP).

5. Tipo de Imunidade (<tpImunidade>)

Usado quando a operação de serviço é imune à cobrança de impostos.

• Código 0: Não informado (tributável ou isento por outra modalidade).
• Código 1: Patrimônio, Renda ou Serviços da União, dos Estados, do DF e dos Municípios.
• Código 2: Templos de Qualquer Culto.
• Código 3: Partidos Políticos, inclusive suas fundações, entidades sindicais dos trabalhadores, instituições de educação e de assistência social, sem fins lucrativos.
• Código 4: Livros, Jornais, Periódicos e o papel destinado a sua impressão.

6. Tipo de Retenção de PIS/COFINS (<tpRetPISCOFINS>)

Define como será feita a retenção das contribuições federais de PIS e COFINS na fonte pagadora.

• Código 1: Retido (o tomador de serviços retém o imposto e recolhe a guia).
• Código 2: Não Retido (o próprio prestador recolhe os impostos em sua guia mensal).
• Código 3: Dispensado por limite de valor (retenção dispensada porque o valor da nota está abaixo do limite legal estabelecido pela Receita).

O Conceito de Layout Fluido (Flow-based Layout)

Diferente do DANFE da NF-e (modelo 55 de produtos), que possui campos e blocos com posições pixel-perfect rígidas devido à quantidade padrão de itens, o DANFSe v2.0 (modelo de serviços) lida com uma variação imensa de conteúdos. Uma nota de serviço pode conter um parágrafo curto de descrição ou um relatório detalhado de horas trabalhadas com milhares de caracteres.

Para lidar com isso de forma eficiente, a NT-008 introduz o Layout Fluido. Ele funciona sob o princípio de Redistribuição do Espaço Livre:

• Ocultação de Dados Ausentes: Se a nota fiscal não possui intermediários de serviço (o que ocorre em mais de 95% dos casos no Brasil), o bloco de "Intermediário de Serviço" não deve ser desenhado em branco. Ele é totalmente suprimido do HTML/CSS, liberando espaço para que a "Descrição dos Serviços" flua verticalmente de forma natural.
• Evitando Quebras de Páginas Inúteis: Em renderizadores rígidos de PDF, uma descrição de serviço ligeiramente maior do que o espaço reservado empurra todo o rodapé de valores para a segunda página, gerando uma folha quase vazia contendo apenas a assinatura e os totais. O layout fluido calcula a altura dinamicamente para manter o documento em página única sempre que for geometricamente possível.

Para implementar o layout fluido no desenvolvimento web, a melhor tecnologia é o uso combinado de CSS Flexbox, CSS Grid e a regra @media print com quebras de página controladas via page-break-inside: avoid.

Construindo um Renderizador Extensível em TypeScript (OOP)

Ao programar a renderização do DANFSe no seu sistema, é fundamental desenhar um código limpo e extensível para evitar retrabalho no futuro, quando novas notas técnicas forem lançadas pelo governo. O uso de Programação Orientada a Objetos (OOP), herança e polimorfismo é a melhor prática para isso.

A biblioteca pública @notaas/danfse-viewer foi desenhada especificamente seguindo esses conceitos. Abaixo, mostramos a arquitetura recomendada para o seu motor de visualização e como você pode estendê-lo para aplicar o polimorfismo e customizar o HTML conforme a identidade da sua empresa.

Arquitetura de Classes Recomendada:

• DanfseXmlParser: Classe responsável por ler a string XML do SPED, limpar namespaces, tratar tipagens de valores decimais e retornar um objeto fortemente tipado (DanfseData).
• DanfseHtmlBuilder: Classe responsável por receber o objeto estruturado e gerar a folha de marcação HTML aplicando as regras visuais da NT-008.

Exemplo de Extensão e Polimorfismo:

Imagine que você deseja utilizar a biblioteca open-source, mas precisa que o visualizador gerado exiba o logotipo personalizado da sua empresa no cabeçalho ou aplique um tema de cores específico de sua marca (ex: trocar a borda Crimson Red padrão por azul ou cinza).

Graças à orientação a objetos, você pode herdar a classe DanfseHtmlBuilder e sobrescrever o método de compilação sem precisar reescrever as 500 linhas de lógica do motor fiscal:

typescript

import { DanfseHtmlBuilder, type DanfseData } from '@notaas/danfse-viewer';

// 1. Criar sua classe herdando da classe base da biblioteca
export class CustomDanfseBuilder extends DanfseHtmlBuilder {
  private customLogoUrl: string;

  constructor(logoUrl: string) {
    super();
    this.customLogoUrl = logoUrl;
  }

  // 2. Sobrescrever o método build para injetar CSS ou alterar HTML (Polimorfismo)
  public override build(data: DanfseData): string {
    // Executa a montagem do HTML base padrão definido pela NT-008
    const htmlOriginal = super.build(data);

    // Injeta um bloco de CSS customizado no <head> para alterar o estilo visual
    const customStyle = `
      <style>
        :root {
          --color-primary: #1e3a8a; /* Altera o vermelho da Notaas para Azul Escuro */
          --color-border-focus: #1e40af;
        }
        .custom-watermark {
          opacity: 0.05;
        }
      </style>
    `;

    // Retorna o HTML alterado
    return htmlOriginal
      .replace('</head>', `${customStyle}</head>`)
      .replace('<!-- LOGO_PLACEHOLDER -->', `<img src="${this.customLogoUrl}" alt="Logo Empresa" />`);
  }
}

Dessa forma, o seu sistema ganha total flexibilidade para atender diferentes clientes (design white-label) mantendo a conformidade fiscal centralizada e protegida contra bugs na geração das tabelas e blocos fiscais oficiais.

Gerenciando Dados de Municípios (Resolvedor IBGE)

Um dos maiores desafios de rodar o gerador local é que o XML da NFS-e Nacional traz apenas os códigos IBGE dos municípios (como 3550308 para São Paulo/SP ou 3106200 para Belo Horizonte/MG) nos campos de local de incidência do imposto ou endereço do tomador. A norma técnica NT-008 exige que o DANFSe visual exiba a descrição do município e a sigla do estado por extenso.

Para que seu sistema exiba os nomes das cidades corretamente, você precisa alimentar o parser com uma lista de busca (lookup table) de municípios do IBGE:

typescript

import { DanfseXmlParser, type IbgeLookup } from '@notaas/danfse-viewer';
import { Pool } from 'pg';

async function processarNotaComIbge(xml: string) {
  // 1. Criar o mapa de busca do IBGE a partir do seu banco de dados
  const ibgeLookup: IbgeLookup = new Map();
  
  const dbPool = new Pool({ connectionString: 'SUA_URL_CONEXÃO_POSTGRES' });
  const dbResult = await dbPool.query('SELECT codigo_ibge, nome_municipio, sigla_uf FROM ibge_municipalities');
  
  for (const row of dbResult.rows) {
    ibgeLookup.set(String(row.codigo_ibge), { name: row.nome_municipio, uf: row.sigla_uf });
  }
  await dbPool.end();

  // 2. Passar o resolvedor do IBGE para o parser da biblioteca
  const parser = new DanfseXmlParser();
  const dadosNfse = await parser.parse(xml, ibgeLookup);

  // Agora, dadosNfse conterá os nomes de cidades resolvidos por extenso, 
  // permitindo que o construtor HTML desenhe o cabeçalho corretamente.
  console.log(`Cidade Prestação: ${dadosNfse.cLocPrestacaoFormatado}`); // Ex: "São Paulo / SP"
}

Conclusão: Biblioteca Local vs APIs Gerenciadas da Notaas

Seguindo este guia, a sua equipe de engenharia estará pronta para adaptar qualquer sistema ERP ao fim do visualizador ADN, fornecendo um renderizador local de alta performance baseado na Nota Técnica NT-008.

No entanto, vale ressaltar que a geração do PDF é apenas a última etapa do ciclo de vida de uma nota fiscal. A transmissão de dados, assinatura ICP-Brasil, contingência automática, leitura de retornos de prefeituras e a custódia segura de XMLs continuam sendo desafios complexos de infraestrutura.

Se a sua empresa busca focar no desenvolvimento do produto principal e deseja terceirizar a complexidade fiscal, a Notaas Platform é a parceira ideal. Oferecemos APIs REST de altíssima velocidade com suporte a múltiplos provedores municipais e portal nacional da NFS-e, garantindo que o seu sistema esteja sempre atualizado com as últimas legislações do Brasil de forma transparente.

Visite www.notaas.com.br e fale com um de nossos especialistas fiscais hoje mesmo para otimizar a sua esteira de emissão e faturamento!