Como conectar provedores via API: handschake, certificação, sandbox

Texto completo do artigo

💡 18+. O material é de engenharia e aplicação, não um apelo para o jogo. Por «provedor» entendemos RGS/live studio/jackpot/serviço; sob «plataforma» - PAM/carteira/caixa/bônus/RG.

1) Cartão de integração: do pedido à produção

Etapas:

1. Pré-sal e Dê Diligence: advogados, geo/licenças, compatibilidade de conteúdo e políticas RG.

2. Handschake e segurança: emissão de acessos sandbox, compartilhamento de chaves (mTLS/HMAC), registro em Schema Registry.

3. Tecndisine: Confira o modelo de domínio (sessions/bets/senslents/events), idempotidade, códigos de erro.

4. Integração Sandbox: emuladores de carteira/PSP/RG, jogadores de teste, cenários de chuva e dublês.

5. Certificação: testes obrigatórios, assinaturas de protocolos, cargas e malas de caos.

6. Staging/UAT: configs de combate sem dinheiro real, tráfego canário.

7. Go-Live: Companhia de chaves, sinalização de bandeiras, monitoramento de SLO, pós-incidentes.

2) Handschake: autenticação, autorização, rastreamento

2. 1 Troca de segredos e escopos

mTLS (certificados per brand/region) e/ou OAuth2 Clientes Credentals.

A assinatura do corpo da solicitação HMAC/EdDSA (adiciona não-representation).

Скоупы: `sessions:write`, `bets:write`, `settlements:write`, `events:publish`.

2. 2 Títulos obrigatórios

'X-Trace-Id' - Traçado de passagem.

`X-Brand-Id`, `X-Region`, `X-Provider-Id`.

'X-Idempotency-Key' é para todas as operações write.

2. 3 Verificação Health (antes do código)


GET /health
→ 200 {"status":"ok","version":"1. 7. 2","time":"2025-10-23T10:00:00Z"}

3) Sandbox: o que há e como usá-lo

Composição do ambiente:

Emulador de carteira ('/wallet/debit	credit	rollback ') com idimpotência e atrasos.
Ganchos RG ('/rg/check ',' rg. limit. hit ') e perfis de teste (auto-exclusão/limites).
Falso agregador/jackpot para contribuições/desencadeadores.
Fake KYC/AML respostas (allow/deny/pending).
Pneu de evento (Kafka/Pulsar) com top de teste e Schema Registry.

Harmonia com a realidade:

Versões similares de circuitos e rate limits que são vendidos.
Tempo-espelho, duplicações de entrega, out-of-order - incorporados por botões de emulação.

Conjunto de jogadores de teste/moedas:


p_demo_1 (EUR), p_demo_2 (USD), p_blocked_rg (denied), p_low_balance

4) Modelo de recursos e contrato mínimo

4. 1 Criação de sessão


POST /v1/sessions
{
"player_id":"p_demo_1",  "game_id":"studio:slot_forge_02",  "currency":"EUR",  "locale":"de-DE"
}
→ 201 {"session_id":"s_456","expires_at":"2025-10-23T19:10:00Z"}

4. 2 Permissão de aposta (hold)


POST /v1/bets/authorize
Headers: X-Idempotency-Key: bet_r_8c12_1
{
"session_id":"s_456",  "bet_id":"b_001",  "round_id":"r_8c12",  "amount":{"amount":2. 00,"currency":"EUR"}
}
→ 200 {"status":"authorized","hold_id":"h_zz1"}

4. 3 Setlent (resultado da rodada)


POST /v1/bets/settle
Headers: X-Idempotency-Key: settle_r_8c12_1
{
"bet_id":"b_001",  "round_id":"r_8c12",  "win":{"amount":14. 60,"currency":"EUR"},  "bonus_state":{"in_bonus":true,"freespins_left":7}
}
→ 200 {"status":"credited","settlement_id":"st_77"}

4. 4 Erros (esquema único)


409
{"code":"DUPLICATE","message":"Bet already authorized","retryable":false,"trace_id":"tr_a1b2"}

5) Eventos e esquemas: sem isso, não se pode certificar

Topics básicos:

`session. started	ended`, `bet. authorized	settled	rolled_back`, `bonus. issued	consumed`, `wager. progress. updated`, `wallet. debit.`, `wallet. credit.`, `rg. limit. hit`, `rg. reality_check`.

Exemplo de Avro/JSON Schema (fatia 'bet. settled`):

json
{
"event_type":"bet. settled",  "schema_version":"1. 2. 0",  "event_id":"uuid",  "occurred_at":"2025-10-23T16:21:05Z",  "tenant_id":"brand-7",  "region":"EU",  "player_id":"p_demo_1",  "trace_id":"tr_a1b2",  "payload":{
"round_id":"r_8c12",   "bet":{"amount":1. 00,"currency":"EUR"},   "win":{"amount":14. 60,"currency":"EUR"},   "in_bonus":true
},  "idempotency_key":"bet_r_8c12_1"
}

Regras: evolução backward-compatível, teste de duplicação e eventos tardios, particionamento por 'tenant _ id/player _ id'.

6) Certificação de integração: exatamente o que é verificado

6. 1 Cenários funcionais (mínimo)

A repetição da solicitação 'autorize/massle' com o mesmo 'X-Idempotency-Key' → a mesma resposta.

Out-of-order: Veio 'setle' sem 'athorize' → falha correta.

Cadeias Rollback na queda da carteira/rede.

Pés RG: auto-exclusão/limite de perda/tempo → proibir a taxa.

Bónus/vager: contribuição por tipo de jogo, max bet, dedline.

6. 2 Cargas de carga

p95 'bet/setle' nos orçamentos (por exemplo, '<200-300 ms'), sem «tempestades» de retais.

Os fluxos de eventos chegam a BI ≤ 5 min.

6. 3 Malas de caos

Dobly entregas, atrasos de outbox/CDC, «largar» a região, setlent parcial.

6. 4 Documentos de resultado

Protocolo de testes com temporizadores/trace-id.

Relatório SLO (latency/erro/lag).

Resumo de segurança (chaves, rotações, acessíveis, Vault/HSM).

7) Versiação e migração

HTTP: '/v1/... 'no caminho, eventos:' schema _ versão 'no corpo.

SemVer: menor - adição de campos opcionais; major - apenas através do novo prefixo '/v2/'.

Deprecation headers: 'Deprecation', 'Sunset', espelho de uso em dashbord.

Porta-bandeiras: «carta dupla» de eventos («v1» e «v2») na transição.

8) Segurança e conformidade

mTLS + assinaturas S2S, tokens curtos, caixas limitadas.

Zero-trust: políticas de rede, per-brand/region chaves.

Data residency & PII: armazenamento e logs na região; RLS/camuflagem.

Auditoria WORM: alterações nos limites, perfis RTP, jackpot configs.

RG/AML: sinalizações de stop sincronizadas na taxa/pagamento; Relatório SAR/TR.

9) Saída em proda: lista de controle de lançamento

Antes de ativar o tráfego

Rotação de segredos sandbox → chaves prod.

Estão incluídos os p95/p99, error-rate, queue-lag, setle-lag.

Alertas SLO: breach latency/erro/lag, surto 'DUPLICATE/IDEMPOTENCY _ MISMATCH'.

Plano DR.: RPO ≤ 5 min, RTO ≤ 30 min; «botão vermelho» - parar novas sessões.

Canário

1 a 5% do público/jogos/geo; rollback automático em violação do SLO.

Monitorização pós-24-72 horas, verificação de legers/relatórios.

10) Anti-pattern (bandeiras vermelhas)

Publicar eventos contornando outbox/CDC.

Falta de 'X-Idempotency-Key' nas operações write.

Edição manual de balanços/setlems na base de dados.

Chaves unificadas para várias marcas/regiões.

BI e relatórios regulatórios acima da base de combate OLTP.

Degradação zero, a queda do provedor está a vazar a carteira/plataforma.

11) Folhas de cheque

Para o provedor

Envio 'X-Trace-Id' e 'X-Idempotency-Key' sempre.
Apoio a repetição com a mesma chave sem efeitos colaterais.
Publico eventos sobre esquemas do Registry; guardo 'schema _ version'.
Implementação de retraias com backoff e dedução.
Os estoques RG e os limites de bónus são cumpridos no real-time.
Acessíveis e segredos - per brand/region, rotação configurada.

Para a plataforma

Outbox/CDC em todos os caminhos de dinheiro; traçado end-to-end.
SLO-dashboard: p95/99, erro-rate, queue-lag, setle-lag.
Deprecation/Processo Sunset, carta dupla de eventos nas migrações.
Dr./xaoc-exercício, gerenciamento de incidente e pós-mortem.
Modos de degradação: 'no new sessions', desativação da promoção/jackpot.

12) Exemplo de playbook «mínimo» de integração (TL; DR)

1. Assinar NDA/contrato → emitir acessos sandbox e esquemas.

2. Trocar certificados mTLS/HMAC; iniciar 'provider _ id'.

3. Concordar com os endpoint mínimos de 'sessions', 'bets/autorize', 'bets/massle', 'rollback'.

4. Conectar-se ao pneu Sandbox e ao Registry; Tirar as malas funcionais/caos.

5. Entregar o protocolo de certificação: logs, trace-id, relatório SLO.

6. Mudar as chaves para a proda, ligar o canário, observar o SLO.

7. Inscrever as métricas pós-lançamento e «lições» em changelog.

A conexão com sucesso do provedor não é apenas uma API, mas um processo controlado: handschake seguro, sandbox realista, certificação rigorosa, observabilidade e regras claras de compatibilidade. Seguindo os invariantes descritos (idempotidade, outbox/CDC, RG/AML stops, SLO e DR), você acelera a integração, evita incidentes monetários e obtém lançamentos previsíveis - sem surpresas para jogadores, reguladores e empresas.