Skip to main content
A Linka API suporta idempotencia para prevenir cobranças duplicadas causadas por retries de rede, timeouts ou bugs no cliente.

​
Como funciona

Envie o header Idempotency-Key com um UUID v4 único em requisicoes POST: 
curl -X POST https://api.linka.com/transactions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1000, "paymentMethod": "PIX", ...}'

​
Comportamento

CenárioResultado
Primeira requisicao com a keyProcessa normalmente, armazena resultado
Requisicao repetida com mesma keyRetorna o resultado armazenado (sem reprocessar)
Mesma key com body diferenteRetorna 409 Conflict

​
Endpoints que exigem Idempotency-Key

EndpointObrigatório
POST /transactionsSim
POST /withdrawalsSim
Demais endpoints POSTNão

​
Duracao

A chave de idempotencia e armazenada por 24 horas. Após esse período, a mesma key pode ser reutilizada.

​
Boas Práticas

Gere UUIDs v4 aleatorios para cada operação. Não use IDs sequenciais ou valores previsiveis.
Use o mesmo Idempotency-Key para retries da mesma operação. Gere um novo para cada operação distinta.
Se receber timeout ou erro de rede, repita a requisicao com o mesmo Idempotency-Key. Isso garante que o pagamento não sera duplicado.

​
Exemplo de retry seguro

async function createTransaction(payload, idempotencyKey, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch('https://api.linka.com/transactions', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer sk_live_...',
          'Idempotency-Key': idempotencyKey, // mesma key em todos os retries
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(payload),
      });
      return await response.json();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      await new Promise(r => setTimeout(r, 1000 * (attempt + 1))); // backoff
    }
  }
}