Skip to main content

​
O que é Idempotência?

Idempotência garante que uma operação executada múltiplas vezes produza o mesmo resultado que executada uma única vez. Na prática, isso evita cobranças ou saques duplicados em caso de falha de rede ou timeout.

​
Como Usar

Adicione o header X-Idempotency-Key com um identificador único por operação: 
POST /v1/charges
Authorization: Bearer flare_xxx
Content-Type: application/json
X-Idempotency-Key: pedido-1234-usuario-5678

​
Comportamento

  • Se a requisição for bem-sucedida, a resposta é armazenada por 24 horas
  • Requisições subsequentes com a mesma chave retornam a resposta original (sem criar um novo recurso)
  • Se a requisição original falhou, a operação é tentada novamente
O header é opcional, mas altamente recomendado para operações financeiras críticas como cobranças e saques.

​
Endpoints que suportam Idempotência

EndpointSuporte
POST /v1/charges✓ Sim
POST /v1/withdrawals✓ Sim
Endpoints GETNão necessário (já são idempotentes por natureza)

​
Boas Práticas para a Chave

// Use uma combinação de IDs únicos do seu sistema
const idempotencyKey = `charge-${orderId}-${userId}-${Date.now()}`;

// Ou use UUID
import { randomUUID } from 'crypto';
const idempotencyKey = randomUUID();
Nunca reutilize a mesma X-Idempotency-Key para operações diferentes. Cada operação distinta deve ter sua própria chave.