Idempotência

Todo endpoint de emissão aceita o header Idempotency-Key. Use-o em toda chamada de emissão feita por sistema (ERP, PDV, integração): é o que garante que um retry de rede não gere duas notas autorizadas para a mesma venda.

O problema que resolve

Quando o seu POST estoura o tempo (timeout), você não sabe se a nota foi criada ou não — o comportamento correto do seu lado é repetir a chamada. Sem chave de idempotência, a repetição aloca um novo número e autoriza uma segunda nota na SEFAZ. Com a chave, a repetição devolve a mesma nota da primeira tentativa.

Como usar

POST /api/v1/nfe
Authorization: Bearer {token}
Content-Type: application/json
Idempotency-Key: pedido-8842

• A chave é sua: qualquer string até 200 caracteres, estável por operação de negócio. Recomendação: derive do seu identificador interno (pedido-8842, venda:2026-08-06:117), não um UUID novo a cada tentativa.
• Alternativa sem header: envie referencia_externa no corpo do JSON — vale como a mesma coisa.
• O escopo é por empresa e por tipo de documento: a mesma chave pode existir em CNPJs ou documentos diferentes sem conflito.

O que acontece no retry

situação	resposta
1ª chamada	201/202 normal — a nota é criada
retry com a mesma chave	200 com a mesma nota e "idempotent_replay": true
retry enquanto a 1ª ainda processa	409 — repita em instantes com a mesma chave

Documentos síncronos e rejeição

NF-e, NFC-e, NFS-e municipal e CT-e são enfileirados (a resposta é o protocolo de processamento; acompanhe o status ou o webhook). MDF-e, BP-e, NFCom e NFS-e Nacional são síncronos — a resposta já traz o veredito do fisco.

Nos síncronos, só a autorização vira replay. Se o fisco rejeitar, a chave é liberada: corrija o payload e repita com a mesma chave — a nova tentativa é real. Rejeição não duplica nada; o risco que a idempotência elimina é a autorização em dobro.

Cobertura

Idempotency-Key funciona em todas as emissões: NF-e, NFC-e, NFS-e municipal, NFS-e Nacional, CT-e, MDF-e, BP-e e NFCom.