Cómo funciona la integración de API entre estudios y plataformas

La integración del estudio (proveedor de juegos) con la plataforma/agregador es una cadena de llamadas sincrónicas y asíncronas alrededor de la sesión, la cartera, el resultado de giro y la telemetría de eventos. A continuación, un mapa breve pero práctico, ya que todo se conecta sin dolor para los desarrolladores y el cumplimiento.

1) Arquitectura en la palma de la mano

Actors:

Studio RGS (Remote Game Server) es la lógica del juego, RNG, bonos, jackpots.
Plataforma/Agregador - enrutamiento, facturación, promoción, cumplimiento.
El operador es la cartera del jugador, KYC/RG, escaparate.
El cliente es el contenedor web/mobile del juego (iframe/webview/native).

Neumáticos principales:

Sync API: sesiones, billetera, outcome.
Async/Bus de eventos: giros, bonos, botes, RG, errores técnicos.
Metadatos/catálogo: juegos, marcas, perfiles RTP, locals.

2) Protocolos y soluciones básicas

Transporte: HTTPS/JSON (a veces gRPC para bus de evento/billetera).

Versioning: 'Accept: application/vnd. rgs. v1 + json 'o '/v1/...'; degradación de compatibilidad - sólo a través de nuevas versiones.

Identificación: 'game _ id', 'build _ hash', 'operator _ id', 'session _ id', 'round _ id', 'spin _ id'.

Tiempo: estrictamente UTC, ISO-8601 con milisegundos.

Monedas: ISO-4217 + precisión (unidades menores). FX - en el lado del operador/agregador.

3) Autenticación y autorización

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

Sesión del jugador: JWT corto-vivo (firma la plataforma) c 'sub', 'geo', 'rg _ flags',' amb ',' aud = studio '.

Listas de acceso: IP allowlist + mTLS para bucles prod.

4) Modelos de billetera: debit/credit vs transfer

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

1. La plataforma llama a RGS: 'SpinRequest (stake)' → RGS calcula el resultado → devuelve 'win'.

2. Paralelamente, la plataforma hace 'debit (stake)' y 'credit (win)' en su operador.

Pros: contabilidad simple. Contras: más llamadas de red, requisitos de idempotencia rígidos.

B) Transfer (session balance):

1. Al inicio de la sesión, la plataforma hace 'transferIn (amount)' en RGS.

2. Durante los giros, el propio RGS mantiene el balance de la sesión; al finalizar - 'transferOut (remaining)'.

Pros: menos chats de billetera. Contras: contabilidad de «dinero del lado RGS», riesgos adicionales y reconciliaciones.

Recomendaciones:

Para las ranuras, es más común usar debit/credit con llaves idempotentes.

En giros gratis y torneos es conveniente tener tipos separados de apuestas 'spin _ type = free	promo`.

5) Idempotencia y coherencia

Cada paso de dinero debe tener un único 'idempotency _ key' (por ejemplo, 'round _ id' o 'spin _ id').

Las repeticiones ('HTTP 409/425') devuelven el mismo resultado en lugar de 'error ya realizado'.

Exactly-once es difícil de lograr, por lo que construimos en-least-once + idempotencia.

La idempotencia se extiende a: 'debit', 'credit', 'jackpot _ contribution', 'bonus _ award'.

6) Esquemas de consultas clave (abreviados)

6. 1. Inicio de la sesión

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. Giro (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-…"
}

Respuesta:

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. Registro de eventos (Bus de eventos, formato 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) Versionar los builds y los builds de mercado

'build _ hash' (SHA-256) - obligatorio en cada evento.

Global vs Market build: idioma, advertencias, restricciones de apuestas, perfil RTP.

La plataforma valida: «¿se juega ahora el billete que corresponde al certificado de un país dado».

Matriz: 'game _ id × country × rtp_profile × build_hash'.

8) RNG, matemáticas y réplicas

RNG vive en RGS; la lógica empresarial no cambia las posibilidades de «estar a la altura».

Para el forensiki: 'seed/nonce' para la ronda/spin + versión mecánica.

Replay: por 'spin _ id '/' seed', el RGS reproduce el resultado y da el rastro de auditoría.

9) Juego responsable (RG) y ganchos de cumplimiento

Hooks de tiempo/límite: 'session _ time _ ms',' recordatorios ', timeouts;' rg _ event 'en Event Bus.

Auto-exclusión/bloque: con la bandera - inmediato '403 RG_BLOCKED'.

IU-invariantes: la plataforma comprueba que el cliente muestre las advertencias/marcas de edad de market build.

10) Errores, retraídas y SLA

Códigos: '400' (validación), '401/403' (autenticación/RG), '409' (conflicto de idempotencia), '422' (error empresarial), '429' (límite de tasa), '5xx' (temporal).

Política de retraídas: exponencial, con clave idempotente y deduplicación en el receptor.

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

11) Observabilidad y auditoría

Registros: registros de servidor sin cortar con la corulación 'trace _ id'.

Métricas: p95/p99 latency, error rate por métodos, desviaciones de RTP/frecuencias de bonificación, fracción de «giros elegables».

Alertas: por la SLA, por las anomalías de las matemáticas, por el crecimiento de los fallos de la cartera.

Auditoría: almacenamiento WORM para eventos de apuestas/resultados; exportar bajo petición.

12) Seguridad

mTLS + TLS 1. 2 +, HSTS, CORS rigurosos en el loader del cliente.

Rotación de kay, fichas TTL cortas, chequeos JTI/nonce.

Anti-tamper para el cliente: firmas de assets, comprobación de integridad, protección contra desbaggers.

Los secretos son sólo en el administrador secreto; ninguna «clave en la confiscación del juego».

13) Entornos de prueba y certificación

Sandbox: billeteras ficticias, RNG determinista (fixed seed), secuencias de comandos RG auto-fallido.

Staging: copia de prod infra sin dinero real.

Paquete para laboratorios: GDD/matemáticas, archivos RNG, diagramas de registro, build repeatable y hashes.

14) Promociones y botes en la API

Tiradas gratis: transferencia del paquete: 'grant _ free _ spins (cuenta, bet_size, rtp_profile?)'; los eventos se gastan en RGS y son lógicos.

Torneos: atributo 'spin _ type = tournament' + agregados individuales en Event Bus.

Jackpots: 'jackpot _ contribution' y 'jackpot _ win' como transacciones individuales; consistencia a través de la idempotencia y eventos «firmados».

15) Informes y facturación

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

Per-spin/turnover-fee: cuenta por 'elegible _ spins' o 'Σ stake × rate'.

Rev-share: de 'NetWin' después de la «cascada» de las retenciones; true-up trimestral para FX/excepciones.

16) Secuencias típicas (diagramas verbales)

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) Change-management y compatibilidad

Contrato en primer lugar: OpenAPI/Protobuf es una única fuente de esquemas.

SemVer: sólo agregue campos; eliminación/cambio - en/v2.

Características flags: activar opciones (Bonus Buy/Ante) - sólo a través de perfiles certificados.

Deprecation: announce → grace period → apagado en regiones inactivas.

18) Hojas de cheques

Estudio → Plataforma

Specas OpenAPI/gRPC y peiload aproximados.
Idempotencia 'spin/debit/credit/jackpot'.
'build _ hash' y el registro de market builds.
réplica de RNG y registro de auditoría.
RG-hooks y errores '403 RG_BLOCKED'.
Sandbox con fix seed, billetera de prueba y autocenarios.

Plataforma → Estudio

Firma JWT con TTL corta, allowlist IP, mTLS.
Validador de marcas y certificados.
Bus de evento y dashboards (latency/error/RTP drift).
Cuotas y rate-limits con retroalimentación honesta '429-Retry-After'.
SLA/incidentes/canales de comunicación 24 × 7.

19) 30-60-90 plan de lanzamiento

0-30 días

Negociar contratos de API y esquemas de eventos, seleccionar un modelo de billetera.

Elevar sandbox: fixed-seed RNG, prueba de billetera, autotestas de idempotencia.

El registro 'build _ hash' y la matriz de mercado principal.

31-60 días

Integración de billetera y giros; incluir Bus de evento y dashboards.

Pruebas de carga (p95/p99), retraídas/idempotencia, escenarios de caos de la red.

Cumplimiento: RG-hooks, localies, age-labels; un paquete para el laboratorio.

61-90 días

El piloto tiene 1-2 operadores, A/B en la promoción (giros gratis/torneos).

Escriba true-up/reporting, alertas de deriva RTP/bonus-freq.

Preparación de mejoras v2: eventos de batch, gRPC para monedero, geo-routing.

20) Preguntas frecuentes cortas

¿Dónde se comprueba la versión RTP/? En platfom: 'build _ hash' ↔ certificado ↔ país.

¿Se puede cambiar el RTP dinámicamente? No. Sólo perfiles previamente certificados y sólo por cambiar de mercado build.

¿Cómo resolver el «doble debate»? Clave idempotente + almacenamiento del estado de la transacción; repetición - devuelve el resultado.

¿Necesita gRPC? Útil para monedero/eventos a altos volúmenes; NAT permanece para metadatos/administración.

Integración estable son contratos + idempotencia + observabilidad. Los esquemas de eventos transparentes, el control de los builds/mercados, los RG-hooks y la disciplina de las versiones eliminan el 90% de los riesgos al inicio. A continuación, la automatización de promos y reporting, un SLA rígido y un desarrollo API cuidadoso sin cambios «rompedores».