Como funciona o sistema de jackpot API

Texto completo do artigo

💡 18+. O material é de engenharia e aplicação, sem apelo para o jogo. Termos: plataforma - PAM/carteira/caixa/bônus/RG; RGS - Remote Game Server (núcleo de jogos do estúdio); agregador - camada unificada para muitos RGS; JP é um serviço de jackpot.

1) O que é o sistema de jackpot e onde está no ecossistema

O sistema de jackpot é um serviço separado (por vezes, um cluster de serviços) que recolhe contribuições de apostas, gerencia pool e trigores de ganhos, calcula a distribuição de prêmios e inicia pagamentos através do circuito de pagamento da operadora. Integra-se:

com RGS (relatos de taxas/resultados e qualificações), plataforma/carteira (cancelamento de contribuições e empréstimo de ganhos), agregador (roting de vários estúdios/marcas), BI/regulador (telemetria e relatórios).

2) Tipos de jackpot (e o que muda na API)

1. Fixo (Fixed): valor pré-conhecido do prémio. Não há pulo na API, apenas verificação de condições e crédito.

2. Progressivo: o pool cresce com as taxas de contribuição. Precisamos de endpoints de contribuição e publicações do tamanho atual.

3. Multiplicidade (Multi-tier: Mini/Major/Grand): Várias poulas paralelas com diferentes possibilidades e capas.

4. Local vs rede: pool local - em uma única operadora/marca; a rede - total de operadoras/marcas/regiões (multiplicidade e replicação são críticas).

5. Tempo/iwent: pool com deadline ou agendado (é necessário tempo e brincadeiras automáticas).

3) Invariantes em dinheiro

A fonte de verdade do balanço é a plataforma de carteira/ledger. O JP só guarda a condição de pool e obrigação.

Todas as transações em dinheiro são idempotentes (chaves 'jp _ contreb _ id', 'jp _ trigger _ id', 'jp _ payout _ id').

«Pagamentos perdidos/duplicados» = 0. As compensações são apenas por eventos (sagas), não por versões manuais do banco de dados.

Divida a contribuição (provision), o desencadeador (trigger) e o pagamento (payout) como transações independentes com sua própria telemetria.

4) Contratos de referência API

4. 1 RGS/agregador → JP (contribuições e desencadeadores)

'POST/v1/jp/contribuições' - Conta a contribuição do pool

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' - pedido de participação/verificação de condições (opcional)

Resposta: 'eligível: true/falso', peso ou chance, regras.

'POST/v1/jp/triggers' - fixação do fato de ativação

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: Em alguns modelos, o desencadeador é iniciado pelo próprio JP (roleta interna) e o RGS apenas informa sobre a rodada. Então os 'triggers' são chamados e o RGS é assinado para o evento.

4. 2 plataforma → JP (pagamentos/reservas)

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

'POST/v1/wallet/credit' - crédito ganho ao jogador

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

As respostas do platom são 'credit. ok	failed ', com códigos de causa (RG/AML, limites de saída, sanções, geo-bloco).

4. 3 Publicar status do pool (para frentes/widgets)

'GET/v1/jp/pools/1962 pool _ id a.' → tamanho atual, seed, kap, número de participantes, ETA etc.

'GET/v1/jp/pools' → uma lista de pool por marca/região com filtros.

5) Modelo de evento (Kafka/Pulsar) e circuitos

Topics básicos:

`jp. contribution. recorded`
`jp. pool. updated '(tamanho, atualizações competitivas)
`jp. triggered`

`jp. payout. requested	credited	failed`
`wallet. credit. '(espelhamento para sagas)
`rg. limit. hit`, `aml. alert. opened '(se o pagamento for bloqueado)
`audit. config. changed '(limites, seed, cap, distribuição)

Contratos: Avro/JSON School + School Registry, chaves de partilha 'tenant _ id', 'pool _ id', 'player _ id'. Versioning - backward-compatível.

6) Algoritmos de desencadeador (de alto nível)

Provável (p-sustentável): Para cada rodada qualificada, geramos hit com probabilidade de 'p' (dependente do pulo/tipo de nível).

Faixa (must-drop): o pool é obrigado a cair para uma soma de cap ou deadline - mantendo o random interno na faixa [min, max] e publicando cap/ETA.

Gerenciamento de side e entropy: seed + per-round salt servidor; a rejeição de cidos de clientes para jackpots. Todas as alterações de seed estão sob áudio WORM.

Honestidade: O desencadeador não deve depender da personalidade específica do jogador (exceto as regras geo/licença/qualificação). Qualquer meta pessoal é tabu.

7) SLO e desempenho

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

p95 'n' <500 ms (sem hop de pagamento externo).

«Pagamentos perdidos/duplicados» = 0 (verificado por testes contratuais).

Entrega de eventos BI ≤ 5 min

Disponibilidade da API JP para caminhos críticos ≥ 99. 95%.

8) Segurança e Complacência

mTLS + assinaturas (HMAC/EdDSA) em todas as chamadas S2S; Tocas curtas.

Zero-trust: políticas de rede/mesh, privilégios mínimos, segmentação por região.

A auditoria WORM de alterações de limites, fórmulas, seed/entropy, configs de pool.

GDPR/Data residency/PCI: PII e logs - na região; localização de campos sensíveis; a proibição das leituras cruzadas-regionais.

RG/AML: sinalizações de stop sincronizadas para pagamento; Os descarregamentos SAR/TR são automatizados.

9) Coerência e sagas

A contribuição ('sustentation') é registrada no JP, publicamos 'jp. contribution. recorded`.

«Triggered» - cria um compromisso; JP está lançando a saga 'payout'.

Pagamento ('payout. requested → wallet. credit. ok ') - completa a saga; no feel, retraí com dedução.

Outbox/CDC é o único caminho para publicar eventos; Não há loggers «contornados».

10) Telemetria e dashboards

Negócios:

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

Técnica:

p50/p95/p99 по `contribution`, `trigger`, `payout`;
error rate с типами (5xx/4xx/business), retry storms, queue lag;
`wallet. credit` latency/ok-rate; A atualização do pool é conflituosa.

Alerts:

altura 'payout. failed '> X% por marca/região,' pool _ size '> cap - Y% de tempo (erro de configuração), drivt entre' pool _ size 'e soma de contribuições de conciliação> Z ppm.

11) Multiplicidade e isolamento

Todas as solicitações e eventos estão marcados 'tenant _ id/brand _ id/license/region'.

Os poóis de rede/local estão divididos fisicamente (DB/cluster) em diferentes licenças/regiões.

Segurança de Row-level (RLS) e camuflagem em vitrines BI.

Chaves/segredos individuais e espaços esquemáticos para marca/região.

12) Integração com bónus/torneios

As contribuições não aumentam diretamente o vager; A contribuição para o bónus vem de uma aposta, não de uma contribuição.

Os torneios podem somar pontos por «participação em JP» ou «entrada no topo dos depósitos». A origem são os eventos 'jp. contribution. recorded` и `jp. triggered`.

Regra obrigatória: o jackpot mecânico não altera o jogo RTP básico; senão precisamos de uma certificação separada.

13) Testes e práticas de caos

Os testes contratuais são: filmagem, atrasos, out-of-order, rollback.

Testes de carga: tempestade de apostas e desencadeadores, zoom de pool.

Ensinamentos de caos: queda da região de JP, carteira offline, relocalização do tempo; verificação de outbox e degradações (pause triggers/no new contributions).

14) Folhas de cheque

Para estúdio/RGS

Idempotentes 'sustentation' e corretas 'round _ id '/' bet _ id'.
Não há publicações «contornando» transações (somente outbox/CDC).
Testes de duplicação/reaproveitamento/compensação.
Os limites de max bet/qualificação são transferidos para JP.

Para operador/plataforma

Ledger é a fonte da verdade, 'wallet. credit 'com dedups.
Os estoques RG/AML são processados no pagamento; relatórios SAR/TR.
Dashboard p95 'trigger→credit', erro rate, confecção de pool.

Para dono de JP

Auditoria WORM de alterações de fórmulas/seed/limites.
Esquemas de eventos do Registry e versioning.
DR.: RPO ≤ 5 min, RTO ≤ 30 min; exercícios regulares.
RLS/isolamento de marcas/licenças; chaves/segredos per region.

15) Bandeiras vermelhas (anti-pattern)

Redimensionamentos manuais de pool e pagamento em banco de dados.

Falta de Idempotação → duplicação de crédito.

Publicar telemetria sem outbox/CDC → contribuições/desencadeadores «perdidos».

Mistura de PII e dados monetários de diferentes regiões.

Jackpot que afeta o jogo básico RTP sem uma nova certificação.

Sem carteira e pula; os relatórios são baseados no OLTP de combate.

A API de sistemas de jackpot é um contrato monetário entre o estúdio, a plataforma e a operadora. As suas fundações são idemotismo e sagas, isolamento de dinheiro, esquemas de eventos claros, segurança e auditoria WORM, observabilidade e SLO. Com este design, os pools progressivos e de rede são escalados de forma previsível, os pagamentos permanecem corretos e os relatórios regulatórios e empresariais são transparentes e confiáveis.