Idempotência
Rede cai, timeout acontece. Há duas formas de repetir um pedido sem emitir em dobro:
id_externoO id do pedido no seu sistema, único por empresa. Mandar o mesmo
id_externo na mesma empresa devolve a nota já criada (200) em vez de criar outra.Idempotency-KeyHeader aceito em qualquer POST, até 255 caracteres. Repetir o pedido com a mesma chave devolve a mesma resposta por 24 h, com o header
Idempotent-Replayed: true.Usar a mesma Idempotency-Key com outro corpo dá 422 idempotency_key_reutilizada; repetir enquanto o primeiro pedido ainda está rodando dá 409 pedido_em_andamento.
Em lote, repetir é seguro com id_externo em cada nota. E reprocessar também é seguro: se a tentativa anterior chegou à SEFIN, o motor recupera a nota em vez de enviar de novo.
POST /v1/nfse Idempotency-Key: 6f1c2b9e-4d1a-4a8e-9c1f-2b7d8e0a1c3f