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.
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.jsonA 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-0042Vem do seu banco de dados e é igual em toda tentativa.
- Bom3f1c9a52-7e0b-4c1d-9a44-2b8f6d0e5a17Um 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 sucessoA resposta original, com o mesmo status e o mesmo corpo. Nada é executado de novo.
- Mesma chave, com a primeira chamada ainda em andamento409 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 5xxO 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 prefeituraA 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 aceita409 com o código idempotencia_em_conflito. Use uma chave nova para a nova operação.
- Mesma chave em outro ambienteSandbox e produção não compartilham chaves. A chamada é tratada como nova.
- Chave enviada há mais de 24 horasA chamada é tratada como nova.
Onde usar
| Método | Precisa da chave? |
|---|---|
| POST | Sim, em toda criação ou ação: emitir, cancelar, substituir, cadastrar e atualizar. |
| GET | Não. Consultas podem ser repetidas à vontade. |
| DELETE | Não. Remover o que já foi removido responde 404 e não causa efeito. |
A chave expira em 24 horas