Sudrel API
Dashboard Create API key

Documentation › First steps

Guides

Integration rules

The twelve rules that prevent duplicate invoices, wrong retries and exceeded limits.

Twelve rules. Each one prevents a real integration problem.

  1. Send Idempotency-Key in POST /v1/nfse and POST /v1/lotes. It is not required, but without it a timeout followed by a retry can create a second invoice. See Idempotency.
  2. When you repeat the same attempt, use the SAME Idempotency-Key. Generate one per invoice, store it with the order and reuse it. A new key is a new invoice.
  3. Send referencia in every invoice (your order number, for example). It is unique per company and environment: a second invoice with the same referencia is refused (409 referencia_duplicada). This protection still applies after the 30 days the Idempotency-Key is kept.
  4. 202 is not an error. The invoice exists and is transmitindo. Track it; do not issue again.
  5. In production, prefer a webhook to repeated queries. Subscribe to NFSE_AUTORIZADA, NFSE_REJEITADA and NFSE_FALHA_TRANSMISSAO.
  6. If you query, do not query too often. The limit is 120 requests per minute per key, and an invoice in transmitindo does not change every second. One query every 30 seconds per invoice is enough.
  7. Money and tax rates go as text with a decimal point: "1500.00", "2". A JSON number is refused (tipo_invalido).
  8. Code against codigo, never against mensagem. The message is for people and its text can change; codigo is stable.
  9. Store X-Request-Id (or requisicao_id) of every call that failed. With it you find the call in Integrações › Log da API (Integrations › API log).
  10. Treat the cursor as an opaque value. Store it and send it back exactly as it came, without interpreting or building it. See Pagination and limits.
  11. Retry only what can succeed when repeated. Retry when the error has retentavel: true, on 429, 5xx and timeout, always with the same Idempotency-Key. Do not retry 400, 401, 403, 404, 409, 412 or 422 without fixing first. See the retry recipe.
  12. On falha_transmissao, read falha.dps_enviada before issuing again. With "desconhecido", the invoice may have been issued: check in the Emissor Nacional first.