---
title: "Idempotência"
description: "Use o cabeçalho Idempotency-Key para repetir chamadas de escrita na API sem emitir a mesma NFS-e duas vezes: como funciona, como escolher a chave e cada caso."
url: https://docs.emissordenota.com/idempotencia
language: pt-BR
---
# 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**

```bash
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.

|   | Exemplo | Por quê |
| --- | --- | --- |
| Bom | fatura-2026-11-0042 | Vem do seu banco de dados e é igual em toda tentativa. |
| Bom | 3f1c9a52-7e0b-4c1d-9a44-2b8f6d0e5a17 | Um UUID funciona, desde que seja gravado antes da primeira tentativa e reutilizado nas seguintes. |
| Ruim | Date.now() | Muda a cada tentativa, então cada repetição vira uma operação nova. |

## O que acontece em cada caso

| Situação | Resposta |
| --- | --- |
| 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é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**
>
> 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.
