Sudrel Public API: NFS-e, NF-e and CT-e

Sudrel API to issue NFS-e and to query NFS-e, NF-e and CT-e of your companies, with signed webhooks and an event log. The same data as the dashboard, for your ERP, accounting system or internal automation.

The API itself speaks Portuguese: field names, error codes and the messages it returns are the same in every language of this documentation. Only the explanations are translated.

What do you want to do?

I want to...	Start with
Issue an NFS-e and know the result	Your first invoice, then `POST /v1/nfse`
Issue many invoices at once (up to 5,000)	Batch issuance
Query documents received or issued (NFS-e, NF-e, CT-e)	Documents, `GET /v1/documents`
Get notified when something changes, without polling	Webhooks and Events
Test failures before going to production	Failure simulator
Use Sudrel in an AI assistant	AI and MCP
Use an SDK, OpenAPI or Postman	SDKs and OpenAPI and Postman
Understand an error	Errors and HTTP status and Troubleshooting

Before going to production, read the Integration rules: there are twelve, they are short, and they prevent duplicate invoices and wrong retries.

What the API does

Document	Issue	Query
NFS-e	Yes: `POST /v1/nfse` and `POST /v1/lotes`, through the Sistema Nacional NFS-e (and through the city hall system in municipalities that do not use the national one yet)	Yes: the ones issued by Sudrel in `GET /v1/nfse`; the received ones and the ones issued by any system in `GET /v1/documents`
NF-e	No	Yes, in `GET /v1/documents`
CT-e	No	Yes, in `GET /v1/documents`

Also: company and A1 certificate setup (/v1/companies), readiness to issue, webhooks (/v1/webhooks), event log (/v1/eventos), account and usage (/v1/account, /v1/usage).

How the API works

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
    +-- Documentos .................. /v1/documents        <--- Ambiente de Dados Nacional e SEFAZ
    +-- Webhooks e eventos .......... /v1/webhooks, /v1/eventos  ---> seu sistema

One issuance:

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 is not an error. It means "received, still in progress". See NFS-e statuses.

Base URL

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

Every route starts with /v1. In this documentation, paths appear without the base URL: POST /v1/nfse is POST https://api.sudrel.com.br/api/v1/nfse.

Test and production use the same URL. The key decides the environment.

Authentication

Every call requires an API key in the Authorization header:

Authorization: Bearer sdr_live_xxxxxxxxxxxxxxxxxxxxxxxx

Create a key in Painel → Chaves de API (Dashboard → API keys) (/painel/chaves-api). It is shown only once, when it is created. If you lose it, revoke it and create another one.

There are two kinds of key:

Prefix	Environment	What it does
`sdr_live_...`	Production	Everything: companies, received documents and NFS-e issuance with fiscal value.
`sdr_test_...`	Issuance test	NFS-e issuance only, in the Sistema Nacional test environment ("restricted production"), with your companies and the real certificate. Reads the company list, but does not change companies or read received documents.

A key can be restricted to a single company. Then it sees only that company.

Every response has the X-Request-Id header. In the issuance, batch, webhook and event routes, the error body repeats the same value in requisicao_id. Store this id: with it you find the call in Integrações › Log da API (Integrations › API log), for 30 days.

Test and production

	Test (`sdr_test_`)	Production (`sdr_live_`)
URL	`https://api.sudrel.com.br/api`	The same
Where the invoice goes	Sistema Nacional "restricted production" (the official test environment), for real	Sistema Nacional production
Fiscal value	No	Yes
Counts toward the plan allowance, requires a plan	No	Yes
Certificate	The company's real certificate	The same
Appears in the dashboard	No	Yes
Companies	Reads. Does not create or change (403)	Reads, creates and changes
Received documents	No (403)	Yes
Webhooks and events	Test ones only	Production ones only
Items per batch	Up to 100	Up to 5,000
Failure simulator	Yes	No (422 `simulacao_so_no_sandbox`)
DPS series	`49999`	The company's

The two environments never mix: the test key sees only test invoices, batches, webhooks and events, and the production key only production ones. The same referencia and the same Idempotency-Key can be used in both.

A company that issues through the city hall system has no test environment: with the test key, readiness returns the item sandbox_municipio_proprio in bloqueio, and issuance is refused with 412 empresa_nao_pronta.

Going to production

Create a sdr_live_ key in the dashboard. The routes and the JSON are the same: only the key changes.
Check readiness with the new key (GET /v1/companies/{id}/prontidao). In production it also checks the Emissão plan (plano_emissao).
Register the production webhook. A webhook created with the test key receives only test events.
Store X-Request-Id (or requisicao_id) in your logs from day one.

Guides

Get started: From the test key to the first authorized NFS-e, step by step, with curl, C# and Delphi.
Integration rules: The twelve rules that prevent duplicate invoices, wrong retries and exceeded limits.
Recipes: Complete flows: issue one invoice, issue thousands, sync documents, receive webhooks and retry.
Idempotency: How Idempotency-Key and referencia prevent duplicate invoices, and how to repeat a call safely.
Errors and HTTP status: The two error formats, what each HTTP status means and the code catalog.
NFS-e statuses: The 7 statuses of an issued invoice, the transitions, what to do in each one and the matching webhook.
Readiness: What the company needs to issue, item by item, and what blocks issuance.
Pagination and limits: Cursor of each list, limit of 120 requests per minute and maximum body size.
NFS-e issuance: Issue, validate, query, cancel and replace NFS-e, with automatic adjustments per municipality.
Batch issuance: Up to 5,000 invoices in one call, by JSON or spreadsheet, with a result and reprocessing per row.
Documents: NFS-e, NF-e and CT-e received and issued by the companies, with events and manifestations.
Account: Account data and usage in the current cycle.
Companies: CNPJ registration, A1 certificate, pause, removal and readiness to issue.
Webhooks: HMAC-signed notifications, retries for 72 hours, resending, secret rotation and verification in 4 languages.
Events: The account's event log, by cursor, with 90-day retention.
Failure simulator: Trigger timeout, rejection, Sefin down and transmission failure with the test key.
SDKs: TypeScript and PHP SDKs and what each one covers.
OpenAPI and Postman: The OpenAPI specification in JSON and YAML, and how to import it into Postman or Insomnia.
AI and MCP: Read-only MCP server for AI assistants, and guidance for agent builders.
Troubleshooting: What to do on 401, 403, 404, 409, 412, 422, 429, a webhook that does not arrive and a stuck invoice.
Glossary: The tax and technical terms used in this documentation.
Changelog: What changed in the API and in the documentation, by date.

Endpoints

Account

GET /v1/account: Current account data
GET /v1/usage: Usage in the current billing cycle

Companies

GET /v1/companies: Lists the account companies
POST /v1/companies: Registers a company (CNPJ) for monitoring
GET /v1/companies/{id}: Company details
DELETE /v1/companies/{id}: Requests company removal
GET /v1/companies/{id}/prontidao: What the company still needs to issue
POST /v1/companies/{id}/certificate: Upload (or replace) the company's A1 digital certificate
POST /v1/companies/{id}/pause: Pause monitoring for the company
POST /v1/companies/{id}/resume: Resume monitoring for the company

NFS-e issuance

GET /v1/servicos/{codigo}/nbs: NBS codes accepted for a service code
GET /v1/municipios/{ibge}/parametros: Agreement and official parameters of a municipality
GET /v1/nfse: List issued NFS-e
POST /v1/nfse: Issue an NFS-e
POST /v1/nfse/validacoes: Validate an NFS-e without issuing
GET /v1/nfse/{id}: Get an NFS-e
GET /v1/nfse/{id}/xml: NFS-e XML
GET /v1/nfse/{id}/pdf: NFS-e PDF (DANFSe)
POST /v1/nfse/{id}/confirmacao: Confirm transmission of an invoice that awaits confirmation
POST /v1/nfse/{id}/cancelamento: Cancel an authorized NFS-e

Documents

GET /v1/documents: List invoices
GET /v1/documents/{id}: Invoice detail

Batch issuance

GET /v1/lotes: List batches
POST /v1/lotes: Create an issuance batch
GET /v1/lotes/{id}: Get a batch
GET /v1/lotes/{id}/itens: Result per row
GET /v1/lotes/{id}/relatorio: Spreadsheet report
POST /v1/lotes/{id}/emissao: Issue a batch that was waiting
POST /v1/lotes/{id}/reprocessamento: Fix rows and issue again

Webhooks

GET /v1/webhooks: List the webhooks of the key's environment
POST /v1/webhooks: Create a webhook
GET /v1/webhooks/{id}: A webhook
PATCH /v1/webhooks/{id}: Change events, URL, active flag or headers
DELETE /v1/webhooks/{id}: Remove the webhook
POST /v1/webhooks/{id}/rotacao-segredo: Rotate the secret, with a 24-hour overlap
POST /v1/webhooks/{id}/teste: Send a `webhook.teste` event now
GET /v1/webhooks/{id}/entregas: Webhook deliveries, newest first
POST /v1/webhooks/{id}/reenvio: Resend events (one, a period or a batch)

Events

GET /v1/eventos: Account event log, by cursor