Skip to main content

​
O que e idempotencia?

Idempotencia garante que uma mesma requisicao, executada multiplas vezes, produz o mesmo resultado. Isso e fundamental em pagamentos para evitar cobracas duplicadas em caso de timeout, retry ou falha de rede.

​
Como usar

Inclua o header Idempotency-Key com um UUID v4 unico em toda requisicao de criacao: 
curl -X POST https://api.thalbank.com/transactions \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "x-api-key: sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1500, "method": "PIX", ... }'

​
Endpoints que exigem Idempotency-Key

EndpointObrigatorio
POST /transactionsSim
POST /withdrawalsSim
Demais endpointsNao

​
Comportamento

CenarioO que acontece
Primeira requisicao com a keyProcessada normalmente
Mesma key, mesmo bodyRetorna o resultado da primeira requisicao (sem reprocessar)
Mesma key, body diferenteRetorna erro 409 Conflict
Key ausente (onde obrigatorio)Retorna erro 400 Bad Request

​
Boas praticas

1

Gere a key no seu sistema

Use UUID v4 gerado no seu backend antes de enviar a requisicao. Isso garante que retries usem a mesma key.
2

Associe a key ao pedido

Vincule a Idempotency-Key ao ID do pedido no seu sistema. Se precisar reenviar, use a mesma key.
3

Nunca reutilize keys entre pedidos diferentes

Cada pedido/transacao deve ter sua propria key unica.

​
Exemplo com retry

const idempotencyKey = crypto.randomUUID(); // gere UMA vez

async function createTransaction(data, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await fetch("https://api.thalbank.com/transactions", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "x-api-key": process.env.THALPAY_API_KEY,
          "Idempotency-Key": idempotencyKey, // mesma key em todos os retries
        },
        body: JSON.stringify(data),
      });
      return await response.json();
    } catch (err) {
      if (i === retries - 1) throw err;
    }
  }
}