API Pública Sudrel: NFS-e, NF-e, NFC-e e CT-e

API da Sudrel para emitir NFS-e, NF-e e NFC-e e para consultar NFS-e, NF-e e CT-e das suas empresas, com webhooks assinados e log de eventos. Os mesmos dados do painel, para o seu ERP, sistema contábil ou automação interna.

O que você quer fazer?

Quero...	Comece por
Emitir uma NFS-e e saber o resultado	Sua primeira nota, depois `POST /v1/nfse`
Emitir muitas notas de uma vez (até 5.000)	Emissão em lote
Emitir uma NF-e (modelo 55, venda de mercadoria)	Início rápido de NF-e, depois `POST /v1/nfe`
Emitir uma NFC-e (modelo 65, varejo presencial)	Emissão de NFC-e, depois `POST /v1/nfce`
Consultar documentos recebidos ou emitidos (NFS-e, NF-e, CT-e)	Documentos, `GET /v1/documents`
Ser avisado quando algo muda, sem ficar consultando	Webhooks e Eventos
Testar falhas antes de ir para produção	Simulador de falhas
Usar a Sudrel num assistente de IA	IA e MCP
Usar SDK, OpenAPI ou Postman	SDKs e OpenAPI e Postman
Entender um erro	Erros e status HTTP e Problemas comuns

Antes de ir para produção, leia as Regras de integração: são doze, curtas, e evitam nota duplicada e retentativa errada.

O que a API faz

Documento	Emitir	Consultar
NFS-e	Sim: `POST /v1/nfse` e `POST /v1/lotes`, em qualquer município do Brasil, pelo Sistema Nacional NFS-e ou pelo layout da própria prefeitura (como ISS Net Online, WebISS e os sistemas próprios). Você manda sempre o mesmo JSON; a Sudrel cuida da diferença	Sim: as emitidas pela Sudrel em `GET /v1/nfse`; as recebidas e as emitidas por qualquer sistema em `GET /v1/documents`
NF-e (modelo 55)	Sim: `POST /v1/nfe`, direto na SEFAZ da UF, com o certificado A1 da empresa, cancelamento, carta de correção, inutilização e contingência (SVC e EPEC). Os tributos vêm do seu ERP ou a Sudrel calcula pelo motor fiscal	Sim: as emitidas pela Sudrel em `GET /v1/nfe`; as recebidas e as emitidas por qualquer sistema em `GET /v1/documents`
NFC-e (modelo 65)	Sim: `POST /v1/nfce`, com caixas, QR Code e cupom de 80 mm	Sim: as emitidas pela Sudrel em `GET /v1/nfce`
DC-e (modelo 99)	Sim: `POST /v1/dce`, para quem transporta bens sem emitir nota fiscal	Sim: as emitidas pela Sudrel
CT-e	Não	Sim, em `GET /v1/documents`

Todos os estados e todas as prefeituras. A NF-e, a NFC-e e a DC-e emitem em qualquer UF, e a NFS-e em qualquer município, no padrão nacional ou no layout próprio da prefeitura. A Sudrel prepara a UF ou a prefeitura da sua empresa por conta própria, em minutos, a partir do cadastro: você não pede, não espera e não muda nada no seu código. Na sandbox (sdr_test_), a nota vai à homologação da SEFAZ.

Além disso: cadastro de empresas e certificado A1 (/v1/companies), prontidão para emitir, webhooks (/v1/webhooks), log de eventos (/v1/eventos), conta e consumo (/v1/account, /v1/usage).

Como a API funciona

Seu sistema
    |
    |  HTTPS + chave de API (Authorization: Bearer sdr_...)
    v
Sudrel API  https://api.sudrel.com.br/api
    |
    +-- Empresas e prontidão ........ /v1/companies
    +-- NFS-e e lotes ............... /v1/nfse, /v1/lotes  ---> Sistema Nacional NFS-e
    +-- NF-e e NFC-e ................ /v1/nfe, /v1/nfce    ---> SEFAZ da UF
    +-- Produtos e motor fiscal ..... /v1/produtos
    +-- Documentos .................. /v1/documents        <--- Ambiente de Dados Nacional e SEFAZ
    +-- Webhooks e eventos .......... /v1/webhooks, /v1/eventos  ---> seu sistema

Uma emissão:

POST /v1/nfse
   |
   +-- 412 empresa_nao_pronta ou 422 validacao --> nada foi criado: corrija e envie de novo
   |
   +-- nota criada e transmitida (a chamada espera até 10 s; Prefer: wait=N muda isso)
          |
          +-- 201 autorizada --------------------> pronto: numero e chave_acesso
          +-- 422 nfse_rejeitada ----------------> a nota existe, rejeitada: corrija e emita outra
          +-- 202 transmitindo ------------------> a Sudrel continua cuidando:
                                                   webhook NFSE_AUTORIZADA / NFSE_REJEITADA
                                                   ou GET /v1/nfse/{id}

202 não é erro. Quer dizer "recebido, ainda em andamento". Veja Estados da NFS-e.

Endereço base

https://api.sudrel.com.br/api

Toda rota começa por /v1. Nesta documentação os caminhos aparecem sem o endereço base: POST /v1/nfse é POST https://api.sudrel.com.br/api/v1/nfse.

Teste e produção usam o mesmo endereço. Quem decide o ambiente é a chave.

Autenticação

Toda chamada exige uma chave de API no cabeçalho Authorization:

Authorization: Bearer sdr_live_xxxxxxxxxxxxxxxxxxxxxxxx

Gere uma chave em Painel → Chaves de API (/painel/chaves-api). Ela é exibida uma única vez no momento da criação — se perder, revogue e crie outra.

Existem dois tipos de chave:

Prefixo	Ambiente	O que faz
`sdr_live_...`	Produção	Tudo: empresas, documentos recebidos e emissão de NFS-e, NF-e e NFC-e com valor fiscal.
`sdr_test_...`	Teste de emissão	Só emissão: NFS-e no ambiente de testes do Sistema Nacional (produção restrita) e NF-e e NFC-e na homologação da SEFAZ, com as suas empresas e o certificado real. Lê a lista de empresas, mas não altera empresa nem lê documento recebido.

Uma chave pode ser restrita a uma única empresa, e aí só enxerga essa empresa.

Toda resposta traz o cabeçalho X-Request-Id. Nas rotas de emissão, lote, webhooks e eventos, o corpo de erro repete o mesmo valor em requisicao_id. Guarde esse id: com ele você acha a chamada em Integrações › Log da API, por 30 dias.

Teste e produção

	Teste (`sdr_test_`)	Produção (`sdr_live_`)
Endereço	`https://api.sudrel.com.br/api`	O mesmo
Para onde vai a nota	Produção restrita do Sistema Nacional (o ambiente de testes oficial), de verdade	Produção do Sistema Nacional
Valor fiscal	Não	Sim
Conta na franquia, exige plano	Não	Sim
Certificado	O certificado real da empresa	O mesmo
Aparece no painel	Não	Sim
Empresas	Lê. Não cria nem altera (403)	Lê, cria e altera
Documentos recebidos	Não (403)	Sim
Webhooks e eventos	Só os de teste	Só os de produção
Itens por lote	Até 100	Até 5.000
Simulador de falhas	Sim	Não (422 `simulacao_so_no_sandbox`)
Série da DPS	`49999`	A da empresa

Os dois ambientes nunca se cruzam: a chave de teste só enxerga notas, lotes, webhooks e eventos de teste, e a de produção só os de produção. A mesma referencia e a mesma Idempotency-Key podem ser usadas nos dois.

Empresa que emite pelo sistema da própria prefeitura tem o teste combinado com a Sudrel: com a chave de teste, a prontidão vem com o item sandbox_municipio_proprio em bloqueio, e a emissão devolve 412 empresa_nao_pronta. Em produção, a mesma empresa emite normalmente.

Passar para produção

Crie uma chave sdr_live_ no painel. As rotas e o JSON são os mesmos: só a chave muda.
Consulte a prontidão com a chave nova (GET /v1/companies/{id}/prontidao). Em produção ela também confere o plano de Emissão (plano_emissao).
Cadastre o webhook de produção. O webhook criado com a chave de teste só recebe eventos de teste.
Guarde X-Request-Id (ou requisicao_id) nos seus logs desde o primeiro dia.

Guias

Comece aqui: Da chave de teste à primeira NFS-e autorizada, passo a passo, com curl, C# e Delphi.
Regras de integração: As doze regras que evitam nota duplicada, retentativa errada e limite estourado.
Receitas: Fluxos completos: emitir uma nota, emitir milhares, sincronizar documentos, receber webhooks e retentar.
Idempotência: Como Idempotency-Key e referencia impedem nota duplicada, e como repetir uma chamada com segurança.
Erros e status HTTP: Os dois formatos de erro, o que cada status HTTP significa e o catálogo de códigos.
Estados da NFS-e: Os 7 status de uma nota emitida, as transições, o que fazer em cada um e o webhook correspondente.
Prontidão: O que a empresa precisa ter para emitir, item por item, e o que bloqueia a emissão.
Paginação e limites: Cursor de cada lista, limite de 120 requisições por minuto e tamanho máximo do corpo.
Emissão de NFS-e: Emitir, validar, consultar, cancelar e substituir NFS-e, com ajustes automáticos por município.
Emissão em lote: Até 5.000 notas numa chamada, por JSON ou planilha, com resultado e reprocessamento por linha.
Início rápido de NF-e: A primeira NF-e no sandbox: a Sudrel calcula os tributos e completa o destinatário pelo CNPJ.
Emissão de NF-e: Emitir, validar, consultar, cancelar e corrigir NF-e modelo 55, com os tributos vindos do seu ERP.
Produtos e motor fiscal: Cadastro de produtos validado na tabela oficial e o cálculo dos tributos da NF-e com regra e fonte de cada valor.
NF-e pela planilha e em lote: A planilha Básica de NF-e (uma linha por produto), a de produtos, e o lote com tipo nfe.
Contingência da NF-e: Quando a SEFAZ de uma UF cai: esperar, SVC ou EPEC, sem nunca criar nota duplicada.
Emissão de NFC-e: NFC-e (modelo 65) pela API: caixas, cálculo pela Sudrel, QR Code, cupom de 80 mm e cancelamento em 30 minutos.
Emissão de DC-e: DC-e (Declaração de Conteúdo eletrônica) pela API: emissão própria, endereço pelo CEP, DACE em A4 e etiqueta 10 × 15, cancelamento em 24 horas.
Documentos: NFS-e, NF-e e CT-e recebidos e emitidos pelas empresas, com eventos e manifestações.
Conta: Dados da conta e consumo do ciclo atual.
Empresas: Cadastro de CNPJs, certificado A1, pausa, remoção e prontidão para emitir.
Webhooks: Avisos assinados com HMAC, retentativa por 72 horas, reenvio, troca de segredo e verificação em 4 linguagens.
Eventos: O log de eventos da conta, por cursor, com 90 dias de retenção.
Simulador de falhas: Provoque timeout, rejeição, Sefin fora e falha de transmissão com a chave de teste.
SDKs: SDKs de TypeScript e PHP e o que cada um cobre.
OpenAPI e Postman: A especificação OpenAPI em JSON e YAML, e como importar no Postman ou no Insomnia.
IA e MCP: Servidor MCP somente leitura para assistentes de IA, e orientações para quem escreve um agente.
Problemas comuns: O que fazer ao receber 401, 403, 404, 409, 412, 422, 429, webhook que não chega e nota parada.
Glossário: Os termos fiscais e técnicos usados nesta documentação.
Changelog: O que mudou na API e na documentação, por data.

Rotas

Conta

GET /v1/account: Dados da conta atual
GET /v1/cnpj/{cnpj}: Dados cadastrais de um CNPJ
GET /v1/usage: Consumo do ciclo de cobrança atual

Empresas

GET /v1/companies: Lista as empresas da conta
POST /v1/companies: Cadastra uma empresa (CNPJ) para monitoramento
GET /v1/companies/{id}: Detalhe de uma empresa
DELETE /v1/companies/{id}: Solicita a remoção da empresa
GET /v1/companies/{id}/prontidao: O que falta para a empresa emitir
POST /v1/companies/{id}/certificate: Envia (ou troca) o certificado digital A1 da empresa
POST /v1/companies/{id}/pause: Pausa o monitoramento da empresa
POST /v1/companies/{id}/resume: Retoma o monitoramento da empresa

Emissão de NFS-e

GET /v1/servicos/{codigo}/nbs: NBS admitidos para um código de serviço
GET /v1/municipios/{ibge}/parametros: Convênio e parâmetros oficiais de um município
GET /v1/nfse: Lista as NFS-e emitidas
POST /v1/nfse: Emite uma NFS-e
POST /v1/nfse/validacoes: Valida uma NFS-e sem emitir
GET /v1/nfse/{id}: Consulta uma NFS-e
GET /v1/nfse/{id}/xml: XML da NFS-e
GET /v1/nfse/{id}/pdf: PDF (DANFSe) da NFS-e
POST /v1/nfse/{id}/confirmacao: Confirma a transmissão de uma nota que espera confirmação
POST /v1/nfse/{id}/cancelamento: Cancela uma NFS-e autorizada

Documentos

GET /v1/documents: Lista notas fiscais
GET /v1/documents/{id}: Detalhe de uma nota fiscal

Emissão de NF-e

GET /v1/nfe: Lista as NF-e
POST /v1/nfe: Emite uma NF-e (modelo 55)
POST /v1/nfe/previas: Valida e mostra o XML sem emitir
GET /v1/nfe/prontidao/{empresa_id}: A empresa está pronta para emitir NF-e?
GET /v1/nfe/inutilizacoes: Números inutilizados pela Sudrel
GET /v1/nfe/{id}: Consulta uma NF-e
GET /v1/nfe/{id}/xml: XML autorizado (nfeProc)
GET /v1/nfe/{id}/danfe: DANFE em PDF
POST /v1/nfe/{id}/correcao: Corrige uma NF-e rejeitada e reenvia
POST /v1/nfe/{id}/descarte: Desiste de uma NF-e rejeitada
POST /v1/nfe/{id}/cancelamento: Cancela uma NF-e autorizada
POST /v1/nfe/{id}/cartas-correcao: Registra uma carta de correção (CC-e)

Contingência da NF-e

GET /v1/sefaz/status: Estado da SEFAZ de cada UF para a NF-e

Emissão de NFC-e

GET /v1/nfce: Lista as NFC-e
POST /v1/nfce: Emite uma NFC-e (modelo 65)
POST /v1/nfce/previas: Valida e mostra o XML sem emitir
GET /v1/nfce/prontidao/{empresa_id}: A empresa está pronta para emitir NFC-e?
GET /v1/nfce/csc/{empresa_id}: Se a empresa tem CSC cadastrado
PUT /v1/nfce/csc/{empresa_id}: Grava (ou troca) o CSC da empresa
DELETE /v1/nfce/csc/{empresa_id}: Remove o CSC da empresa
GET /v1/nfce/inutilizacoes: Inutilizações de números de NFC-e
GET /v1/nfce/{id}: Consulta uma NFC-e
GET /v1/nfce/{id}/xml: XML autorizado (nfeProc, com o QR Code)
GET /v1/nfce/{id}/danfe: Cupom (DANFE NFC-e) de 80 mm
POST /v1/nfce/{id}/cancelamento: Cancela uma NFC-e autorizada
POST /v1/nfce/{id}/descarte: Desiste de uma NFC-e rejeitada (ou que não saiu)
POST /v1/nfce/{id}/envio: Envia o cupom ao consumidor por e-mail
GET /v1/caixas: Lista os caixas de NFC-e
POST /v1/caixas: Cadastra um caixa
GET /v1/caixas/{id}: Consulta um caixa
PATCH /v1/caixas/{id}: Altera um caixa

Emissão de DC-e

GET /v1/dce: Lista as DC-e
POST /v1/dce: Emite uma DC-e (emissão própria)
GET /v1/dce/planilha-modelo: Modelo da planilha de DC-e
GET /v1/dce/prontidao/{empresa_id}: A empresa está pronta para emitir DC-e?
GET /v1/dce/{id}: Consulta uma DC-e
GET /v1/dce/{id}/xml: XML autorizado (dceProc)
GET /v1/dce/{id}/dace: DACE em PDF (A4 ou etiqueta 10 × 15)
POST /v1/dce/{id}/cancelamento: Cancela uma DC-e autorizada
POST /v1/dce/{id}/descarte: Desiste de uma DC-e rejeitada (ou que não saiu)

Produtos e motor fiscal

GET /v1/produtos: Lista os produtos
POST /v1/produtos: Cadastra um produto
GET /v1/produtos/{codigo}: Consulta um produto pelo código
PATCH /v1/produtos/{codigo}: Altera um produto
POST /v1/produtos/{codigo}/aprovacao-perfil: Aprova o perfil fiscal do produto
GET /v1/produtos/{codigo}/vinculos-entrada: Lista os vínculos do produto com as compras
POST /v1/produtos/{codigo}/vinculos-entrada: Vincula o produto às compras
DELETE /v1/produtos/{codigo}/vinculos-entrada/{id}: Remove um vínculo
GET /v1/nfe/perfil-fiscal/{empresa_id}: Perfil fiscal da empresa
PUT /v1/nfe/perfil-fiscal/{empresa_id}: Grava o perfil fiscal da empresa
POST /v1/nfe/perfil-fiscal/{empresa_id}/aprovacao: Aprova o perfil fiscal da empresa

Emissão em lote

GET /v1/lotes: Lista os lotes
POST /v1/lotes: Cria um lote de emissão
GET /v1/lotes/{id}: Consulta um lote
GET /v1/lotes/{id}/itens: Resultado por linha
GET /v1/lotes/{id}/relatorio: Relatório em planilha
GET /v1/lotes/{id}/etiquetas: DACE do lote de DC-e em etiquetas 10 × 15, num PDF só
POST /v1/lotes/{id}/emissao: Manda emitir um lote que aguardava
POST /v1/lotes/{id}/reprocessamento: Corrige linhas e emite de novo

Webhooks

GET /v1/webhooks: Lista os webhooks do ambiente da chave
POST /v1/webhooks: Cria um webhook
GET /v1/webhooks/{id}: Um webhook
PATCH /v1/webhooks/{id}: Altera eventos, endereço, ativo ou cabeçalhos
DELETE /v1/webhooks/{id}: Remove o webhook
POST /v1/webhooks/{id}/rotacao-segredo: Troca o segredo, com 24 horas de convivência
POST /v1/webhooks/{id}/teste: Manda um evento `webhook.teste` agora
GET /v1/webhooks/{id}/entregas: Entregas do webhook, das mais novas para as mais antigas
POST /v1/webhooks/{id}/reenvio: Reenvia eventos (um, um período ou um lote)

Eventos

GET /v1/eventos: Log de eventos da conta, por cursor