Idempotência

Repita uma criação sem duplicar nada, pelo idempotencyKey das vendas ou pelo cabeçalho Idempotency-Key das outras rotas.

Rede cai, servidor reinicia, a resposta se perde. Para repetir uma criação sem criar duas vezes, mande uma chave de idempotência: um texto seu, único por operação (o número do pedido serve bem).

Existem dois jeitos, conforme a rota:

Nas vendas

{ "method": "pix", "currency": "BRL", "amountCents": 15000, "idempotencyKey": "pedido-42", "payer": { … } }

• A primeira chamada cria a venda e responde 201.
• Repetir com o mesmo idempotencyKey devolve a venda original com 200 e "replayed": true. Nada novo é criado nem cobrado, mesmo que o corpo seja diferente: o que vale é a chave.
• A chave é única por conta. Usada numa venda de outra loja da mesma conta, a resposta é 409.

Nas outras rotas

curl -X POST https://api.confidoscm.com/api/v1/charges \
  -H "X-API-Key: $CONFIDO_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-43" \
  -d '{ "amountCents": 25000, "method": "pix", "dueDate": "2026-12-01", "customer": { "name": "Joana", "email": "joana@exemplo.com" } }'

• Repetir com a mesma chave e o mesmo corpo devolve a mesma resposta (mesmo status, mesmo corpo), com o cabeçalho Idempotent-Replayed: true.
• A mesma chave com outro corpo responde 409 idempotency_key_reused.
• Se a primeira chamada ainda está rodando, a repetição responde 409 idempotency_request_in_progress: espere um pouco e repita.
• Se a primeira chamada falhou, a chave é liberada e a repetição tenta de novo.
• A chave conta o método, o caminho, o corpo e o Confido-Account.

Quando repetir

Uma venda nova é uma chave nova. Reaproveitar a chave de um pedido anterior devolve a venda daquele pedido. Pelo mesmo motivo, para tentar de novo uma venda que voltou declined ou failed, use uma chave nova (pedido-42-tentativa-2).