Website · Playground · Documentação · English
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.
| 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 |
– |
npm install @useinvio/nfse-sdkNode.js 20 ou mais recente. Nada para instalar no sistema: a validação XSD roda em WebAssembly.
NFSE_CERT_PATH=./certificado.pfx
NFSE_CERT_PASSWORD=sua-senhaimport { 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| 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/.
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-mcpOu 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 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.
Issues e PRs são bem-vindos. Veja CONTRIBUTING.md e o CHANGELOG.
MIT © Invio