Receitas

Fluxos completos para as tarefas mais comuns.

Emitir uma 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

O passo a passo com exemplos está em Sua primeira nota.

Emitir milhares de 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

Escolha ao_validar: emitir_validas (padrão) emite as linhas boas e deixa as ruins para corrigir; aguardar para depois da validação e só emite quando você chamar POST /v1/lotes/{id}/emissao, para quem quer tudo ou nada. Mande referencia em todo item. Detalhes em Emissão em lote.

Sincronizar documentos recebidos

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

Grave pelo id do documento, atualizando se ele já existe: assim tanto faz receber o mesmo documento pela carga inicial, pelo log e pelo webhook. Use uma chave sdr_live_: a chave de teste não lê documentos.

Receber webhooks sem perder nada

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>

O código de verificação em quatro linguagens está em Webhooks.

Retentativa

Situação	Repetir?	Como
Timeout, conexão caiu, nenhuma resposta	Sim	Mesma Idempotency-Key, mesmo corpo.
500 erro_interno, 502, 503, 504	Sim	Mesma Idempotency-Key, com espera crescente (1 s, 2 s, 4 s... até cerca de 1 minuto).
429	Sim	Depois da virada do minuto.
409 conflito	Sim	Alguns segundos depois, mesma Idempotency-Key: a primeira chamada ainda estava em andamento.
409 nfse_sem_pdf	Sim	Mais tarde: o PDF ainda não existe.
202 transmitindo	Não repita a emissão	Acompanhe por webhook ou GET /v1/nfse/{id}.
409 referencia_duplicada	Não	A nota já existe: consulte pelo nfse_id que veio no erro.
409 idempotencia_conflito	Não	O seu sistema usou a mesma chave para corpos diferentes: corrija isso.
422 nfse_rejeitada	Não	Corrija e emita uma nota nova, com outra referencia.
422 validacao, 412, 400, 401, 403, 404	Não	Corrija antes. Repetir dá o mesmo erro.
falha_transmissao com dps_enviada: "nao"	Sim, como nota nova	A nota não chegou ao Sistema Nacional. Emita de novo com outra referencia (a nota em falha continua registrada), ou, se veio de lote, use POST /v1/lotes/{id}/reprocessamento.
falha_transmissao com dps_enviada: "desconhecido"	Não, antes de conferir	A DPS pode ter virado nota. Confira no Emissor Nacional antes de emitir de novo.

A regra curta: repita o que vem com retentavel: true e os erros de rede, sempre com a MESMA Idempotency-Key. O resto, corrija antes.