Cómo funciona la API de los sistemas de jackpot

Texto completo del artículo

💡 18+. El material es de ingeniería y aplicación, sin llamada al juego. Términos: plataforma - PAM/billetera/taquilla/bonos/RG; RGS - Remote Game Server (el núcleo de los juegos del estudio); agregador: capa unificada para múltiples RGS; JP es un servicio jackpot.

1) ¿Qué es un sistema de bote y dónde está en el ecosistema

El sistema Jackpot es un servicio separado (a veces un clúster de servicios) que recoge las contribuciones de las apuestas, gestiona los grupos y desencadenantes de las ganancias, calcula la distribución de los premios e inicia los pagos a través del circuito de pago del operador. Se integra con:

con RGS (informes de tasas/resultados y calificaciones), con plataforma/billetera (cobro de contribuciones y crédito de ganancias), con agregador (routing de múltiples estudios/marcas), con BI/regulador (telemetría e informes).

2) Tipos de botes (y lo que cambia en la API)

1. Fijo (Fixed): cantidad de premio de antemano conocida. No hay grupo en la API, sólo verificación de condiciones y crédito.

2. Progresivo (Progressive): el grupo crece a partir de las contribuciones de las apuestas. Se necesitan endpoints de contribución y publicación del tamaño actual.

3. Multinivel (Multi-tier: Mini/Major/Grand): varias agrupaciones paralelas con diferentes posibilidades y capas.

4. Local vs red: grupo local - en un solo operador/marca; networking: resumen de múltiples operadores/marcas/regiones (la multitenencia y la replicación son críticas).

5. Temporal/Evento: Una piscina con una línea de tiempo o programada (se necesitan temporizadores y sorteos automáticos).

3) Invariantes monetarios

La fuente de la verdad en el balance es el monedero/ledger de la plataforma. JP sólo almacena el estado de las agrupaciones y las obligaciones.

Todas las transacciones monetarias son idempotentes (claves 'jp _ contrib _ id', 'jp _ trigger _ id', 'jp _ payout _ id').

«Pagos perdidos/duplicados» = 0. Las compensaciones son solo por eventos (sagas), no por revisiones manuales de la DB.

Comparta la contribución (contribution), el disparador (trigger) y el pago (payout) como transacciones independientes con su propia telemetría.

4) Contratos de referencia API

4. 1 RGS/agregador → JP (contribuciones y disparadores)

'POST/v1/jp/contributions' - contabilidad de la contribución al grupo

json
{
"jp_contrib_id": "uuid-1",  "tenant_id": "brand-42",  "pool_id": "grand-eu-01",  "player_id": "p_abc",  "game_id": "studio:slot_777",  "round_id": "r_123",  "bet": {"amount": 2. 00, "currency": "EUR"},  "contrib": {"amount": 0. 02, "currency": "EUR"},  "occurred_at": "2025-10-23T15:12:05Z",  "idempotency_key": "round_r_123"
}

'POST/v1/jp/candidates' - Solicitud de participación/verificación de condiciones (opcional)

Respuesta: 'elegible: true/false', peso o azar, reglas.

'POST/v1/jp/triggers' - confirmación del hecho de activación

json
{
"jp_trigger_id": "uuid-2",  "pool_id": "grand-eu-01",  "reason": "random_hit",  "selector": {"player_id": "p_abc", "round_id": "r_123"},  "occurred_at": "2025-10-23T15:12:06Z",  "idempotency_key": "jp_t_grand_r_123"
}

💡 Nota: en algunos modelos, el iniciador del disparador es el propio JP (ruleta interna), y el RGS solo informa de la ronda. Entonces los 'triggers' son llamados JP→platforma y RGS se suscribe al evento.

4. 2 JP → plataforma (pagos/reservas)

'POST/v1/wallet/reserve' - (opcional) reserva para el pago futuro

'POST/v1/wallet/credit' - el crédito de ganar al jugador

json
{
"jp_payout_id": "uuid-3",  "tenant_id": "brand-42",  "player_id": "p_abc",  "pool_id": "grand-eu-01",  "amount": {"amount": 500000. 00, "currency": "EUR"},  "meta": {"tax": "withheld=false", "tier": "grand"},  "idempotency_key": "jp_p_grand_r_123"
}

Respuestas de Platfom: 'credit. ok	falled ', con códigos de causa (RG/AML, límites de retirada, sanciones, geo-bloque).

4. 3 Publicación del estado de la agrupación (para frentes/widgets)

'GET/v1/jp/pools/{ pool _ id}' → tamaño actual, seed, cap, número de participantes, ETA, etc.

'GET/v1/jp/pools' → una lista de grupos por marca/región con filtros.

5) Modelo de eventos (Kafka/Pulsar) y esquemas

Topics básicos:

`jp. contribution. recorded`
`jp. pool. updated '(tamaño, actualizaciones competitivas)
`jp. triggered`

`jp. payout. requested	credited	failed`
`wallet. credit. '(espejado para sagas)
`rg. limit. hit`, `aml. alert. opened '(si se bloquea el pago)
`audit. config. changed '(límites, seed, cap, distribución)

Contratos: Avro/JSON Schema + Schema Registry, llaves de lote 'tenant _ id', 'pool _ id', 'player _ id'. Versioning - backward-compatible.

6) Algoritmos desencadenantes (de alto nivel)

Probabilística (p-constante): para cada ronda calificada, generamos hit con probabilidad de 'p' (dependiente del grupo/tipo de nivel).

Rango (must-drop): La piscina está obligada a caer a una cantidad de cap o a un deadline - mantener el random interno en el rango [min, max], publicar cap/ETA.

Control de sid y entropy: seed + per-round salt del servidor; rechazar los asientos del cliente para los jackpots. Todos los cambios de seed están bajo la auditoría WORM.

Honestidad: el desencadenante no debe depender de la identidad específica del jugador (excepto las reglas de geo/licencia/calificación). Cualquier objetivo «personal» es un tabú.

7) SLO y rendimiento

p95 'contribution' <120 ms, p99 <250 ms.

p95 'trigger→credit' <500 ms (sin hopas de pago externas).

«Pagos perdidos/duplicados» = 0 (verificados mediante pruebas contractuales).

Entrega de eventos a BI ≤ 5 minutos.

Disponibilidad de la API de JP para rutas críticas ≥ 99. 95%.

8) Seguridad y cumplimiento

mTLS + firmas (HMAC/EdDSA) en todas las llamadas S2S; tokens de vida corta.

Zero-trust: políticas de red/mesh, privilegios mínimos, segmentación por regiones.

Auditoría WORM de cambios de límites, fórmulas, seed/entropy, configuraciones de agrupaciones.

GDPR/Residencia de Datos/PCI: PII y registros en la región; tokenización de campos sensibles; Prohibición de las lecturas entre regiones.

RG/AML: señales de parada sincrónicas en pago; Las descargas SAR/AMB están automatizadas.

9) Coherencia y sagas

Contribución ('contribution') - Registramos en JP, publicamos 'jp. contribution. recorded`.

Desencadenante ('triggered'): crea un compromiso; JP inicia la saga 'payout'.

Pago ('payout. requested → wallet. credit. ok '): completa la saga; con feil - retrés con deduplicación.

Outbox/CDC es la única ruta de publicación de eventos; No hay loggers «bypass».

10) Telemetría y dashboards

Negocios:

`pool_size`, `contrib_rate`, `avg_contrib_per_bet`, `time_to_drop`, `payouts_count/sum`, `tier_distribution`.

Técnicos:

p50/p95/p99 по `contribution`, `trigger`, `payout`;
error rate с типами (5xx/4xx/business), retry storms, queue lag;
`wallet. credit` latency/ok-rate; conflicto de actualización de pool.

Alertas:

crecimiento 'payout. failed '> X% por marca/región,' pool _ size '> cap - Y% del tiempo (error de configuración), drift entre' pool _ size 'y la cantidad de contribuciones de conciliación> Z ppm.

11) Multitenencia y aislamiento

Todas las solicitudes y eventos están marcados con 'tenant _ id/brand _ id/license/region'.

Las agrupaciones locales/de red se dividen físicamente (DB/cluster) en diferentes licencias/regiones.

Seguridad de nivel de fila (RLS) y enmascaramiento en vitrinas BI.

Claves/secretos individuales y espacios esquemáticos por marca/región.

12) Integración con bonificaciones/torneos

Las contribuciones no aumentan directamente el vager; contribución al bono - viene de la apuesta, no de la contribución.

Los torneos pueden ganar puntos por «participar en JP» o «estar entre los mejores contribuyentes». Fuente - eventos 'jp. contribution. recorded` и `jp. triggered`.

Regla obligatoria: la mecánica del bote no cambia la RTP básica del juego; de lo contrario, se necesita una certificación separada.

13) Pruebas y prácticas de caos

Pruebas contractuales RGS↔JP↔koshelyok: toma-entrega, retrasos, fuera-de-orden, rollback.

Pruebas de carga: tormenta de apuestas y desencadenantes, escalar los workers de la piscina.

Enseñanzas del caos: caída de la región JP, monedero fuera de línea, resincronización del tiempo; verificación de outbox y degradaciones (pause triggers/no new contributions).

14) Hojas de cheques

Para estudio/RGS

Idempotent 'contribution' y los correctos 'round _ id '/' bet _ id'.
No hay publicaciones «omitiendo» transacciones (sólo outbox/CDC).
Pruebas de toma/repetición de desencadenantes/compensaciones.
Los límites max bet/calificaciones se transmiten a JP.

Para operador/plataforma

Ledger es la fuente de la verdad, 'wallet. credit's dedoop.
Los pies RG/AML se procesan en pago; Informes SAR/NAT.
Dashboards p95 'trigger→credit', error de anotación, conciliación de las piscinas.

Para el propietario de JP

Auditoría WORM de cambios de fórmulas/semilla/límites.
Esquemas de eventos en Registry y versioning.
DR: RPO ≤ 5 min, RTO ≤ 30 min; ejercicios regulares.
RLS/aislamiento por marca/licencia; claves/secretos por región.

15) Banderas rojas (anti-patrones)

Correcciones manuales de tamaños de grupos y pagos en DB.

Falta de idempotencia → toma de créditos.

Publicar telemetría sin outbox/CDC → contribuciones/disparadores «perdidos».

Mezcla de PII y datos monetarios de diferentes regiones.

Un bote que afecta a la RTP del juego básico sin una nueva certificación.

No hay soldadura de billetera y piscina; los informes se construyen según el OLTP de combate.

API Jackpot Systems es un contrato de eventos monetarios entre el estudio, la plataforma y el operador. Sus fundamentos son: idempotencia y sagas, duro aislamiento de dinero, esquemas de eventos claros, seguridad y auditoría WORM, observabilidad y SLO. En este diseño, los grupos de fix/progresivos y de red se escalan previsiblemente, los pagos siguen siendo correctos y los informes regulatorios y comerciales son transparentes y fiables.