Pular para o conteúdo
Fundamentos

Idempotência

Repita uma requisição com segurança: a mesma chave nunca gera duas cobranças, dois estornos ou duas transferências.

Como funciona

  • Envie o cabeçalho Idempotency-Key (até 120 caracteres) — use o ID do seu pedido ou um UUID.
  • Mesma chave + mesmo corpo → a resposta original é devolvida, com o cabeçalho idempotent-replayed: true. Nada é executado de novo.
  • Mesma chave + corpo diferente → 422 IDEMPOTENCY_MISMATCH.
  • Primeira requisição ainda em andamento → 409 IDEMPOTENCY_IN_PROGRESS. Aguarde e repita.
  • Se a primeira tentativa falhar antes de concluir, a chave é liberada para nova tentativa.
  • A chave vale por empresa, ambiente e rota.
Repetir após timeout de rede
curl -X POST https://api2.bosspay.io/v1/transactions/TX_ID/refund \
  -H "Authorization: Bearer bp_live_SUA_CHAVE" \
  -H "Idempotency-Key: estorno-pedido-1042" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "5000", "reason": "Item devolvido" }'

Endpoints que aceitam Idempotency-Key