Sudrel API
Panel Crear clave de API

Documentación › Primeros pasos

Guías

Reglas de integración

Las doce reglas que evitan notas duplicadas, reintentos incorrectos y límites excedidos.

Doce reglas. Cada una evita un problema real de integración.

  1. Envía Idempotency-Key en POST /v1/nfse y POST /v1/lotes. No es obligatorio, pero sin él un timeout seguido de un reintento puede crear una segunda nota fiscal. Consulta Idempotencia.
  2. Al repetir el mismo intento, usa la MISMA Idempotency-Key. Genera una por nota fiscal, guárdala junto al pedido y reutilízala. Clave nueva es nota fiscal nueva.
  3. Envía referencia en cada nota fiscal (el número de tu pedido, por ejemplo). Es única por empresa y entorno: una segunda nota fiscal con la misma referencia se rechaza (409 referencia_duplicada). Es la protección que sigue valiendo después de los 30 días en que se guarda la Idempotency-Key.
  4. 202 no es un error. La nota fiscal existe y está transmitindo. Haz el seguimiento; no emitas de nuevo.
  5. En producción, prefiere el webhook a la consulta repetida. Suscríbete a NFSE_AUTORIZADA, NFSE_REJEITADA y NFSE_FALHA_TRANSMISSAO.
  6. Si consultas, consulta sin prisa. El límite es de 120 solicitudes por minuto por clave, y la nota fiscal en transmitindo no cambia cada segundo. Una consulta cada 30 segundos por nota fiscal es suficiente.
  7. Los montos y las alícuotas van como texto con punto decimal: "1500.00", "2". Un número JSON se rechaza (tipo_invalido).
  8. Programa sobre codigo, nunca sobre mensagem. El mensaje es para personas y su texto puede cambiar; el codigo es estable.
  9. Guarda X-Request-Id (o requisicao_id) de cada llamada que falló. Con él encuentras la llamada en Integrações › Log da API (Integraciones › Registro de la API).
  10. Trata el cursor como valor opaco. Guárdalo y devuélvelo exactamente como vino, sin interpretarlo ni armarlo. Consulta Paginación y límites.
  11. Repite solo lo que puede salir bien al repetirse. Repite cuando el error trae retentavel: true, en 429, 5xx y timeout, siempre con la misma Idempotency-Key. No repitas 400, 401, 403, 404, 409, 412 ni 422 sin corregir antes. Consulta la receta de reintento.
  12. Ante falha_transmissao, lee falha.dps_enviada antes de emitir de nuevo. Con "desconhecido", la nota fiscal puede haberse emitido: verifica primero en el Emissor Nacional.