@treeunfe/nfse

Biblioteca NFS-e Sistema Nacional (DPS) para Treeunfe DFe — APIs REST gov.br/nfse.

Escopo: apenas emissão nacional via DPS (Declaração de Prestação de Serviços).
Não inclui NFP-SP / Nota Fiscal Paulistana nem layouts municipais legados.

Funcionalidades

| Operação | Método adapter | Status | |----------|----------------|--------| | Autorização DPS | Autorizacao(dps) | Implementado | | Consulta por chave | Consulta({ chaveAcesso }) | Implementado | | Consulta DPS por ID | ConsultaDPS(data) | Implementado | | Registro de eventos | RegistrarEvento(data) | Implementado | | Consulta de eventos | ConsultarEvento(data) | Implementado | | Distribuição por NSU | DistribuicaoPorNSU(data) | Implementado | | Eventos por chave | EventosPorChave(data) | Implementado | | Parâmetros municipais (ADN) | ConsultarAliquota, ConsultarConvenio, etc. | Implementado | | DANFSe PDF (local NT-008) | GerarDanfse(props) | Implementado |

Utilities exportadas: decodeNFSeB64Gzip, parseNFSeXml.

Início rápido

import { NFSe, decodeNFSeB64Gzip, parseNFSeXml } from '@treeunfe/nfse';
import path from 'path';

const client = new NFSe({
  ambiente: 2, // 1 = Produção | 2 = Homologação (Sefin Nacional)
  pathCertificado: path.resolve('certificado.pfx'),
  senhaCertificado: 'sua_senha',
  useForSchemaValidation: 'validateSchemaJsBased',
  connection: { timeout: 30_000 },
});

const resp = await client.Autorizacao(dpsPayload);
const xml = decodeNFSeB64Gzip(resp.response.nfseXmlGZipB64);
const NFSe = parseNFSeXml(xml);

await client.GerarDanfse({
  data: { NFSe },
  outputPath: `tmp/DANFSe/${resp.response.chNFSe}-DANFSe.pdf`,
});

Documentação de referência

XSDs em runtime: packages/shared/resources/schemas/nfse/

Consulte documentação oficial NFS-e Nacional (gov.br) e NT-008 (DANFSe).

Exemplo / testes

NFSE_EMITIR=1 pnpm test:nfse             # autorização DPS
pnpm test:nfse                           # script interativo na raiz

Fixtures: examples/NFSe/

Notas

• Comunicação REST/JSON (Sefin Nacional + ADN) — distinto da família SOAP NF-e/CT-e
• DANFSe é gerada localmente (NT-008); API HTTP da SefIN será suspensa em 01/07/2026
• parseNFSeXml aceita <NFSe> ou <nfseProc>