SDK oficial para emitir NFS-e em Node.js e PHP: retentativa sem nota duplicada e erros previsíveis

A API de emissão da Sudrel tem SDK oficial para Node.js e para PHP. Os dois fazem a mesma coisa que uma chamada HTTP faria, mas resolvem de fábrica as três partes que mais dão trabalho numa integração fiscal: repetir sem duplicar nota, tratar erro de um jeito previsível e acompanhar a nota até a Sefin responder.

Instalação

• Node.js 18 ou mais novo, sem dependências: npm install @sudrel/sdk. Vem junto a linha de comando sudrel.
• PHP 8.1 ou mais novo, com as extensões curl e json: composer require sudrel/sdk.

A primeira nota

Para um tomador com CNPJ, quatro informações bastam: a empresa, o documento do tomador, o valor e a descrição.

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',
  tomador: { documento: '11222333000181' },
  valor: '1500.00',
  servico: { descricao: 'Consultoria em sistemas' },
});

const final = await sudrel.nfse.esperar(nota.id);

Em PHP é o mesmo desenho: $sudrel->nfse->emitir([...]) e $sudrel->nfse->esperar($id). A referencia é o identificador do pedido no seu sistema; mande sempre, porque é ela que torna seguro repetir.

Retentativa que não duplica nota

O caso mais perigoso numa emissão por API é a conexão cair depois que a nota chegou do outro lado. O sistema não recebeu resposta, tenta de novo, e sai uma segunda nota para o mesmo serviço. O SDK evita isso: todo envio leva uma chave de idempotência gerada uma vez e reaproveitada em cada nova tentativa. Se a primeira chegou, a repetição devolve a mesma nota, nunca uma segunda.

Ele repete sozinho só o que vale repetir: erro de rede, limite de requisições (respeitando o tempo que a API pede para esperar) e erro do servidor. Erro de validação não é repetido, porque mandar de novo daria o mesmo erro. Mais sobre o mecanismo em idempotência na emissão de NFS-e por API.

Erros que dá para programar em cima

Quando o pedido tem problema (campo inválido, empresa ainda sem certificado, referência repetida), o SDK lança ErroSudrel com o status HTTP, um codigo estável, o campo envolvido, a correcao em português e o requisicaoId. Esse id é o mesmo que aparece no painel, em Integrações › Log da API, então o suporte do seu lado acha a chamada exata.

Acompanhar a nota sem martelar a API

nfse.esperar(id) consulta a nota com intervalo crescente, de 1 em 1 segundo no começo até 30 segundos entre consultas, até ela sair de processamento. Para muitas notas, o caminho é o webhook, e o SDK confere a assinatura dele com webhooks.verificar, com a tolerância de horário de 5 minutos. Veja como funciona a assinatura do webhook.

Listas, lotes e planilha

• Toda lista é paginada sozinha: em Node, for await (const nota of sudrel.nfse.listar({ status: 'autorizada' })); em PHP, um foreach sobre o gerador.
• Lotes por JSON ou pela planilha que a sua equipe já usa (lotes.enviarPlanilha), com consulta de cada linha e reprocessamento.
• empresas.prontidao diz, item por item, se a empresa já pode emitir e o que falta em cada bloqueio.

Testar os casos difíceis antes de ir para produção

Com a chave de sandbox (sdr_test_), o mesmo código emite no ambiente de testes do Sistema Nacional, e o simulador provoca os casos que quase nunca acontecem quando você quer: resposta que se perde depois da autorização, Sefin fora do ar, processamento prolongado, rejeição com um código escolhido. Em Node, sudrel.nfse.emitir(corpo, { simular: 'timeout_depois_autorizada' }). O passo a passo está em como testar a API de emissão com o sandbox e o simulador.

Perguntas frequentes

O SDK da Sudrel é pago?

Não. O SDK é gratuito; o que conta no plano são as notas emitidas. Notas emitidas com a chave de sandbox não são cobradas.

Preciso usar o SDK para integrar?

Não. A API é REST com JSON e funciona com qualquer linguagem. O SDK só poupa o trabalho de idempotência, retentativa, paginação e verificação de webhook.

Se a conexão cair no meio do envio, a nota sai duplicada?

Não. O SDK repete o envio com a mesma chave de idempotência, e a API devolve a nota que já existe em vez de criar outra.

Referência completa de rotas e campos na documentação da API, e a visão geral do produto em emissão de NFS-e por API.