Idempotência

Como evitar cobranças duplicadas ao fazer retries de requisições.

Por que usar

Redes são instáveis. Uma requisição POST pode falhar no meio do caminho — o servidor processou mas a resposta não chegou. Sem idempotência, um retry geraria uma segunda cobrança ou transferência. Com o header Idempotency-Key, a API detecta a repetição e devolve o resultado original sem reprocessar.

Como funciona

Inclua o header Idempotency-Key em toda requisição POST. Use um UUID v4 gerado pelo cliente para cada operação distinta. A API armazena a chave e o resultado por 24 horas no Redis. Requisições repetidas com a mesma chave dentro desse prazo recebem o resultado original com o header X-Idempotent-Replayed: true.

# Gerar UUID único por operação (bash)
IDEM_KEY=$(uuidgen)

# Usar na requisição
curl -s -X POST https://api.brpix.app/v1/pix/charges \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Idempotency-Key: $IDEM_KEY" \
  -d '{"amount":"50.00"}'

Resposta original vs replayed

# Primeira chamada — processada normalmente
HTTP/1.1 201 Created
X-Request-ID: req_abcd1234

{
  "id": "pix_c_9f8e7d6c",
  "status": "PENDING",
  "amount": "50.00000",
  "qr_code": "00020126..."
}

# Segunda chamada com a mesma Idempotency-Key — replayed
HTTP/1.1 201 Created
X-Idempotent-Replayed: true
X-Request-ID: req_efgh5678

{
  "id": "pix_c_9f8e7d6c",
  "status": "PENDING",
  "amount": "50.00000",
  "qr_code": "00020126..."
}

O resultado é idêntico ao original. Não importa quantas vezes você reenviar a mesma chave dentro de 24 horas — o recurso não é criado novamente.

TTL e renovação

A chave é armazenada por 24 horas a partir da primeira chamada bem-sucedida. Após esse prazo, a chave é liberada — uma nova requisição com o mesmo UUID seria processada normalmente (o que é improvável, mas tecnicamente possível se o UUID for reutilizado).

Recomendação: gere um novo UUID para cada operação de negócio. Nunca reutilize a mesma chave para operações distintas (ex: duas cobranças diferentes).

O que acontece se omitir o header

Comportamento indefinido em POSTs. Requisições POST sem Idempotency-Key podem resultar em duplicatas em caso de retry. O header é obrigatório em todos os endpoints POST financeiros da API. A ausência do header retorna 400 MISSING_IDEMPOTENCY_KEY.

Endpoints que exigem o header

Todos os endpoints POST que criam recursos financeiros:

POST /v1/pix/charges     — Gerar cobrança Pix
POST /v1/pix/transfers   — Iniciar transferência Pix Out

Endpoints GET, DELETE e o POST de autenticação não exigem o header.