@sudrel/sdk

SDK oficial da API de emissão de NFS-e da Sudrel, com a CLI sudrel. Node 18 ou mais novo, sem dependências.

npm install @sudrel/sdk

Primeira nota

import { Sudrel } from '@sudrel/sdk';

const sudrel = new Sudrel({ chave: process.env.SUDREL_API_KEY }); // sdr_test_... no sandbox

const nota = await sudrel.nfse.emitir({
  empresa_id: '0b7e6a52-3c1d-4f8e-9a20-5d4c3b2a1f00',
  referencia: 'PED-1001', // mande sempre: é o que torna seguro repetir
  tomador: { documento: '11222333000181' },
  valor: '1500.00',
  servico: { descricao: 'Consultoria em sistemas' },
});

const final = await sudrel.nfse.esperar(nota.id); // autorizada, rejeitada, falha_transmissao...

emitir devolve a nota em qualquer desfecho da Sefin, inclusive rejeitada (com rejeicao.explicacao). Erro do pedido (validação, empresa não pronta, referência repetida) lança ErroSudrel.

O que o SDK faz por você

• Retentativa segura. Todo POST leva uma Idempotency-Key gerada uma vez e reaproveitada em cada tentativa. Se a conexão cair depois de a Sudrel receber a nota, a repetição devolve a mesma nota, nunca uma segunda. Repete só erro de rede, 429 (respeitando Retry-After) e 5xx.
• Erros tipados. ErroSudrel traz status, codigo (estável, programe em cima dele), campo, correcao, erros e requisicaoId, que você procura no painel em Integrações › Log da API.
• Paginação. Toda lista é um iterador: for await (const nota of sudrel.nfse.listar({ status: 'autorizada' })).
• Acompanhar sem martelar a API. nfse.esperar(id) consulta em 1 s, 2 s, 4 s, até 30 s entre consultas. Pra muitas notas, use webhook.
• Webhook. sudrel.webhooks.verificar(corpoBruto, req.headers['x-sudrel-signature-v2'], segredo) confere a assinatura com horário (tolerância de 5 minutos). Deduplique pelo X-Sudrel-Event-Id.

Recursos

| | | |---|---| | nfse | emitir, validar, obter, listar, cancelar, confirmar, esperar, xml, pdf | | lotes | criar (JSON), enviarPlanilha, obter, listar, itens, emitir, reprocessar, relatorio | | empresas | listar, obter, prontidao | | webhooks | criar, listar, obter, alterar, remover, rotacionarSegredo, testar, entregas, reenviar, verificar | | eventos | pagina, listar (o log da conta, por cursor) |

Simulador de falhas (sandbox)

Com a chave sdr_test_, provoque os casos difíceis sem tocar na Sefin:

await sudrel.nfse.emitir(corpo, { simular: 'timeout_depois_autorizada' });

Cenários: autorizada_lenta, rejeicao:<codigo>, timeout_depois_autorizada, sefin_fora, processamento_prolongado, falha_transmissao_nao_enviada, falha_transmissao_desconhecido, aguardando_confirmacao. O que cada um mostra está na documentação, seção "Simulador de falhas".

CLI

A chave vem de SUDREL_API_KEY.

sudrel nfse emitir nota.json --simular sefin_fora
sudrel nfse ver PED-1001
sudrel lotes enviar planilha.xlsx --empresa 0b7e6a52-3c1d-4f8e-9a20-5d4c3b2a1f00 --aguardar
sudrel lotes ver <id>
sudrel eventos seguir --encaminhar http://localhost:3000/webhook

eventos seguir lê o log de eventos da conta e reencaminha cada evento pro endereço local, assinado como um webhook de verdade com um segredo local que ela mostra ao iniciar. Teste o seu recebedor na sua máquina, sem expor porta e sem cadastrar webhook.

Documentação

https://sudrel.com.br/docs