Recipes

Complete flows for the most common tasks.

Issue an NFS-e

1. GET  /v1/companies/{id}/prontidao        -> sem bloqueio? siga
2. POST /v1/nfse/validacoes                 -> valida: true? siga
3. POST /v1/nfse  (Idempotency-Key + referencia)
4. 201 -> pronto | 202 -> passo 5 | 422 -> corrigir
5. webhook NFSE_AUTORIZADA / NFSE_REJEITADA, ou GET /v1/nfse/{referencia}
6. GET  /v1/nfse/{id}/pdf e /xml

The step-by-step guide with examples is in Your first invoice.

Issue thousands of NFS-e

1. POST /v1/lotes  { empresa_id, ao_validar, itens: [ { referencia, ... } ] }   -> 202
2. webhook LOTE_EMISSAO_CONCLUIDO, ou GET /v1/lotes/{id} até status "concluido"
3. GET  /v1/lotes/{id}/itens?status=rejeitada   (e com_erro_validacao)
4. POST /v1/lotes/{id}/reprocessamento   { itens: [ { linha, campos } ] }
5. GET  /v1/lotes/{id}/relatorio         -> a planilha com o resultado de cada linha

Choose ao_validar: emitir_validas (default) issues the good rows and leaves the bad ones for you to fix; aguardar stops after validation and issues only when you call POST /v1/lotes/{id}/emissao, for all-or-nothing cases. Send referencia in every item. Details in Batch issuance.

Sync received documents

Carga inicial:
1. GET /v1/documents?limite=100, seguindo proximoCursor até vir nulo
2. para o detalhe e o XML: GET /v1/documents/{id}

Daqui em diante:
3. GET /v1/eventos?tipos=NOTA_RECEBIDA,NFE_RECEBIDA,CTE_RECEBIDA,EVENTO_FISCAL_RECEBIDO
4. para cada evento: GET /v1/documents/{recurso.id}, e grave pelo id (atualiza se já existe)
5. guarde o proximo_cursor e, na próxima rodada, leia com ?apos=<cursor>
6. opcional: webhook com os mesmos tipos, para saber na hora; o log cobre o que o webhook perder

Store by the document id, updating it if it already exists: this way it does not matter whether you get the same document from the initial load, the log or the webhook. Use a sdr_live_ key: the test key does not read documents.

Receive webhooks without losing anything

1. POST /v1/webhooks  { url, eventos }        -> guarde o segredo
2. a cada entrega: confira X-Sudrel-Signature-V2, responda 2xx em até 10 s
3. deduplique por X-Sudrel-Event-Id
4. depois de uma queda sua: GET /v1/eventos?apos=<último cursor guardado>

The verification code in four languages is in Webhooks.

Retry

Situation	Retry?	How
Timeout, dropped connection, no response	Yes	Same Idempotency-Key, same body.
500 erro_interno, 502, 503, 504	Yes	Same Idempotency-Key, with increasing wait (1 s, 2 s, 4 s... up to about 1 minute).
429	Yes	After the minute turns over.
409 conflito	Yes	A few seconds later, same Idempotency-Key: the first call was still in progress.
409 nfse_sem_pdf	Yes	Later: the PDF does not exist yet.
202 transmitindo	Do not repeat the issuance	Track it by webhook or GET /v1/nfse/{id}.
409 referencia_duplicada	No	The invoice already exists: query it by the nfse_id returned in the error.
409 idempotencia_conflito	No	Your system used the same key for different bodies: fix this.
422 nfse_rejeitada	No	Fix it and issue a new invoice, with a different referencia.
422 validacao, 412, 400, 401, 403, 404	No	Fix it first. Repeating gives the same error.
falha_transmissao with dps_enviada: "nao"	Yes, as a new invoice	The invoice did not reach the Sistema Nacional. Issue again with a different referencia (the failed invoice stays recorded), or, if it came from a batch, use POST /v1/lotes/{id}/reprocessamento.
falha_transmissao with dps_enviada: "desconhecido"	No, not before checking	The DPS may have become an invoice. Check in the Emissor Nacional before issuing again.

The short rule: retry what comes with retentavel: true and network errors, always with the SAME Idempotency-Key. For everything else, fix it first.