Cómo funciona la API de conexión de juegos en vivo a la plataforma

1) Arquitectura general y roles de componentes

Plataforma de operador (Casino Platform): cuentas, billetera, motor de bonificación, límites, KYC/AML, registro de transacciones.

Proveedor de juegos en vivo (Studio/Provider): estudios, distribuidores, streaming de vídeo (WebRTC/Low-Latency HLS), servidor de juegos de rondas.

Agregador (a veces): API única para docenas de proveedores, unificación de monedas/límites/eventos.

Frontend del cliente: cliente web/móvil con apuestas de UI, reproductor de vídeo, chat, consejos locales.

Servicios auxiliares: Risk/Anti-fraud, lógica, análisis, Message Queue Server (Kafka/RabbitMQ), monitoreo.

Topología tipo: cliente → (JWT) → plataforma de → (server-to-server) → proveedor, en paralelo, el cliente recibe el flujo de vídeo de CDN/grupo de servidores multimedia.

2) Ciclo de vida del jugador y sesiones

2. 1. Inicio de sesión y «token de juego»

1. El jugador está autorizado en la plataforma.

2. La plataforma llama a CreateGameSession en el proveedor (S2S), pasa 'player _ id', 'currency', 'country', 'bet _ limits', banderas del juego responsable.

3. El proveedor devuelve el game_token y la launch_url desechables.

4. El cliente abre 'launch _ url' en iframe/nueva pestaña añadiendo' game _ token '(o recibe 302 en la URL final del juego).

Ejemplo 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"
}
}

Respuesta del proveedor:

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

2. 2. Autenticación en el frente

El juego se carga, valida 'game _ token' a través de su bacend.

Se instala WebSocket en el servidor de juegos para apuestas/eventos.

El vídeo fluye a través de WebRTC (baja latencia 0. 5-2 c) o LL-HLS (2-5 s).

3) Dinero y apuestas: Wallet API e idempotencia

3. 1. Saldo y débito/crédito

El proveedor no almacena el «dinero» del jugador - llama a la plataforma Wallet API:

`GET /wallet/balance? player_id' → disponible actualmente.
'POST/wallet/debit' → cargar la tarifa.
'POST/wallet/credit' → acreditar una ganancia/devolución.
'POST/wallet/rollback' → revertir la transacción cuando se cancela la ronda.

Importante: todas las transacciones monetarias son idempotentes por 'transaction _ id '/' round _ id'. La repetición de la misma consulta no cambia el resultado.

Ejemplo de débito (apuesta):

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. Tiempos y estados de apuesta

WINDOW_OPEN → WINDOW_CLOSING → WINDOW_CLOSED. Después de 'WINDOW _ CLOSED', el proveedor prohíbe nuevos adeudos.

Las apuestas tardías se rechazan con el código 'LATE _ BET'.

Cuando se rompe la comunicación, el cliente puede volver a enviar la apuesta - el servidor debe ser capaz de distinguir el duplicado por Idempotency-Key.

Los estados de las transacciones son: 'PENDING', 'SETTLED', 'ROLLED _ BACK', 'REJECTED'.

4) Eventos de la ronda: modelo y orden de prioridad

4. 1. Diagrama de eventos de WebSocket

`round. started '→ viene' round _ id ', temporizador de apuestas.

`bet. accepted/rejected '→ confirmación de cada apuesta.

`round. closed '→ las apuestas ya no se aceptan.

`round. resultado '→ desenlace (sector de la ruleta/tarjetas/huesos).

`payout. created '→ la cantidad ganada por jugador.

`round. settled '→ estado final, suma de comprobación.

Ejemplo 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. Coherencia y montos de comprobación

Cada evento está provisto de 'seq' y 'signature' (mTLS + firma del cuerpo de la consulta).

Para reconciliation se especifica 'payout _ checksum' - la suma de todos los créditos por 'round _ id' debe converger.

5) Transmisión de vídeo y latencia

WebRTC para apuestas de mano en vivo (blackjack/baccarat/ruleta) - un estricto presupuesto de retraso <2 c al cliente.

LL-HLS/DASH para espectadores/escala, permite 2-5 c.

Sincronización de tiempo: NTP/chrony, en payload - 'video _ ts' para réplicas y disputas.

Folback: cuando WebRTC se degrada → cambio automático a LL-HLS con bloqueo de apuestas tardías.

6) Errores, retraídas, temporizaciones

Reglas generales:

Todas las llamadas S2S con timaut de 800-1500 ms, retraen con pausa exponencial y Jitter, pero sin volver a cargar dinero (idempotencia).

Códigos de error de billetera:

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

Formato de error:

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

7) Bonos, giros gratis, seguros

Paralelamente a la billetera «en efectivo» puede haber un saldo de bonificación: payload especifica la fuente de cargo 'source: CASH	BONUS`.
Para los juegos en vivo, los seguros/side beth (por ejemplo, en blackjack) son transacciones separadas con sus propios límites y coeficientes.
Reglas de redondeo: bancario (half-to-even) o a favor del jugador/operador - debe estar fijado en la configuración de integración.

8) Juego responsable y limitaciones

Las marcas de sesión son: 'self _ excluded', 'cooldown _ until', 'loss _ limit _ left',' time _ limit _ left'.

El proveedor puede solicitar 'validate _ limits' antes de cada débito.

La plataforma puede iniciar force_close_session: el jugador es excluido/excedido del límite → el proveedor cierra la ventana de apuestas y realiza devoluciones en apuestas no jugadas.

9) Seguridad y cumplimiento

mTLS para S2S, HSTS, estricta IP-allowlist.

JWT/JWS con TTL breve para tokens de primera línea, audience/issuer validación.

Firma webhook's del proveedor (HMAC-SHA256 sobre el cuerpo).

Registros de acciones de distribuidores, repeticiones de rondas, auditoría sin cambios (almacenamiento WORM).

Almacenamiento de datos personales - minimización de PII, tokenización de 'player _ id', períodos de retención por jurisdicción (GDPR y análogos).

Bloqueos geográficos y prohibiciones por jurisdicción a nivel de CreateGameSession.

10) Reconciliación y finanzas

10. 1. Informes por hora/día

El proveedor da el informe por 'round _ id → total_bets, total_wins, fees'. La plataforma resume:

Importe de los adeudos = Σ de apuestas, Cantidad de créditos = Σ de ganancias + devoluciones, Delta = GGR (teniendo en cuenta bonificaciones/botes/comisiones).

Formato de informe:

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. Escenarios de Rollback

Error de video/guión gráfico → round. cancelled: proveedor de la llave 'rollback' todas las apuestas en la ronda.

Doble procesamiento de débito atrapado en la plataforma → 'DUPLICATE _ TRANSACTION' y 200 OK con el resultado anterior.

11) Chat, moderación y eventos de IU

Los eventos de chat pasan por un canal separado (WebSocket # 2) con filtros de palabras de parada.

Anuncios del sistema (close bets, winner list): sólo de la fuente de confianza del proveedor, firmado/temporizado.

12) Pruebas y certificación

Sandbox proveedor: resultados fijos, la capacidad de forzar 'round. result`.

Esquema de QA: tabla de pruebas con ventanas de apuestas cortadas (5-8 c) y flow acelerado.

Carga: simulación de 5-10 mil jugadores simultáneos, débitos máximos por segundo (TPS) ≥ × programado 1. 5.

Certificación de integración: hojas de comprobación de idempotencia, monedas, redondeo, procesamiento de desconexiones, cumplimiento de límites y autolesión.

13) Métricas y SLO

Esos son: media/95p latency para 'debit/credit', WebSocket round-trip, error de sincronización de tiempo, drop-rate WebRTC.

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

Ejemplos de SLO:

99. 5% `debit` ≤ 1. 2 c, 99. 9% envío 'round. nat '≤ 300 ms después de la fijación, videollamada ≤ 2. 5 s para WebRTC 95p.

14) Multivalor, impuestos, localización

Conversión - fuera del proveedor: el juego funciona estrictamente en la moneda de la sesión.

Impuestos/retenciones - en el lado de la plataforma cuando 'credit' (campo 'withholding').

Localización: 'lang', formato de números/moneda, zona horaria para temporizadores e informes.

15) Opciones de integración

1. Direct-to-Provider: control máximo y fich, pero contratos/certificaciones individuales.

2. A través del agregador: cobertura rápida por parte de los proveedores, esquemas unificados, a veces menos flexibilidad.

3. Híbrido: mesas superiores directamente, el resto a través del agregador.

16) Mini especificación (total)

16. 1. WebSocket entrantes (de cliente a proveedor)

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

16. 2. WebSocket saliente (de proveedor a 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 ↔ proveedor)

'POST/wallet/debit' (idempotente)

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

Firma HMAC, 'Timestamp', 'Nonce', protección contra repeticiones (TTL ≤ 60 c).

17) Casos de borde y cómo cerrarlos

Ruptura de conexión en el jugador: la apuesta se envía, no hay confirmación → repetición con la misma 'Idempotency-Key'; el servidor responderá con el estado anterior.

Cambio de distribuidor/baraja en ronda: cancelación automática y 'rollback' completo.

Divergencia de moneda: 'CURRENCY _ MISMATCH' + registro de eventos; el juego está bloqueado hasta que la sesión se reinicie.

Self-exclusion en el momento del juego: inmediato 'force _ close _ session', devuelve los no jugados.

Cambio de calidad de vídeo: solo cliente, sin afectar a temporizadores/apuestas.

Re-handshake WebSocket: sin perder el orden es la cola de eventos con 'seq', el 'dagón' de los perdidos.

18) Check-list de lanzamiento de producción

Seguridad

mTLS + pinning del certificado, IP-allowlist.
Firma todos los webhook y verifica 'Timestamp '/' Nonce'.
Mini-PII: sólo 'player _ id' (tokenizado).

Seguridad

Idempotencia de todas las transacciones monetarias.
Repeticiones de rondas y auditorías inmutables.
Auto-folback WebRTC → LL-HLS.

Producto

Los límites/juego responsable se aplican en tiempo real.
Pistas nativas en el momento de la apuesta.
Dashboards SLO + alertas 24/7.

La API de integración de juegos en vivo es un conjunto de stream de bajo rendimiento, bus de evento y billetera idempotente con requisitos rígidos de orden de mensajes, tiempo de espera y seguridad. La implementación exitosa se basa en: un ciclo de vida estricto de apuestas y rondas, consistencia verificable (reconciliation), protección de datos y límites de juego responsable - y convierte la «transmisión hermosa» en un producto financiero confiable y certificable.