Idempotência
Idempotency-Key obrigatória em toda emissão, para um retry nunca emitir duas notas.
Toda chamada que emite um documento exige o header Idempotency-Key:
| Rota | |
|---|---|
POST /nfse | Emissão de NFS-e |
POST /nfse/{id}/substituicao | NFS-e substituta |
POST /nfe | Emissão de NF-e |
POST /nfce | Emissão de NFC-e |
Idempotency-Key: 3f1c2b9e-5a7d-4c1e-9b2f-8d6a0e4c7b21- De 1 a 100 caracteres ASCII visíveis. Recomendado: um UUID novo por documento, gravado no seu sistema junto do pedido que gerou a nota.
- Ausente ou inválida:
400 requisicao-invalida, comcampos[0].campo = "Idempotency-Key".
O que acontece ao repetir
| Situação | Resposta |
|---|---|
| Chave nova | 202 Accepted + Location, documento novo em PENDENTE |
| Mesma chave e mesmo corpo (ex.: retry após timeout) | 200 OK + Idempotent-Replayed: true, o mesmo documento e o mesmo Location, sem nova transmissão |
| Mesma chave e outro corpo | 409 idempotency-conflito |
Assim, se a sua chamada estourar o timeout ou a conexão cair, repita com a mesma chave: ou a nota já existe e volta como estava, ou é criada agora. Nunca há duas notas para o mesmo pedido.
Depois de um erro 5xx ou 429
429(rate limit) e erros de autenticação são barrados antes do processamento: a chave ainda não foi usada. Repita depois com a mesma chave.- Num
5xxou timeout, repita com a mesma chave. Se o documento tiver sido criado, ele volta com200.
Outras rotas
Cancelamento, carta de correção, inutilização e cadastros não usam Idempotency-Key:
- cancelamento de nota já cancelada devolve a nota
CANCELADAde novo (idempotente por natureza); - cadastro duplicado responde
409(emitente-duplicado,cliente-duplicado,mercadoria-duplicada).