API de emissão de NFS-e: uma nota com 4 campos

Na API da Sudrel, o seu sistema manda só a empresa, o tomador, o valor e a descrição do serviço. O resto, do endereço do tomador às regras de cada município, a Sudrel resolve e explica na resposta. É o mesmo motor da emissão por planilha e pela tela: três formas de emitir, as mesmas notas no mesmo painel, em qualquer cidade do Brasil.

Criar conta e pegar a chave de teste Ler a documentação

por nota: empresa, tomador, valor e descrição: 4 campos; por nota: empresa, tomador, valor e descrição
notas por lote, em JSON ou planilha: 5.000; notas por lote, em JSON ou planilha
de falha para simular no sandbox: 8 cenários; de falha para simular no sandbox
de retentativa de cada webhook: 72 h; de retentativa de cada webhook

A chamada inteira

Esta é uma emissão completa. Valores em dinheiro vão como texto com ponto decimal, para nenhuma nota depender de arredondamento. A resposta traz a nota autorizada, o número, a chave de acesso e a lista de ajustes que a Sudrel fez para essa cidade.

Antes de emitir, a mesma nota pode ir para a rota de validação, que devolve os erros e os ajustes sem criar nada. E a prontidão da empresa diz, item por item, se o certificado, a configuração fiscal e o plano estão em dia.

Prefere um SDK? Em Node.js, npm install @sudrel/sdk, que traz também a linha de comando sudrel. Em PHP, composer require sudrel/sdk. Os dois geram a Idempotency-Key sozinhos e esperam a nota sair por você (guia do SDK).

E para um assistente de IA consultar as notas e as emissões da conta, há o servidor MCP da Sudrel, somente leitura: ele responde, mas não emite nem cancela nada.

curl https://api.sudrel.com.br/api/v1/nfse \
  -H "Authorization: Bearer sdr_test_..." \
  -H "Idempotency-Key: 7f1c0d9a-4a51-4e0e-9b1f-2b6f0d3c5a10" \
  -H "Content-Type: application/json" \
  -d '{
    "empresa_id": "0b7e6a52-3c1d-4f8e-9a20-5d4c3b2a1f00",
    "referencia": "PED-1001",
    "tomador": { "documento": "11222333000181" },
    "valor": "1500.00",
    "servico": { "descricao": "Consultoria em sistemas" }
  }'

O que muda para quem integra

Você manda o mínimo, a Sudrel completa

Razão social e endereço do tomador saem do CNPJ. Código de serviço, competência e regime vêm da configuração da empresa. A alíquota do ISS, quando obrigatória, vem do parâmetro oficial do município. Nada disso é escondido: cada campo preenchido, omitido ou exigido volta em ajustes, com o motivo e a regra.

As regras de cada município ficam do nosso lado

Município que não aceita inscrição municipal, que exige alíquota, que recusa o endereço do prestador: o motor aplica a regra antes do envio, e algumas rejeições conhecidas são corrigidas e reenviadas sozinhas. O seu sistema manda sempre o mesmo JSON, qualquer que seja a cidade.

Repetir a chamada nunca gera nota dobrada

Com Idempotency-Key e referência, a mesma chamada devolve a mesma nota. Se a comunicação com o Sistema Nacional cair no meio, a Sudrel consulta a DPS antes de tentar de novo, e a nota que já existia do outro lado é recuperada, não emitida outra vez.

Teste o que dá errado antes de ir para produção

A chave de teste emite de verdade no ambiente de testes do Sistema Nacional, sem valor fiscal e sem cobrar. E o simulador de falhas provoca rejeição com o código oficial que você escolher, timeout, Sefin fora do ar, processamento prolongado e DPS que talvez tenha saído, pelos mesmos estados e webhooks de uma nota real, sem tocar na Sefin.

Webhooks em que dá para confiar

Cada entrega é assinada com horário, o que impede reaproveitar um corpo capturado. Entrega que falha é repetida por até 72 horas, a troca de segredo convive com o antigo por 24 horas, e o log de eventos da conta guarda 90 dias para recuperar o que o seu sistema perdeu numa queda.

O erro aparece na sua tela, não num chamado

Todo erro traz um código estável, o campo, a correção em português e um requisicao_id. No painel, o log de requisições mostra o que o seu sistema mandou e o que a Sudrel respondeu, por 30 dias, com senhas e segredos mascarados.

Três formas de emitir, um painel só

Planilha. Até 5.000 notas por arquivo XLSX ou CSV, emitidas em cerca de 2 minutos. Como funciona a planilha.
Tela. Uma grade parecida com a planilha, para quem emite poucas notas e não quer montar arquivo.
API. Para o seu sistema emitir sozinho, nota a nota ou em lote. As notas aparecem no mesmo painel, marcadas com a origem API.

Perguntas frequentes

Quais campos são obrigatórios para emitir uma NFS-e pela API?

Para um tomador com CNPJ, quatro: a empresa emissora, o documento do tomador, o valor e a descrição do serviço. Razão social e endereço do tomador saem do CNPJ, e código de serviço, competência e alíquota vêm da configuração da empresa e dos parâmetros oficiais do município. Tudo pode ser informado na chamada quando você quiser decidir.

Dá para testar a API sem emitir nota de verdade?

Sim. A chave de teste (sdr_test_) emite no ambiente de testes do Sistema Nacional, com o certificado real da empresa, sem valor fiscal, sem cobrar e sem aparecer no painel. Com o cabeçalho X-Sudrel-Simular, a nota passa por cenários de falha (rejeição com o código que você escolher, timeout, Sefin fora do ar, falha de transmissão) sem ir à Sefin. O ambiente de testes vale para empresas que emitem pelo Emissor Nacional: prefeitura com sistema próprio não oferece um.

O que acontece se a conexão cair no meio da emissão?

Repita a chamada com a mesma Idempotency-Key: a resposta é a mesma nota. Do nosso lado, quando a comunicação com o Sistema Nacional falha, a Sudrel consulta a DPS antes de reenviar, então uma nota que já tinha sido autorizada é recuperada e nunca emitida duas vezes.

A API emite em qualquer cidade?

Sim. A nota sai pelo Emissor Nacional ou pelo sistema próprio da prefeitura, conforme o município, com o mesmo JSON. A diferença entre as cidades é tratada pelo motor de regras e aparece em ajustes.

Posso emitir muitas notas de uma vez pela API?

Sim. O lote aceita até 5.000 notas numa chamada, em JSON ou com a mesma planilha do painel. O resultado vem por linha, com relatório para baixar, e as linhas com erro podem ser corrigidas e reenviadas sem mexer nas que deram certo.

Quanto custa emitir pela API?

As notas emitidas pela API usam os mesmos planos de Emissão da planilha e da tela, e contam na mesma franquia. O ambiente de testes não cobra nada.

Para ir mais fundo

Emita a primeira nota de teste hoje.

A chave de teste emite no ambiente de testes do Sistema Nacional, sem cobrar.

Criar conta grátis