Idempotência
Operações que criam recursos ou movimentam dinheiro exigem o cabeçalho Idempotency-Key (8 a 128 caracteres: letras, números, _, -, : e .). São elas: cadastrar jogador, registrar envio de KYC, criar/confirmar/falhar depósito, solicitar/cancelar saque.
- Gere uma chave única por intenção (por exemplo, um UUID por depósito) e guarde-a junto do pedido no seu sistema.
- Repetir a mesma requisição com a mesma chave devolve a resposta original, sem repetir o efeito, e a resposta traz
Idempotent-Replayed: true. - Reutilizar a chave com corpo ou caminho diferente retorna
409 IDEMPOTENCY_CONFLICT. - Se a primeira requisição ainda estiver em andamento, retorna
409 IDEMPOTENCY_IN_PROGRESS: aguarde e tente de novo. - As chaves são lembradas por 24 horas e valem por operador.
- Em caso de timeout ou erro
5xx, repita com a mesma chave; nunca gere uma nova para a mesma intenção. Falhas5xxliberam a chave para nova tentativa. - Respostas de erro de validação (
4xx) também são guardadas: corrija o pedido e use uma nova chave.
Além da chave HTTP, alguns recursos têm identificadores naturais de deduplicação: o externalId do jogador é único por marca e a externalReference de um depósito é única por operador (409 com o id do recurso existente).
Cancelamentos e reversões
Nada registrado é apagado: correções geram novos lançamentos e ficam na trilha de auditoria.
- Depósito não concretizado:
POST /deposits/{depositId}/fail(só enquantopending). Depois de confirmado, um depósito não pode ser desfeito pela API. - Saque:
POST /withdrawals/{withdrawalId}/cancelenquanto estiver em análise. Depois de aprovado, o cancelamento retorna409 WITHDRAWAL_NOT_CANCELLABLE. - Estornos e ajustes na carteira (por exemplo, reversão de um depósito confirmado) são operações da equipe no backoffice, com motivo e aprovação. Fale com a equipe quando precisar de uma.