Atendimento

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 /nfseEmissão de NFS-e
POST /nfse/{id}/substituicaoNFS-e substituta
POST /nfeEmissão de NF-e
POST /nfceEmissã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, com campos[0].campo = "Idempotency-Key".

O que acontece ao repetir

SituaçãoResposta
Chave nova202 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 corpo409 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 5xx ou timeout, repita com a mesma chave. Se o documento tiver sido criado, ele volta com 200.

Outras rotas

Cancelamento, carta de correção, inutilização e cadastros não usam Idempotency-Key:

  • cancelamento de nota já cancelada devolve a nota CANCELADA de novo (idempotente por natureza);
  • cadastro duplicado responde 409 (emitente-duplicado, cliente-duplicado, mercadoria-duplicada).

Nesta página