API pública de Sudrel: NFS-e, NF-e y CT-e

API de Sudrel para emitir NFS-e y para consultar NFS-e, NF-e y CT-e de tus empresas, con webhooks firmados y registro de eventos. Los mismos datos del panel, para tu ERP, sistema contable o automatización interna.

La API en sí habla portugués: los nombres de campo, los códigos de error y los mensajes que devuelve son los mismos en todos los idiomas de esta documentación. Solo se traducen las explicaciones.

¿Qué quieres hacer?

Quiero...	Empieza por
Emitir una NFS-e y conocer el resultado	Tu primera nota fiscal, después `POST /v1/nfse`
Emitir muchas notas fiscales a la vez (hasta 5.000)	Emisión por lotes
Consultar documentos recibidos o emitidos (NFS-e, NF-e, CT-e)	Documentos, `GET /v1/documents`
Recibir avisos cuando algo cambia, sin consultar todo el tiempo	Webhooks y Eventos
Probar fallos antes de pasar a producción	Simulador de fallos
Usar Sudrel en un asistente de IA	IA y MCP
Usar SDK, OpenAPI o Postman	SDKs y OpenAPI y Postman
Entender un error	Errores y estados HTTP y Problemas comunes

Antes de pasar a producción, lee las Reglas de integración: son doce, cortas, y evitan notas fiscales duplicadas y reintentos incorrectos.

Qué hace la API

Documento	Emitir	Consultar
NFS-e	Sí: `POST /v1/nfse` y `POST /v1/lotes`, por el Sistema Nacional NFS-e (y por el sistema de la alcaldía en los municipios que todavía no usan el nacional)	Sí: las emitidas por Sudrel en `GET /v1/nfse`; las recibidas y las emitidas por cualquier sistema en `GET /v1/documents`
NF-e	No	Sí, en `GET /v1/documents`
CT-e	No	Sí, en `GET /v1/documents`

Además: registro de empresas y certificado A1 (/v1/companies), preparación para emitir, webhooks (/v1/webhooks), registro de eventos (/v1/eventos), cuenta y consumo (/v1/account, /v1/usage).

Cómo funciona la API

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

Una emisión:

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 no es un error. Significa "recibido, todavía en curso". Consulta Estados de la NFS-e.

Dirección base

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

Toda ruta empieza por /v1. En esta documentación las rutas aparecen sin la dirección base: POST /v1/nfse es POST https://api.sudrel.com.br/api/v1/nfse.

Prueba y producción usan la misma dirección. Quien decide el entorno es la clave.

Autenticación

Toda llamada exige una clave de API en el encabezado Authorization:

Authorization: Bearer sdr_live_xxxxxxxxxxxxxxxxxxxxxxxx

Genera una clave en Painel → Chaves de API (Panel → Claves de API) (/painel/chaves-api). Se muestra una sola vez, en el momento de la creación: si la pierdes, revócala y crea otra.

Hay dos tipos de clave:

Prefijo	Entorno	Qué hace
`sdr_live_...`	Producción	Todo: empresas, documentos recibidos y emisión de NFS-e con valor fiscal.
`sdr_test_...`	Prueba de emisión	Solo emisión de NFS-e, en el entorno de pruebas del Sistema Nacional (producción restringida), con tus empresas y el certificado real. Lee la lista de empresas, pero no modifica empresas ni lee documentos recibidos.

Una clave puede estar restringida a una sola empresa, y entonces solo ve esa empresa.

Toda respuesta trae el encabezado X-Request-Id. En las rutas de emisión, lote, webhooks y eventos, el cuerpo del error repite el mismo valor en requisicao_id. Guarda ese id: con él encuentras la llamada en Integrações › Log da API (Integraciones › Registro de la API), durante 30 días.

Prueba y producción

	Prueba (`sdr_test_`)	Producción (`sdr_live_`)
Dirección	`https://api.sudrel.com.br/api`	La misma
Adónde va la nota fiscal	Producción restringida del Sistema Nacional (el entorno de pruebas oficial), de verdad	Producción del Sistema Nacional
Valor fiscal	No	Sí
Cuenta en la franquicia, exige plan	No	Sí
Certificado	El certificado real de la empresa	El mismo
Aparece en el panel	No	Sí
Empresas	Lee. No crea ni modifica (403)	Lee, crea y modifica
Documentos recibidos	No (403)	Sí
Webhooks y eventos	Solo los de prueba	Solo los de producción
Ítems por lote	Hasta 100	Hasta 5.000
Simulador de fallos	Sí	No (422 `simulacao_so_no_sandbox`)
Serie de la DPS	`49999`	La de la empresa

Los dos entornos nunca se cruzan: la clave de prueba solo ve notas fiscales, lotes, webhooks y eventos de prueba, y la de producción solo los de producción. La misma referencia y la misma Idempotency-Key se pueden usar en los dos.

Una empresa que emite por el sistema de la alcaldía no tiene entorno de pruebas: con la clave de prueba, la preparación trae el ítem sandbox_municipio_proprio en bloqueio, y la emisión se rechaza con 412 empresa_nao_pronta.

Pasar a producción

Crea una clave sdr_live_ en el panel. Las rutas y el JSON son los mismos: solo cambia la clave.
Consulta la preparación con la clave nueva (GET /v1/companies/{id}/prontidao). En producción también verifica el plan de Emisión (plano_emissao).
Registra el webhook de producción. El webhook creado con la clave de prueba solo recibe eventos de prueba.
Guarda X-Request-Id (o requisicao_id) en tus logs desde el primer día.

Guías

Empieza aquí: De la clave de prueba a la primera NFS-e autorizada, paso a paso, con curl, C# y Delphi.
Reglas de integración: Las doce reglas que evitan notas duplicadas, reintentos incorrectos y límites excedidos.
Recetas: Flujos completos: emitir una nota fiscal, emitir miles, sincronizar documentos, recibir webhooks y reintentar.
Idempotencia: Cómo Idempotency-Key y referencia evitan notas fiscales duplicadas, y cómo repetir una llamada con seguridad.
Errores y estados HTTP: Los dos formatos de error, qué significa cada status HTTP y el catálogo de códigos.
Estados de la NFS-e: Los 7 estados de una nota emitida, las transiciones, qué hacer en cada uno y el webhook correspondiente.
Preparación: Lo que la empresa necesita tener para emitir, ítem por ítem, y lo que bloquea la emisión.
Paginación y límites: Cursor de cada lista, límite de 120 solicitudes por minuto y tamaño máximo del cuerpo.
Emisión de NFS-e: Emitir, validar, consultar, cancelar y sustituir NFS-e, con ajustes automáticos por municipio.
Emisión por lotes: Hasta 5.000 notas fiscales en una llamada, por JSON u hoja de cálculo, con resultado y reprocesamiento por línea.
Documentos: NFS-e, NF-e y CT-e recibidos y emitidos por las empresas, con eventos y manifestaciones.
Cuenta: Datos de la cuenta y consumo del ciclo actual.
Empresas: Registro de CNPJs, certificado A1, pausa, eliminación y preparación para emitir.
Webhooks: Avisos firmados con HMAC, reintentos durante 72 horas, reenvío, cambio de secreto y verificación en 4 lenguajes.
Eventos: El log de eventos de la cuenta, por cursor, con 90 días de retención.
Simulador de fallos: Provoca timeout, rechazo, Sefin caída y falla de transmisión con la clave de prueba.
SDKs: SDK de TypeScript y PHP y qué cubre cada uno.
OpenAPI y Postman: La especificación OpenAPI en JSON y YAML, y cómo importarla en Postman o en Insomnia.
IA y MCP: Servidor MCP de solo lectura para asistentes de IA, y orientaciones para quien escribe un agente.
Problemas comunes: Qué hacer al recibir 401, 403, 404, 409, 412, 422, 429, un webhook que no llega y una nota fiscal detenida.
Glosario: Los términos fiscales y técnicos usados en esta documentación.
Registro de cambios: Qué cambió en la API y en la documentación, por fecha.

Rutas

Cuenta

GET /v1/account: Datos de la cuenta actual
GET /v1/usage: Consumo del ciclo de facturación actual

Empresas

GET /v1/companies: Lista las empresas de la cuenta
POST /v1/companies: Registra una empresa (CNPJ) para monitoreo
GET /v1/companies/{id}: Detalle de una empresa
DELETE /v1/companies/{id}: Solicita la eliminación de la empresa
GET /v1/companies/{id}/prontidao: Lo que le falta a la empresa para emitir
POST /v1/companies/{id}/certificate: Envía (o reemplaza) el certificado digital A1 de la empresa
POST /v1/companies/{id}/pause: Pausa el monitoreo de la empresa
POST /v1/companies/{id}/resume: Reanuda el monitoreo de la empresa

Emisión de NFS-e

GET /v1/servicos/{codigo}/nbs: NBS admitidos para un código de servicio
GET /v1/municipios/{ibge}/parametros: Convenio y parámetros oficiales de un municipio
GET /v1/nfse: Lista las NFS-e emitidas
POST /v1/nfse: Emite una NFS-e
POST /v1/nfse/validacoes: Valida una NFS-e sin emitirla
GET /v1/nfse/{id}: Consulta una NFS-e
GET /v1/nfse/{id}/xml: XML de la NFS-e
GET /v1/nfse/{id}/pdf: PDF (DANFSe) de la NFS-e
POST /v1/nfse/{id}/confirmacao: Confirma la transmisión de una nota fiscal que espera confirmación
POST /v1/nfse/{id}/cancelamento: Cancela una NFS-e autorizada

Documentos

GET /v1/documents: Lista notas fiscales
GET /v1/documents/{id}: Detalle de una nota fiscal

Emisión por lotes

GET /v1/lotes: Lista los lotes
POST /v1/lotes: Crea un lote de emisión
GET /v1/lotes/{id}: Consulta un lote
GET /v1/lotes/{id}/itens: Resultado por línea
GET /v1/lotes/{id}/relatorio: Informe en planilla
POST /v1/lotes/{id}/emissao: Manda emitir un lote que estaba en espera
POST /v1/lotes/{id}/reprocessamento: Corrige líneas y emite de nuevo

Webhooks

GET /v1/webhooks: Lista los webhooks del entorno de la clave
POST /v1/webhooks: Crea un webhook
GET /v1/webhooks/{id}: Un webhook
PATCH /v1/webhooks/{id}: Cambia eventos, dirección, estado activo o encabezados
DELETE /v1/webhooks/{id}: Elimina el webhook
POST /v1/webhooks/{id}/rotacao-segredo: Cambia el secreto, con 24 horas de convivencia
POST /v1/webhooks/{id}/teste: Envía un evento `webhook.teste` ahora
GET /v1/webhooks/{id}/entregas: Entregas del webhook, de las más nuevas a las más antiguas
POST /v1/webhooks/{id}/reenvio: Reenvía eventos (uno, un período o un lote)

Eventos

GET /v1/eventos: Log de eventos de la cuenta, por cursor