Pular para o conteúdo principal

Visão geral da API

A API servidor a servidor é com quem o backend do seu casino conversa. Ela é pequena: uma rota de catálogo, sete rotas de batalha e uma rota de token.

URL baseA sua instância, ou a que o host da plataforma te deu
AuthAuthorization: Bearer sbk_...
Content typeapplication/json
Limite de corpo1 MiB
Erros{"error":{"code":"...","message":"..."}} em toda falha

→ Referência completa com Try It

As rotas​

RotaEscopoO que faz
GET /gamesgames:readO catálogo, filtrado pela sua allowlist
POST /battlesbattles:writeAbre um lobby
GET /battlesbattles:readLista as suas batalhas
GET /battles/{id}battles:readLê uma
POST /battles/{id}/seatsbattles:writeSenta um jogador
POST /battles/{id}/bot-seatsbots:writePreenche o resto com bots
POST /battles/{id}/leavebattles:writeLibera um assento
POST /battles/{id}/cancelbattles:writeCancela um lobby aberto
POST /battles/{id}/viewer-tokensviewer:mintEmite um token do feed ao vivo

Não existe endpoint de início. Uma batalha começa sozinha quando todos os assentos estão READY. Veja Ciclo de vida da batalha.

Quatro comportamentos para conhecer antes de começar​

Dinheiro é string. entry_amount é uma string decimal canônica, nunca um número JSON. Ela também é normalizada: envie "25.50" e toda resposta retorna "25.5". Compare valores fazendo parse como decimal, nunca por igualdade de string.

Os corpos são decodificados de forma estrita. Campo desconhecido é 400, não ignorado em silêncio. Enviar tenant_id num corpo de POST /battles falha com unknown field "tenant_id", porque o tenant vem da sua chave de API e de lugar nenhum mais.

Allowlist vazia significa catálogo vazio. GET /games num casino sem nada liberado retorna {"games": []} e toda criação de batalha falha com game_not_allowed. Isso é configuração, não defeito. Uma mudança de allowlist feita no console aparece na hora; uma que o seu host faz para você pode levar até 30 segundos para chegar nesta API.

A batalha de outro casino responde 404, não 403. Um 403 confirmaria que o id existe, transformando um erro de permissão num oráculo de enumeração de ids.

Uma integração mínima​

Quatro chamadas abrem uma batalha, preenchem e colocam a plateia assistindo:

BASE=https://slotbattle.example.com
KEY=sbk_3f9a1c...

# 1. What may we play?
curl -s "$BASE/games" -H "Authorization: Bearer $KEY"

# 2. Open a lobby. The creator is seated at index 0.
BATTLE=$(curl -s "$BASE/battles" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"game_id":"sweet-bonanza","seats_total":3,"entry_amount":"25.50",
       "currency":"BRL","creator_player_ref":"alice",
       "creator_game_url":"https://provider.example/session/abc"}')

ID=$(echo "$BATTLE" | jq -r .id)

# 3. Seat another player.
curl -s "$BASE/battles/$ID/seats" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"player_ref":"bob","game_url":"https://provider.example/session/def"}'

# 4. Fill what is left with bots — this is usually what starts the battle.
curl -s "$BASE/battles/$ID/bot-seats" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{}'

A batalha agora está rodando. Duas coisas acontecem em seguida, e elas chegam a lugares diferentes:

  • Espectadores conectam no feed WebSocket com o ws_token do passo 2 ou 3.
  • O seu backend recebe um webhook assinado quando a batalha acaba.

Liquide pelo webhook, nunca por um frame de WebSocket. Veja Eventos.

Idempotência​

Nenhuma rota aceita header Idempotency-Key. Torne as retentativas seguras do jeito comum: POST /battles/{id}/seats é naturalmente idempotente por jogador, já que um jogador que já tem assento READY é recusado com 409 em vez de sentado duas vezes.

Limites de taxa​

A superfície S2S não tem rate limiter. As rotas de autenticação do console são limitadas, mas a criação de batalha é limitada por capacidade e não por taxa: uma instância no limite de batalhas em voo responde 503 unavailable, que é retentável com backoff.

Próximo​