Idempotência

Repita requisições com segurança, sem cobrar nem sacar em dobro.

Rede falha, e às vezes você não sabe se a API recebeu seu pedido. Envie o cabeçalho Idempotency-Key com um valor único por operação: repetir a requisição devolve o recurso original, sem criar outro.

Rota	Idempotency-Key
`POST /v1/payouts`	Obrigatória
`POST /v1/crypto/payouts`	Obrigatória
`POST /v1/charges`	Opcional, recomendada

Requisição com chave

curl -X POST "https://api.sacipix.com/v1/payouts" \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Idempotency-Key: saque-fornecedor-77" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "pixKey": "financeiro@example.com",
    "pixKeyType": "email"
  }'

Como funciona

A chave tem até 200 caracteres e vale por conta e por ambiente, sem expiração.
Use um valor do seu domínio, como o id do pedido. Um UUID gerado antes da primeira tentativa também serve.
Mesma chave e mesmos parâmetros devolvem o recurso existente, com o mesmo status HTTP da criação.
Mesma chave com parâmetros diferentes devolve 409 idempotency_conflict.
Em cobranças, enquanto a primeira requisição não termina, as repetições recebem 409 idempotency_in_progress.
Saque recusado por saldo insuficiente não consome a chave: depois de receber saldo, a mesma chave pode ser usada.
Cobrança que falhou na criação libera a chave. Repetir a requisição gera uma cobrança nova.