Recursos

Idempotency-Key

Garante que retries de uma mesma operação não dupliquem o resultado. Crítico pra PIX — você não quer mandar dinheiro 2x por causa de um timeout de rede.

O problema

Você manda POST /v1/withdrawals de R$ 1.000. O timeout estoura, mas o servidor pode ter processado normalmente. Você tenta de novo. Sem idempotency = 2 PIX de R$ 1.000.

A solução

Você manda um header Idempotency-Key com uma string única por operação. Se enviar duas requests com a mesma key:

• Mesmo body → retorna a resposta da 1ª request (sem duplicar)
• Body diferente → retorna 409 IDEMPOTENCY_KEY_CONFLICT

Exemplo

# 1ª request — cria o PIX
curl -X POST https://api.realfy.io/v1/withdrawals \
  -H "X-Api-Key: rfy_live_..." \
  -H "X-Api-Secret: ..." \
  -H "Idempotency-Key: tx-9182" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100, "pixKey": "..."}'

# 2ª request (retry — mesma key, mesmo body)
# Retorna a MESMA resposta + header "Idempotency-Replayed: true"
# Nada é duplicado no servidor.

import { randomUUID } from 'crypto';

async function createWithdrawal(amount, pixKey) {
  // Gera uma key única por transação. Salve junto do registro no seu DB
  // pra reusar em caso de retry.
  const idempotencyKey = `tx-${randomUUID()}`;

  const response = await fetch('https://api.realfy.io/v1/withdrawals', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.REALFY_API_KEY,
      'X-Api-Secret': process.env.REALFY_API_SECRET,
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey,
    },
    body: JSON.stringify({ amount, pixKey }),
  });

  return response.json();
}

Boas práticas

• Gere a key antes de chamar a API e persista no seu DB. Em caso de retry, leia do DB e reuse.
• Use uma key diferente por operação (UUID v4 é seguro). Reusar a mesma key com body diferente gera erro 409.
• Aplique idempotency em todos os POSTs financeiros: /deposits e /withdrawals.
• Para GETs (consulta de saldo, lista de transações) o header é ignorado — GETs são naturalmente idempotentes.

Identificando uma response replayed

Quando a request é cached, a resposta vem com o header:

Idempotency-Replayed: true

Útil pra você logar diferente no seu sistema (era retry, não criou nada novo). HTTP status code e body são idênticos ao da 1ª request.

Escopo

Idempotency-Keys são escopadas pela API key. Cliente A com tx-001 não colide com Cliente B usando a mesma tx-001 — namespaces independentes.

Limites