Limites do jogador e saldos

Para: Dev, Fin — Conferido em 2026-10-18.

Duas leituras: GET /v1/players/{external_ref}/limits mostra a posição de um jogador perante as regras de saque automático, e GET /v1/balances mostra o caixa de liquidação da sua operação por moeda. Esta página descreve a forma das respostas. O significado financeiro (o que entra no caixa, o que é caixa livre, como o multiplicador age) está em Saldos e caixa livre e em Decisão, limites e regras.

O que é

Rota Escopo operationId O que devolve
GET /v1/players/{external_ref}/limits?currency= read limitesDoJogador LimitesJogador: totais do jogador, multiplicador e o que ainda cabe no automático
GET /v1/balances read saldosDaOperacao {"data": [...]} com um item por moeda habilitada

As duas são somente leitura e não têm efeito colateral.

Quando usar

  • Avisar o jogador antes do pedido. Use auto_withdrawal_remaining para dizer "até R$ X sai na hora". É uma estimativa: outras regras (primeiro saque, chave nova, janelas, saque sem player.ip) ainda podem mandar o saque para revisão.
  • Decidir se oferece o saque. blocked: true indica que o jogador está numa lista de bloqueio.
  • Monitorar o caixa. Alerte quando o caixa livre se aproximar do valor dos saques que você espera. Um saque sem caixa recebe 422 insufficient_operation_balance na criação, ou fica em approved se o caixa faltar só no envio.
  • Reconciliar. Os saldos servem para acompanhamento. A prova diária está em Reconciliação.

Como funciona

GET /v1/players/{external_ref}/limits

O caminho leva o external_ref do jogador (^[A-Za-z0-9_.:-]{1,64}$) e a query leva currency, que é obrigatório. A API confere nesta ordem:

  1. external_ref fora do formato: 400 validation_failed com field: external_ref e reason: format.
  2. currency ausente: 400 com field: currency e reason: required.
  3. Moeda não habilitada na operação: 400 currency_not_enabled.
  4. Jogador que nunca transacionou nesta operação: 404 not_found. Jogador de outra operação também é 404: a API nunca confirma a existência.
  5. Motor de regras fora: 503 service_unavailable, repetível.

Resposta 200, objeto LimitesJogador:

Campo Tipo Conteúdo
player_ref texto o external_ref pedido
currency texto a moeda pedida
total_deposited Money total depositado pelo jogador e liquidado pelo Dracma, na moeda, conforme a regra da operação
total_withdrawn Money total de saques do jogador, contado pela regra da operação
auto_multiplier texto o multiplicador X da regra, decimal em texto ("1", "1.5"). "0" desliga o automático
auto_withdrawal_remaining Money quanto ainda cabe no saque automático pela regra do multiplicador
blocked booleano true quando o jogador ou o documento dele está em lista de bloqueio

As janelas internas de consumo e a versão do conjunto de regras que o motor calcula não são devolvidas.

GET /v1/balances

Resposta 200 com {"data": [Saldo, ...]}, uma entrada por moeda habilitada, ordenadas pelo código da moeda. Cada entrada tem:

Campo Tipo Conteúdo
available Money o caixa da operação no livro do Dracma. Inclui o que já está reservado para saques em curso
pending_in Money dinheiro já recebido e ainda não creditado: depósitos em revisão (e nos estados de retenção, que não ocorrem em PIX hoje). Vem do valor pago, ou do pedido se não houver
pending_out Money o que está reservado para saques em curso, e que continua dentro de available
as_of texto instante da leitura, RFC 3339 em UTC
  • A moeda não aparece como campo solto da entrada: ela está dentro de cada Money.
  • Moeda habilitada sem movimento vem zerada ("0").
  • O caixa livre para novos saques é available menos pending_out. A API não devolve esse número pronto.
  • pending_in é calculado pela API, não vem do livro. Use só para acompanhamento.
  • Livro fora: 503 service_unavailable, repetível.

Não disponível

O Dracma não oferece aporte de caixa: o caixa da operação só cresce por depósito pago ou por devolução de saque. Não existe rota para recarregar o saldo. Se o caixa faltar, o saque novo recebe 422 insufficient_operation_balance.

Exemplos

Pedido:

GET /v1/players/0192a3b4-0000-7000-8000-000000000001/limits?currency=BRL HTTP/1.1
Host: api.example.test
Dracma-Key-Id: key_test_01J9EXEMPLO
Dracma-Timestamp: 1790000100
Dracma-Nonce: 0123456789abcdef0123456789abcdef
Dracma-Signature: v1=<assinatura>

Resposta 200:

{
  "player_ref": "0192a3b4-0000-7000-8000-000000000001",
  "currency": "BRL",
  "total_deposited": { "amount": "10000", "currency": "BRL" },
  "total_withdrawn": { "amount": "5000", "currency": "BRL" },
  "auto_multiplier": "1",
  "auto_withdrawal_remaining": { "amount": "5000", "currency": "BRL" },
  "blocked": false
}

GET /v1/balances, resposta 200:

{
  "data": [
    {
      "available": { "amount": "150000000", "currency": "BRL" },
      "pending_in": { "amount": "250000", "currency": "BRL" },
      "pending_out": { "amount": "90000", "currency": "BRL" },
      "as_of": "2026-10-18T15:00:00Z"
    }
  ]
}

Neste exemplo o caixa livre é R$ 1.500.000,00 − R$ 900,00, ou "150000000" − "90000" = "149910000" na menor unidade.

Erros e casos de borda

Rota Situação Resposta
limites external_ref inválido, currency ausente 400 validation_failed
limites moeda não habilitada 400 currency_not_enabled
limites jogador desconhecido nesta operação 404 not_found
limites e saldos motor de regras ou livro fora 503 service_unavailable com Retry-After; repita
ambas sem o escopo read 403 insufficient_scope
  • Jogador novo, que ainda não pediu nada, devolve 404 nos limites. Trate como "sem histórico": mostre o texto padrão ao jogador.
  • auto_withdrawal_remaining é uma estimativa. Não a use para liberar saldo no seu lado: quem decide é o decision do saque.
  • Os totais são da regra da operação, não do seu livro. Eles podem diferir dos seus por pendentes ou por depósitos ainda em revisão.

Veja também