Skip to content
useinvioPublic

About

SDK TypeScript para emitir, consultar e gerenciar NFS-e Nacional.

Topics

Resources

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

63 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

@useinvio/nfse-sdk

npm version CI Node.js License: MIT

Website · Playground · Documentação · English

NFS-e SDK

Emita, consulte e cancele NFS-e Nacional em TypeScript, sem escrever XML fiscal na mão.

Você descreve a nota em JSON; o SDK monta a DPS, valida contra o XSD oficial, assina com o certificado A1, compacta, envia por mTLS para a SEFIN e devolve a resposta oficial em formato estruturado. Sem binários nativos e sem xmllint.

O que ele faz

Operação Função No NfseClient
Emitir a partir de JSON ou XML emitirNfse invoices.create
Validar sem enviar (JSON + XSD) validateDpsJsonRequest, buildDpsFromJson invoices.buildDpsJson
Consultar com resultado tipado obterNfse invoices.retrieve
Recuperar uma emissão após timeout recuperarNfsePorDps invoices.recover
Cancelar / cancelar por substituição cancelarNfse, cancelarNfsePorSubstituicao invoices.cancel, invoices.cancelBySubstitution
Baixar o DANFSe em PDF baixarDanfse invoices.danfse
Distribuição por NSU e parâmetros municipais (ADN) distribuirDfePorNsu, consultarAliquota… distribution, municipalParameters
Explicar rejeições com o texto oficial explicarRejeicao, explicarErros, uma página por código –
Usar pelo terminal npx nfse init, doctor, validate, emit, explain –
Testar sem certificado nem rede @useinvio/nfse-sdk/testing –
Servidor MCP e ferramentas para agentes de IA npx -y @useinvio/nfse-mcp, @useinvio/nfse-sdk/agent –

Instalação

npm install @useinvio/nfse-sdk

Node.js 20 ou mais recente. Nada para instalar no sistema: a validação XSD roda em WebAssembly.

Em 60 segundos

NFSE_CERT_PATH=./certificado.pfx
NFSE_CERT_PASSWORD=sua-senha
import { emitirNfse, EmitirNotaError, NfseCertificate } from '@useinvio/nfse-sdk';

const certificado = NfseCertificate.fromEnv(); // a chave privada nunca aparece em logs

const nota = {
  ambiente: 'restrita' as const, // produção restrita: o sandbox oficial
  prestador: {
    cnpj: '12345678000195',
    cLocEmi: '4106902',
    serie: '1601',
    opSimpNac: '1',
    regEspTrib: '0',
  },
  servico: {
    cTribNac: '010201',
    xDescServ: 'Desenvolvimento de software',
    cLocPrestacao: '4106902',
    cNBS: '115022000',
  },
  emissao: {
    nDPS: '1',
    dhEmi: '2026-06-15T10:30:00-03:00',
    dCompet: '2026-06-01',
    valores: { vServ: '1500.00' },
    tributacaoMunicipal: { tribISSQN: '1', tpRetISSQN: '1' },
    tributacaoFederal: { piscofins: { CST: '07' } },
    totTrib: { pTotTribFed: '0.00', pTotTribEst: '0.00', pTotTribMun: '5.00' },
  },
};

try {
  const { chaveAcesso, nfseXml } = await emitirNfse(nota, certificado);
  console.log(chaveAcesso); // chave de 50 dígitos
} catch (error) {
  if (!(error instanceof EmitirNotaError)) throw error;
  for (const rejeicao of error.erros) console.error(rejeicao.Codigo, rejeicao.Descricao);
}

Primeira vez? Siga o tutorial: emitir, consultar, baixar o PDF e cancelar na produção restrita, do zero. Ou experimente sem certificado, pelo terminal:

npx nfse init && npx nfse emit nota.json --mock

Documentação

Guia
Certificado A1 Variáveis de ambiente, cofres de segredo, vários emitentes.
Emitir JSON, NfseClient, XML pronto, série e número.
Consultar e DANFSe Resultado tipado e PDF.
Recuperar após timeout Sem notas duplicadas quando a conexão cai.
Cancelar e101101 e substituição (e105102).
Erros e rejeições O que cada erro significa e o que fazer.
Linha de comando nfse doctor, emit, cancel, explain.
Testar sem certificado SEFIN simulada para o seu CI.
Agentes de IA e MCP Servidor MCP, plugin do Claude Code, ferramentas para o seu agente.
Referência da API Todas as funções.
Mapeamento do JSON Cada campo de DpsJsonRequest.

Exemplos executáveis em examples/.

Com agentes de IA

Emita uma NFS-e conversando com o Claude. Para experimentar sem certificado, o modo de teste usa uma SEFIN simulada:

claude mcp add nfse --env NFSE_MCP_MOCK=1 --env NFSE_MCP_ALLOW_WRITE=1 -- npx -y @useinvio/nfse-mcp

Ou instale o plugin do Claude Code, que inclui o servidor e uma skill com o fluxo:

/plugin install nfse-nacional --marketplace useinvio/nfse-sdk

Emitir e cancelar sempre passam por um resumo que você aprova antes do envio, e o certificado nunca chega ao modelo. Veja o guia de agentes e MCP. Para assistentes de código, o pacote inclui llms.txt.

O que fica com a sua aplicação

O SDK cuida do protocolo; ele não é um motor fiscal. Códigos de serviço, CST, alíquotas, retenções, regime tributário e a numeração da DPS são decisões da sua aplicação e de quem cuida da parte tributária. Campos fiscais obrigatórios nunca recebem valores padrão silenciosos. O grupo IBS/CBS da reforma tributária ainda não é suportado.

Contribuir

Issues e PRs são bem-vindos. Veja CONTRIBUTING.md e o CHANGELOG.

Licença

MIT © Invio

About

SDK TypeScript para emitir, consultar e gerenciar NFS-e Nacional.

Topics

Resources

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages