Como funciona a API de conexão de jogos de lieve à plataforma

1) Arquitetura geral e papéis de componentes

Plataforma do operador: contas, carteira, bónus, limites, KYC/AML, registro de transações.

Provedor de jogos ao vivo (Studio/Provider): estúdios, distribuidores, roteiros de vídeo (WebRTC/Low-Latency HLS), servidor de round de jogos.

Agregador (às vezes): API unificada para dezenas de provedores, unificação de moedas/limites/eventos.

Frontend cliente: cliente web/celular com apostas UI, leitor de vídeo, bate-papo, dicas locais.

Serviços de apoio: Risk/Anti-fraud, loging, analista, filas de mensagens (Kafka/RabbitMQ), monitoramento.

Topologia típica: O cliente → (JWT) → a plataforma → (server-to-server) → o provedor, e, paralelamente, o cliente recebe um fluxo de vídeo de CDN/pool de mídia.

2) Ciclo de vida do jogador e sessões

2. 1. Login e «token de jogo»

1. O jogador é autorizado na plataforma.

2. A plataforma chama o provedor (S2S), transmite «player _ id», «currency», «country», «bet _ limits», as bandeiras do jogo responsável.

3. O provedor devolve o game _ token descartável e o launch _ url.

4. O cliente abre 'launch _ url' no iframe/nova guia adicionando 'game _ tocen' (ou recebendo 302 para o URL final do jogo).

Exemplo de consulta S2S:

http
POST /api/v1/sessions
Content-Type: application/json
Authorization: Bearer <platform_api_key>

{
"player_id": "u-918273",  "session_id": "sess-5f3b2",  "currency": "EUR",  "country": "DE",  "lang": "de",  "bet_limits": {"min": 0. 5, "max": 2000},  "responsible_gaming": {"self_excluded": false, "deposit_limit_left": 150},  "callback_urls": {
"balance": "https://platform. example. com/wallet/balance",   "debit":  "https://platform. example. com/wallet/debit",   "credit": "https://platform. example. com/wallet/credit",   "rollback":"https://platform. example. com/wallet/rollback",   "events": "https://platform. example. com/game/events"
}
}

Resposta do provedor:

json
{
"game_token": "gtkn_7f0...e2a",  "launch_url": "https://live. provider. com/launch/roulette",  "expires_in": 900
}

2. 2. Autenticação na frente

O jogo é carregado, valendo 'game _ token' através do seu becand.

Instala WebSocket para o servidor de jogos de apostas/eventos.

O fluxo de vídeo segue o WebRTC (baixa retenção 0. 5-2 c) ou LL-HLS (2-5 c).

3) Dinheiro e apostas: API Wallet e Idempotação

3. 1. Equilíbrio e débito/crédito

O provedor não armazena o «dinheiro» do jogador - ele chama a Plataforma Wallet API:

`GET /wallet/balance? player _ id '→ o atual.
'POST/wallet/debit' → descontar a taxa.
'POST/wallet/credit' → inscrever ganho/retorno.
'POST/wallet/rollback' → a reversão da transação ao cancelar a rodada.

O importante é que todas as transações em dinheiro são idimpotentes por 'transmissão _ id '/' round _ id'. A repetição da mesma solicitação não altera o resultado.

Exemplo de débito (aposta):

http
POST /wallet/debit
Idempotency-Key: trx-7a2df-001
Content-Type: application/json

{
"player_id": "u-918273",  "round_id": "r-2025-10-18-12:30:15Z-001",  "transaction_id": "trx-7a2df-001",  "amount": 25. 00,  "currency": "EUR",  "bet_type": "roulette_straight",  "meta": {"table_id":"ru-11", "selection":"17", "odds":35}
}

3. 2. Timing e apostas estatais

WINDOW_OPEN → WINDOW_CLOSING → WINDOW_CLOSED. Depois de 'WINDOW _ CLOSED', o provedor proíbe novos débitos.

As apostas tardias são rejeitadas com o código 'LATE _ BET'.

Se você romper o vínculo, o cliente pode enviar a taxa novamente - o servidor deve ser capaz de distinguir a duplicação pelo Idempotency-Key.

Os estados de transação são 'PENDING', 'MASSLED', 'ROLLED _ BACK', 'REJECTED'.

4) Eventos de rodada: modelo e prioridade

4. 1. Esquema de eventos por WebSocket

`round. started '→ vem' round _ id ', o time de apostas.

`bet. aceited/rejected '→ confirmação para cada aposta.

`round. closed '→ as apostas já não são aceitas.

`round. result' o resultado (setor de roleta/mapas/ossos).

`payout. created '→ o valor do ganho do jogador.

`round. setled 'é o status final, o valor de referência.

Exemplo de evento de resultado:

json
{
"type": "round. result",  "round_id": "r-2025-10-18-12:30:15Z-001",  "table_id": "ru-11",  "payload": {
"roulette": {"number":17, "color":"black"},   "hash": "sha256:8a7b...d1c",   "video_ts": "2025-10-18T12:30:23. 450Z"
}
}

4. 2. Coerência e valores de controle

Cada evento é fornecido com 'seq' e 'signatura' (mTLS + assinatura do corpo da solicitação).

A recordação indica 'payout _ checksum' - a soma de todos os créditos de 'round _ id' deve corresponder.

5) Fluxo de vídeo e atraso

WebRTC para apostas de mão viva (blackjack/baquara/roleta) - orçamento rigoroso de atraso <2 c para o cliente.

LL-HLS/DASH para público/escala, permite 2-5 c.

Sincronização de tempo: NTP/crony, em payload - 'video _ ts' para réplicas e disputas.

Falback: Ao degradar o WebRTC, → a mudança de carro para LL-HLS com bloqueio de apostas tardias.

6) Erros, retais, temporizadores

Regras gerais:

Todas as chamadas S2S com temporizador 800-1500 ms, retrai com pausa exponencial e Jitter, mas sem novo cancelamento (idempotidade).

Códigos de erro de carteira:

`INSUFFICIENT_FUNDS`, `LIMIT_EXCEEDED`, `ACCOUNT_LOCKED`, `DUPLICATE_TRANSACTION`, `LATE_BET`, `CURRENCY_MISMATCH`.

Formato de erro:

json
{
"error": "INSUFFICIENT_FUNDS",  "message": "Balance 18. 00 < required 25. 00",  "transaction_id": "trx-7a2df-001"
}

7) Bônus, fraldas, seguros

Paralelamente à carteira «em dinheiro» pode haver um saldo de bónus: payload indica a fonte de débito 'fonte: CASH	BONUS`.
Para jogos de lave, os seguros/side bet (por exemplo, no blackjack) são transações individuais com limites e coeficientes próprios.
Regras de arredondamento: bancário (half-to-even) ou a favor do jogador/operador - deve ser registrado no configh de integração.

8) Jogo responsável e restrições

Bandeiras de sessão: 'self _ excluded', 'cooldown _ until', 'loss _ limit _ left',' time _ limit _ left'.

O provedor pode solicitar 'validate _ limits' antes de cada débito.

A plataforma pode iniciar force _ close _ sessions: o jogador está excluído/ultrapassou o limite → o provedor fecha a janela de apostas e faz reembolsos a taxas não financiadas.

9) Segurança e Complacência

mTLS para S2S, HSTS, IP-allowlist rigoroso.

JWT/JWS com TTL curto para tokens de frente, audição/issuer verificação.

Assinatura webhook 'ov do provedor (HMAC-SHA256 acima do corpo).

Logs de ações de distribuidores, réplicas de rodadas, auditoria de armazenamento WORM inalterável.

Armazenamento de dados pessoais - Minimização de PII, tocenização de 'player _ id', prazos de armazenamento de jurisdição (GDPR e similares).

Bloqueios geo e proibições de jurisdição no nível CreateGameSession.

10) Reconciliação e finanças

10. 1. Relatórios horários/diários

O provedor informa sobre 'round _ id → total _ bets, total _ wins, fees'. A plataforma reduz:

Soma de débitos = Taxas, Soma de créditos = Ganhos + restituições, Delta = GGR (considerando bónus/jackpots/comissões).

Formato de relatório:

json
{
"date": "2025-10-18",  "currency": "EUR",  "tables": [{
"table_id": "ru-11",   "rounds": 1260,   "total_bets": "45230. 00",   "total_payouts": "43012. 50",   "jackpot_contrib": "302. 00",   "provider_fee": "2. 5%"
}]
}

10. 2. Cenários Rollback

Falha no vídeo/storyboard → round. cancelled: O provedor envia 'rollback' para todas as apostas do round.

Processamento duplo do débito capturado na plataforma → 'DUPLICATE _ TRANSMISSÃO' e 200 OK com o resultado anterior.

11) Bate-papo, moderação e eventos UI

Os eventos de bate-papo vão através de um canal separado (WebSocket nº 2) com filtros parados.

Anúncios de sistema (close bets, winner list) - apenas da fonte confiável do provedor, assinados/temporizados.

12) Testes e certificação

Sandbox provedor: resultados fixos, capacidade de forçar 'round. result`.

Contorno QA: Tabela de teste com janelas de apostas cortadas (5-8 c) e flow acelerado.

Carga: simulação de 5 a 10 mil jogadores simultâneos, debêntures de pico por segundo (TPS) ≥ programado x 1. 5.

Certificação de integração: cheques de idempotação, moedas, arredondamento, processamento de apagões, conformidade com limites e self-exclusion.

13) Métricas e SLO

Aqueles são median/95p latency para 'debit/credit', WebSocket round-trip, erro de sincronização de tempo, drop-rate WebRTC.

Продукт: bet acceptance rate, late-bet rate, dispute rate, chargeback rate, session duration, retention, ARPU/LTV.

SLO exemplos:

99. 5% `debit` ≤ 1. 2 c, 99. 9% entrega 'round. result' ≤ 300 ms após a gravação, gravação de vídeo ≤ 2. 5 c para 95p WebRTC.

14) Multivaluta, impostos, localização

Conversão - fora do provedor: o jogo funciona estritamente na moeda da sessão.

Impostos/retenção - do lado da plataforma para 'credit' (campo 'witholding').

Localização: 'lang', formato de número/moeda, fuso horário para temporizadores e relatórios.

15) Opções de integração

1. Direto-to-Provider: controle máximo e fic, mas contratos/certificações individuais.

2. Através do agregador: cobertura rápida por provedores, circuitos unificados, às vezes menos flexibilidade.

3. As mesas de topo, o resto através do agregador.

16) Minigrafia (total)

16. 1. WebSocket entrantes (do cliente para o provedor)

json
{ "type":"bet. place", "bet":{
"amount": 25, "selection":"17", "table_id":"ru-11"
}, "idempotency_key":"c3a2-...-001" }

16. 2. WebSocket de saída (do provedor para o cliente)

json
{ "type":"bet. accepted", "bet_id":"b-8821", "seq":12031 }
{ "type":"round. closed", "round_id":"r-...001", "seq":12050 }
{ "type":"round. result", "result":{"number":17,"color":"black"}, "seq":12070 }
{ "type":"payout. created", "amount":875, "currency":"EUR", "seq":12075 }

16. 3. Wallet S2S (plataforma ↔ provedor)

'POST/wallet/debit' (idempotado)

'POST/wallet/credit' (idempotado)
'POST/wallet/rollback'

Assinatura HMAC, 'Timestamp', 'Nince', proteção contra repetições (TTL ≤ 60 c).

17) Malas de borda e como fechá-las

Quebra de conexão do jogador: taxa enviada, sem confirmação com o mesmo 'Idempotency-Key'; o servidor responderá ao status anterior.

Mudança de distribuidor/baralho na rodada: cancelamento automático e completa 'rollback'.

Correspondência da moeda: 'CURRENCY _ MISMATCH' + registro do evento; o jogo é bloqueado até a sessão ser superestimada.

Self-exclusion no momento do jogo: imediato 'force _ close _ sessions', devolução dos indevidos.

Mudança de qualidade de vídeo: somente cliente, sem impacto sobre os temporizadores/apostas.

Ré-handschake WebSocket, sem perder a ordem, é a fila de eventos com 'seq', 'apanhar' os que faltaram.

18) Folha de cheque de produção

Segurança

Certificado mTLS + pinning, IP-allowlist.
Assinar todos os webhook 'ov e verificar' Timestamp '/' Nince '.
Mini-PII: apenas 'player _ id' (torneado).

Confiabilidade

Idempotidade de todas as transações em dinheiro.
Réplicas de rodadas e auditoria inalterável.
Folback automático WebRTC → LL-HLS.

Produto

Os limites/jogo responsável são aplicados em tempo real.
Dicas nativas no momento da aposta.
Dashboard SLO + alertas 24/7.

A API de integração de jogos de lave é uma ligação de striptease de baixo nível, pneu de evento e carteira idumpotente com exigências rígidas de ordem de mensagens, timing e segurança. A implementação com sucesso é baseada em um ciclo de vida rigoroso de apostas e rodadas, consistência verificável, proteção de dados e limites do jogo responsável - e transforma a «transmissão bonita» em um produto financeiro confiável e certificado.