Como funciona a API integração entre estúdios e plataformas

A integração entre o estúdio (provedor de jogos) e a plataforma/agregador é uma cadeia de chamadas sincronizadas e assíncronas em torno de uma sessão, carteira, resultado das costas e telemetria de eventos. Abaixo é um mapa breve, mas prático, como tudo é conectado sem dor para desenvolvedores e complens.

1) Arquitetura na palma da mão

Actos:

Studio RGS (Remote Game Server) é a lógica do jogo, RNG, bónus, jackpots.
Plataforma/Agregador - roteiro, billing, promo, complacência.
Operador - carteira do jogador, KYC/RG, vitrine.
O cliente é um contêiner web/mobile do jogo (iframe/webview/native).

Pneus principais:

Sync API: sessões, carteira, outcome.
Async/Evento Ônibus: eventos de spin, bônus, jackpots, RG, erros técnicos.
Metadados/catálogo: jogos, market builds, perfis RTP, locais.

2) Protocolos e soluções básicas

Transporte: HTTPS/JSON (às vezes gRPC para Event Ônibus/carteira).

Versioning: 'Accept: aplicação/vnd. rgs. v1 + json 'ou '/v1/...'; A degradação da compatibilidade é apenas através de novas versões.

Identificação: 'game _ id', 'build _ hash', 'operator _ id', 'sessions _ id', 'round _ id', 'spin _ id'.

Hora: Rigorosamente UTC, ISO-8601 com milissegundos.

Moedas: ISO-4217 + precisão (menor units). FX - do lado do operador/agregador.

3) Autenticação e autorização

Server-to-server: OAuth2 Client Credentials или HMAC-подпись (`X-Signature: HMAC_SHA256(payload, shared_key)`).

Sessão do jogador: short-lived JWT (assina plataforma) c 'sub', 'geo', 'rg _ flags',' exp ',' aud = studio '.

Listas de acesso: IP allowlist + mTLS para caminhos prod.

4) Modelos de carteira: debit/credit vs transfer

A) Debit/Credit (on-the-fly):

1. A plataforma chama RGS: 'SpinRequest (stake)' → RGS calcula o resultado → devolve 'win'.

2. Paralelamente, a plataforma faz 'debit (stake)' e 'credit (win)' em sua operadora.

Os benefícios são uma simples contabilidade. Contras: mais chamadas de rede, exigências rígidas de idempotidade.

B) Transfer (session balance):

1. No início da sessão, a plataforma faz 'transferIn (amount)' em RGS.

2. Durante os spins, o RGS faz o balanço da sessão; ao terminar, 'transferOut (remaining)'.

Mais, menos bate-papos. Contras: conta «dinheiro à RGS», riscos adicionais e recalculações.

Recomendações:

Para slots, é mais comum usar debit/credit com chaves idumpotentes.

Em free spins e torneios é conveniente ter tipos de apostas individuais 'spin _ tipo = free	promo`.

5) Idempotidade e coerência

Cada etapa em dinheiro deve ter um único 'idempotency _ key' (por exemplo, 'round _ id' ou 'spin _ id').

As repetições («HTTP 409/425») devolvem o mesmo resultado, em vez de «erro já concluído».

Exactly-once é difícil de alcançar, por isso construímos at-least-once + idempotidade.

A idimpotência pode ser estendida em «debit», «credit», «jackpot _ contabilidade», «bônus _ award».

6) Esquemas de solicitação chave (reduzidos)

6. 1. Início da sessão

json
POST /rgs/v1/sessions
{
"session_id": "s-…",  "operator_id": "op-…",  "player_id": "p-…",  "game_id": "g-BookOf…",  "build_hash": "sha256:…",  "jwt": "eyJhbGci…",  "geo": "DE",  "currency": "EUR",  "rg_flags": {"self_excluded": false, "time_limit_min": 60}
}

6. 2. Spin (debit/credit)

json
POST /rgs/v1/spins
{
"spin_id": "spin-…",  "round_id": "rnd-…",  "session_id": "s-…",  "stake": {"amount": 1. 00, "currency": "EUR"},  "spin_type": "cash",  "idempotency_key": "spin-…"
}

Resposta:

json
{
"spin_id": "spin-…",  "outcome": {
"win": {"amount": 3. 40, "currency": "EUR"},   "features": [{"type":"bonus_trigger","name":"FreeSpins","count":10}],   "symbols": "opaque-or-omitted"
},  "rgs_txns": [
{"type":"jackpot_contribution","amount":0. 01}
],  "telemetry_ref": "evt-…"
}

6. 3. Logs de evento (Event Ônibus, formato de batch)

json
POST /rgs/v1/events/batch
{
"events":[
{
"type":"spin_finished",    "ts":"2025-10-20T11:22:33. 123Z",    "spin_id":"spin-…",    "round_id":"rnd-…",    "stake":1. 00,"win":3. 40,"currency":"EUR",    "game_id":"g-…","build_hash":"sha256:…",    "player_id":"p-…","operator_id":"op-…",    "spin_type":"cash"
}
]
}

7) Versionização de bildes e market builds

'build _ hash' (SHA-256) é obrigatório em cada evento.

Global vs Market build: linguagem, avisos, limitações de apostas, perfil RTP.

A plataforma valida: «Se está a ser jogado um bild que corresponde ao certificado deste país».

Matriz: 'game _ id x country x rtp _ profile x build _ hash'.

8) RNG, matemática e réplicas

A RNG vive em RGS; A lógica empresarial não muda as hipóteses de voar.

Para forense: 'seed/nonte' para round/spin + versão mecânica.

Réplicas: Por 'spin _ id '/' seed', o RGS reproduz o resultado e dá uma pista de auditoria.

9) Resolvível Gaming (RG) e ganchos complicados

Ganchos de tempo/limite: 'sessions _ time _ ms', 'lembretes', timeouts; 'rg _ event' em Event Ônibus.

Auto-exclusão/bloco: com a bandeira, «403 RG _ BLOCKED» imediato.

Invariantes UI: a plataforma verifica que o cliente exibe avisos/marcas etárias no market build.

10) Erros, retais e SLA

Códigos: '400' (validação), '401/403' (autenticação/RG), '409' (conflito de idempotação), '422' (erro de negócio), '429' (rate limit), '5xx' (temporal).

A política de retrações é exponencial, com chave idumpotente e dedução no receptor.

SLA: disponibilidade da API ≥99. 9%, p95 latency para 'spin' ≤200 -300 ms (regional), Event Ônibus - near-real-time <60 s.

11) Observação e auditoria

Logs: logs de servidor não cortados com a coralização 'trace _ id'.

Métricas: p95/p99 latency, errador rate por métodos, desvios de RTP/frequência de bônus, participação «eligível spins».

Alerts: Por SLA, por anomalias de matemática, aumento de falhas de carteira.

Auditoria: armazenamento WORM para eventos de apostas/resultados; exportação por solicitação.

12) Segurança

mTLS + TLS 1. 2 +, HSTS, CORS rigoroso no loador do cliente.

Rotação K., TTL KTL curtos, JTI/lince-verificação.

Anti-tamper para o cliente: assinaturas de assets, verificação de integridade, proteção contra debaggers.

Os segredos são apenas segredos gerentes; Nada de «chave no jogo de configh».

13) Ambientes de teste e certificação

Sandbox: carteiras fictícias, RNG (fixed seed) determinados, o fracasso automático dos cenários RG.

Uma cópia de prod-infra sem dinheiro real.

O pacote para laboratórios é GDD/matemática, arquivo RNG, esquemas de logs, repeatable build e hashy.

14) Promos e jackpots em API

Free Spins: transferência de pacote: 'grant _ free _ spins (count, bet _ size, rtp _ profile?)'; eventos são gastos em RGS e logados.

Torneios: atributo 'spin _ tipo = tornement' + unidades individuais em Event Ônibus.

Jackpots: 'jackpot _ sustentation' e 'jackpot _ win' como transações individuais; consistência através da idempotidade e eventos «assinados».

15) Relatórios e Billing

Блоки выгрузок: `spins_total`, `eligible_spins`, `turnover`, `ggr`, `netwin`, `jackpot_contrib`, `bonus_cost`, `royalty_due`.

Per-spin/turnover-fee: conta em 'eligível _ spins' ou ' stake x rate'.

De 'NetWin' após as «cataratas» de retenção; true-up trimestral para FX/exceções.

16) Sequências típicas (diagramas verbais)

Spin (debit/credit):

Client → Platform: StartRound → Platform → RGS: Spin → RGS → Platform: Outcome → Platform → Wallet: Debit → Platform → Wallet: Credit → Platform → Client: Result → Platform → EventBus: spin_finished.

Free Spins:

Platform → RGS: GrantFreeSpins → Client: Start → RGS: Consume/Log each → EventBus: spin_finished (spin_type=free).

17) Mudar-management e compatibilidade

Contrato-primeiro (contract-first): OpenAPI/Protobuf é uma única fonte de esquema.

SemVer: Apenas adicione os campos; remoção/alteração - em/v2.

Função flags: ativação de opções (Bónus Buy/Ante) - somente através de perfis certificados.

Deprecation: announce → grace period → desligado em regiões inativas.

18) Folhas de cheque

Estúdio → Plataforma

OpenAPI/grRPC spacks e palatáveis.
Idempotidade 'spin/debit/credit/jackpot'.
'build _ hash' e registro market builds.
Réplicas RNG e logs de auditoria.
Ganchos RG e erros '403 RG _ BLOCKED'.
Sandbox com fix-seed, carteira de teste e carros.

Plataforma → Estúdio

Assinatura JWT com TTL curto, allowlist IP, mTLS.
Validador market builds e certificados.
Event Ônibus e dashboards (latency/erro/RTP drivt).
Quotas e rate-limits com feedback honesto '429-Retry-After'.
SLA/incidentes/canais de comunicação 24 x 7.

19) 30-60-90 plano de lançamento

0-30 dias

Negociar contratos de API e esquema de eventos, escolher o modelo de carteira.

Levantar sandbox: fixed-seed RNG, carteira de teste, carros de idempotação.

Registro de 'build _ hash' e matriz primária de market builds.

31-60 dias

Integração de carteira e spin; incluir Event Ônibus e dashboards.

Testes de carga (p95/p99), retraí/idempotidade, cenários de caos da rede.

Complaens: ganchos RG, locais, age-labels; Um pacote para o laboratório.

61-90 dias

Piloto em 1-2 operadores, A/B em promoção (free spins/torneios).

Digite true-up/relatório, alertas RTP à deriva/bônus-freq.

Preparar v2 melhorias para eventos de batch, gRPC para carteira, geo-roting.

20) FAQ curto

Onde é verificado o RTP/versão? A placa «build _ hash» mostra um certificado país.

Você pode alterar o RTP dinamicamente? Não. Apenas perfis pré-certificados e apenas comutando market build.

Como decidir «duplo debit»? Chave Idumpotente + armazenamento de status de transação; repetição - devolve o resultado.

Precisas de gRPC? Útil para carteirinha/iWent em alto volume; O REST fica para metadados/admininos.

Integração estável são contratos + idempotidade + observabilidade. Os esquemas de eventos transparentes, o controle de mercado/bilds, os ganchos RG e a disciplina de versões removem 90% dos riscos no início. Mais adiante, automação de promoção e relatórios, SLA rígido e desenvolvimento cuidadoso da API sem mudanças «quebrantes».