ConceitosIdempotência

Idempotência

Uma falha de rede no meio de uma emissão deixa a dúvida: a nota saiu ou não? Com a Idempotency-Key você repete a chamada sem risco de emitir a mesma nota duas vezes.

Como funciona

Em toda chamada de escrita, envie o cabeçalho Idempotency-Key com um valor único para aquela operação. A API guarda a chave e a resposta por 24 horas. Se a mesma chave chegar de novo nesse período, você recebe a resposta original e nada é executado outra vez.

Requisição
curl -X POST https://api.emissordenota.com/v1/nfse \  -H "Authorization: Bearer $EDN_KEY" \  -H "Idempotency-Key: fatura-2026-11-0042" \  -H "Content-Type: application/json" \  -d @nota.json

A resposta repetida vem com o cabeçalho Idempotency-Replayed: true, para o seu sistema distinguir a repetição da primeira chamada.

Escolhendo a chave

Use um identificador que já existe no seu sistema e representa a operação, como o número da fatura ou do pedido. Assim a chave é a mesma em toda tentativa, mesmo que o seu processo reinicie no meio do caminho. A chave aceita até 255 caracteres.

ExemploPor quê

  • Bomfatura-2026-11-0042
    Vem do seu banco de dados e é igual em toda tentativa.
  • Bom3f1c9a52-7e0b-4c1d-9a44-2b8f6d0e5a17
    Um UUID funciona, desde que seja gravado antes da primeira tentativa e reutilizado nas seguintes.
  • RuimDate.now()
    Muda a cada tentativa, então cada repetição vira uma operação nova.

O que acontece em cada caso

SituaçãoResposta

  • Mesma chave e mesmo corpo, com a primeira chamada concluída com sucesso
    A resposta original, com o mesmo status e o mesmo corpo. Nada é executado de novo.
  • Mesma chave, com a primeira chamada ainda em andamento
    409 com o código requisicao_em_andamento. Espere alguns segundos e repita.
  • Mesma chave, com a primeira chamada recusada com erro 4xx (dados inválidos, chave de API recusada, limite excedido)
    Nada foi executado e a chave não fica guardada. Corrija o problema e repita com a mesma chave, mesmo que o corpo mude.
  • Mesma chave, com a primeira chamada terminada em erro 5xx
    O erro não fica guardado. Repita com a mesma chave: se a operação chegou a ser concluída, você recebe a resposta original. Se não, ela é executada agora.
  • Mesma chave, sem ter recebido resposta da primeira chamada (timeout ou queda de conexão)
    Repita com a mesma chave. Você recebe a resposta original, um 409 requisicao_em_andamento ou a operação é executada pela primeira vez. Em nenhum caso ela roda duas vezes.
  • Mesma chave, depois de a nota ter sido aceita pela API e rejeitada pela prefeitura
    A resposta original, que aponta para a nota rejeitada. A chamada em si deu certo, então a chave continua valendo. Para emitir a versão corrigida, use uma chave nova.
  • Mesma chave com outro corpo, depois de uma chamada aceita
    409 com o código idempotencia_em_conflito. Use uma chave nova para a nova operação.
  • Mesma chave em outro ambiente
    Sandbox e produção não compartilham chaves. A chamada é tratada como nova.
  • Chave enviada há mais de 24 horas
    A chamada é tratada como nova.

Onde usar

MétodoPrecisa da chave?
POSTSim, em toda criação ou ação: emitir, cancelar, substituir, cadastrar e atualizar.
GETNão. Consultas podem ser repetidas à vontade.
DELETENão. Remover o que já foi removido responde 404 e não causa efeito.

A chave expira em 24 horas

Para conferir se uma nota mais antiga já foi emitida, envie o campo referencia na emissão e, antes de repetir, liste as notas da empresa filtrando por essa referência.