nferapido

SDK oficial do NFeRápido — emissão de NF-e, NFC-e, NFS-e (municipal e nacional), CT-e, MDF-e, BP-e e NFCom direto na SEFAZ, com emissão ilimitada em todos os planos.

• Zero dependências (fetch nativo — Node 18+)
• TypeScript incluso (CJS + ESM)
• Idempotência de fábrica: retry nunca duplica nota
• Verificação de assinatura de webhook em uma função

npm install nferapido

Começando

Crie a conta em app.nferapido.com.br, cadastre a empresa (o CNPJ preenche o cadastro sozinho), suba o certificado A1 e gere um token em Empresa → API Keys.

import NFeRapido from 'nferapido';

// nfr_test_... = homologação (nunca emite de verdade) · nfr_live_... = produção
const nfe = new NFeRapido('nfr_test_...');

const nota = await nfe.emitirNFe({
  ide: { natOp: 'Venda', serie: 1 },
  dest: { cnpj: '33000167000101', xNome: 'Cliente LTDA', /* ... */ },
  det: [/* itens */],
  total: { vProd: '100.00', vNF: '100.00' },
  pag: [{ tPag: '01', vPag: '100.00' }],
}, { idempotencyKey: 'pedido-8842' });

console.log(nota.chave, nota.status);

O contrato campo a campo de cada documento está na documentação e no Swagger.

Idempotência (use sempre)

Passe idempotencyKey derivada do seu identificador de negócio em toda emissão feita por sistema:

await nfe.emitirNFe(payload, { idempotencyKey: `pedido-${pedido.id}` });

• Timeout no meio da chamada? Repita com a mesma chave: a API devolve a mesma nota (idempotent_replay: true) em vez de emitir uma segunda.
• O SDK só faz retry automático (falha de rede, 502–504) quando a chamada é segura de repetir — GET, ou escrita com idempotencyKey. Escrita sem chave nunca é re-tentada às cegas: é o seu caixa que agradece.
• Rejeição da SEFAZ libera a chave: corrija o payload e reenvie com a mesma.

Como funciona por dentro →

Documentos

await nfe.emitirNFe(payload, opts);           // NF-e (55)
await nfe.emitirNFCe(payload, opts);          // NFC-e (65) — PDV
await nfe.emitirNFSe(payload, opts);          // NFS-e municipal
await nfe.emitirNFSeNacional(payload, opts);  // NFS-e Nacional (LC 214/2025)
await nfe.emitirCTe(payload, opts);           // CT-e (57)
await nfe.emitirMDFe(payload, opts);          // MDF-e (58) — síncrono
await nfe.emitirBPe(payload, opts);           // BP-e (63) — síncrono
await nfe.emitirNFCom(payload, opts);         // NFCom (62) — síncrono

await nfe.cancelarNFe(id, 'justificativa com 15+ caracteres');
await nfe.cartaCorrecaoNFe(id, 'texto da correção');
await nfe.devolucaoNFe(payload);              // NF-e de devolução
await nfe.encerrarMDFe(id, { cMun: '3550308', UF: 'SP' });

await nfe.consultarNFe(chave);                // por chave de acesso
await nfe.consultarCNPJ('33000167000101');    // Receita
await nfe.consultarIE('33000167000101','RJ'); // SEFAZ (grátis) → Sintegra
await nfe.consultarCEP('01001000');

Qualquer endpoint sem método dedicado (são 300+):

await nfe.request('GET', '/nfce/ID/danfe');

Webhooks

Configure a URL em Empresa → Webhook de notificações (painel) e valide cada entrega com o secret exibido na criação:

import { verificarAssinaturaWebhook } from 'nferapido';

app.post('/webhooks/nferapido', express.raw({ type: '*/*' }), (req, res) => {
  const ok = verificarAssinaturaWebhook(
    req.body,                              // corpo BRUTO (não re-serialize!)
    req.header('X-NFeRapido-Signature'),
    process.env.NFERAPIDO_WEBHOOK_SECRET,
  );
  if (!ok) return res.status(401).end();

  const evento = JSON.parse(req.body.toString('utf8'));
  // evento.resultado: autorizada | rejeitada | cancelada ...
  res.status(200).end();
});

A comparação é em tempo constante; X-NFeRapido-Delivery é estável entre retries — use-o para deduplicar.

Erros

import { NFeRapidoError } from 'nferapido';

try {
  await nfe.emitirNFe(payload, { idempotencyKey: 'pedido-1' });
} catch (err) {
  if (err instanceof NFeRapidoError) {
    console.error(err.status, err.message, err.body);
    // 422 → payload inválido/rejeição · 402 → saldo · 409 → mesma chave em processamento
  }
}

Homologação sem medo

Token nfr_test_ nunca emite em produção — o rebaixamento para homologação é aplicado pela API em todas as rotas de emissão e coberto por teste automatizado do lado de cá.

Licença

MIT