Idempotência

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

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