> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notasx.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotência

> Como repetir um pedido sem medo de emitir duas NFS-e.

Rede cai, timeouts acontecem. Se o seu `POST /v1/notas` não recebeu resposta, você não sabe se a Nota foi
criada. A **Chave de idempotência** resolve isso: repita o pedido com a mesma chave e receba a mesma Nota.

```http theme={null}
POST /v1/notas
Idempotency-Key: pedido-000123
```

## Regras

* **Obrigatória** em `POST /v1/notas`. Sem ela: `422 requisicao_invalida`.
* Até **255 caracteres**. Use algo que já identifica o pedido no seu sistema (o id da venda, do contrato,
  da fatura) ou um UUID que você grava antes de chamar a API.
* **Única por Conta e não expira.** A mesma chave, a qualquer momento, devolve a mesma Nota.
* Repetir a chave devolve a Nota **como ela está agora** (por exemplo, já `emitida`), com `202`.
* O **corpo do pedido repetido é ignorado.** Se você mudar o valor e repetir a chave, recebe a Nota original,
  com o valor original.

## Padrão recomendado

```python theme={null}
import uuid, httpx

chave = pedido.chave_idempotencia or str(uuid.uuid4())
pedido.salvar(chave_idempotencia=chave)          # grave ANTES de chamar a API

for tentativa in range(5):
    try:
        r = httpx.post(f"{NOTASX}/v1/notas", json=corpo, timeout=30,
                       headers={"Authorization": f"Bearer {CHAVE}", "Idempotency-Key": chave})
        break
    except httpx.TransportError:
        continue                                 # mesma chave: nunca cria outra Nota
```

## Quando usar uma chave nova

Quando a intenção é **outra emissão**: por exemplo, depois de `rejeitada` ou `falhou`, para corrigir os dados
e tentar de novo. Reaproveitar a chave antiga devolveria a Nota rejeitada.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.