Recetas

Flujos completos para las tareas más comunes.

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

El paso a paso con ejemplos está en Tu primera nota fiscal.

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

Elige ao_validar: emitir_validas (predeterminado) emite las líneas buenas y deja las malas para corregir; aguardar se detiene después de la validación y solo emite cuando llamas a POST /v1/lotes/{id}/emissao, para quien quiere todo o nada. Envía referencia en cada ítem. Detalles en Emisión por lotes.

Sincronizar documentos recibidos

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

Guarda por el id del documento y actualiza si ya existe: así da igual recibir el mismo documento por la carga inicial, por el registro de eventos y por el webhook. Usa una clave sdr_live_: la clave de prueba no lee documentos.

Recibir webhooks sin 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>

El código de verificación en cuatro lenguajes está en Webhooks.

Reintento

Situación	¿Repetir?	Cómo
Timeout, conexión caída, ninguna respuesta	Sí	Misma Idempotency-Key, mismo cuerpo.
500 erro_interno, 502, 503, 504	Sí	Misma Idempotency-Key, con espera creciente (1 s, 2 s, 4 s... hasta cerca de 1 minuto).
429	Sí	Después del cambio de minuto.
409 conflito	Sí	Unos segundos después, misma Idempotency-Key: la primera llamada todavía estaba en curso.
409 nfse_sem_pdf	Sí	Más tarde: el PDF todavía no existe.
202 transmitindo	No repitas la emisión	Haz el seguimiento por webhook o GET /v1/nfse/{id}.
409 referencia_duplicada	No	La nota fiscal ya existe: consúltala por el nfse_id que vino en el error.
409 idempotencia_conflito	No	Tu sistema usó la misma clave para cuerpos diferentes: corrige eso.
422 nfse_rejeitada	No	Corrige y emite una nota fiscal nueva, con otra referencia.
422 validacao, 412, 400, 401, 403, 404	No	Corrige antes. Repetir da el mismo error.
falha_transmissao con dps_enviada: "nao"	Sí, como nota fiscal nueva	La nota fiscal no llegó al Sistema Nacional. Emite de nuevo con otra referencia (la nota fiscal con fallo sigue registrada), o, si vino de un lote, usa POST /v1/lotes/{id}/reprocessamento.
falha_transmissao con dps_enviada: "desconhecido"	No, antes de verificar	La DPS puede haberse convertido en nota fiscal. Verifica en el Emissor Nacional antes de emitir de nuevo.

La regla corta: repite lo que viene con retentavel: true y los errores de red, siempre con la MISMA Idempotency-Key. Lo demás, corrígelo antes.