Guia de integração de GambleHub

1) Visão e modelo de interação

• Provedor API: você chama API GambleHub (carteira, bônus, relatórios).
• Fornecedor externo: Chamamos seus webhooks/endpoint (balanço, transações, KYC).

1. Edge/API (REST/gRPC, Webhooks)

2. Eventos (event ônibus: apostas/pagamentos/carteira/CUS)

3. Relatórios (API + exportação S3/SFTP)

4. Operações (incidentes, SLO, crédito SLA)

2) Ambientes, domínios e IP

A SLA contratual é fixada no contrato. As atualizações do IP são publicadas com antecedência. Autorize o Allowlist.

3) Autenticação e autorização

• OAUTh2 Clientes Credentals: servidor-a-servidor ('scope' - 'wallet: read', 'wallet: write', 'bet: write', 'relatório: read').
• JWT (issuer = GambleHub): assinatura RS256, chaves no endpoint JWKS.
• mTLS: Autenticação TLS mútua no nível ingress (a pedido da complacência).

POST /oauth2/token grant_type=client_credentials&scope=wallet:write bet:write
→ { "access_token": "...", "token_type": "Bearer", "expires_in": 3600 }

Os scopes são verificados em cada chamada. As transações de alto risco (pagamento) utilizam um scope individual e, opcionalmente, um vínculo IP/ASN.

4) Versionização e compatibilidade

Caminho: '/v1/... ', '/v2/...' (a versão major não é compatível para trás).
Alterações menores e extensivas - através da extensão do esquema (novos campos opcionais).
Depressões, 90 dias com aviso.
Os webhooks são versionizados em «X-GH-Event-Version: 1».

5) Limites, quotas e idimpotência

• `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
• 429 volta com 'Retry-After' (segundos).
• Todos os métodos inseguros exigem 'Idempotency-Key' (TTL 24-72 h). A repetição de uma consulta idêntica devolve o resultado original ('409 IDEMP _ REPLAY' em um conflito).

6) Padrões de erro

json
{
"type": "https://docs. gamblehub. io/errors/validation_failed",
"title": "Validation failed",
"status": 422,
"error_code": "VAL_001",
"trace_id": "a1b2c3...",
"retriable": false,
"errors": [{"field":"amount","code":"min","message":"Must be >= 1"}]
}

Retriable: 5xx/503/504/429 (с `Retry-After`). Non-retriable: 400/401/403/404/409/422/410/415/412.

7) Circuitos de dados (núcleo)

7. 1 Jogador

json
{
"player_id": "p_123",
"country": "CA",
"currency": "CAD",
"rg_flags": {"self_excluded": false, "limits": {"daily_loss": 100}},
"kyc_status": "verified    pending    failed"
}

7. 2 Sessão

json
{
"session_id": "s_789",
"player_id": "p_123",
"started_at": "2025-11-03T17:55:00Z",
"ip": "203. 0. 113. 5",
"device": {"ua":"...", "os":"Android", "model":"..."}
}

7. 3 Carteira/transação

json
{
"txn_id": "t_001",
"player_id": "p_123",
"type": "deposit    withdrawal    bet    win    bonus    adjustment",
"amount": "12. 34",
"currency": "EUR",
"balance_after": "123. 45",
"metadata": {"provider":"psp_x","request_id":"r_456"}
}

7. 4 Taxa/pagamento

json
{
"bet_id": "b_456",
"player_id": "p_123",
"game_id": "g_777",
"stake": "1. 50",
"currency": "EUR",
"placed_at": "2025-11-03T17:58:10Z",
"round_id": "rnd_aa1",
"provider": "StudioX"
}

json
{
"settlement_id": "st_456",
"bet_id": "b_456",
"win_amount": "3. 75",
"settled_at": "2025-11-03T17:59:02Z",
"outcome": "win    lose    void"
}

7. 5 Bónus

json
{
"bonus_id": "bo_900",
"player_id": "p_123",
"type": "freespin    cash    wagered",
"state": "issued    active    expired    consumed",
"wagering": {"target": "100. 00","progress":"45. 20","currency":"EUR"}
}

8) RESTAPI (fatias de OpenAPI)

yaml paths:
/v1/wallet/balance/{player_id}:
get:
summary: Get wallet balance security: [{ oauth2: [wallet:read] }]
responses:
'200': { description: OK }
'401': { $ref: '#/components/responses/Problem' }
'404': { $ref: '#/components/responses/Problem' }

/v1/wallet/transactions:
post:
summary: Create wallet transaction security: [{ oauth2: [wallet:write] }]
parameters:
- name: Idempotency-Key in: header required: true schema: { type: string }
responses:
'201': { description: Created }
'409': { $ref: '#/components/responses/Problem' }
'422': { $ref: '#/components/responses/Problem' }

/v1/bets:
post:
summary: Register bet security: [{ oauth2: [bet:write] }]
responses:
'201': { description: Created }
'422': { $ref: '#/components/responses/Problem' }

9) Webhooks (de GambleHub para parceiro)

• `X-GH-Event`: `player. created|session. started|bet. placed|bet. settled|wallet. changed|kyc. updated|rg. flagged`
• 'X-GH-Evento-ID': UUID único
• `X-GH-Signature`: `sha256=`
• 'X-GH-Retry': tentativa nº
• `X-GH-Event-Version`: `1`

json
{
"event": "bet. settled",
"occurred_at": "2025-11-03T18:00:12Z",
"data": {
"settlement_id": "st_456",
"bet_id": "b_456",
"player_id": "p_123",
"win_amount": "3. 75",
"currency": "EUR",
"outcome": "win"
}
}

Resposta do anfitrião - apenas 2xx é considerado um sucesso. Senão, retraí: backoff exponencial (1s, 3s, 10s, 30s, 2m, 10m, 30m; no máximo 24 horas). Use «X-GH-Event-Id» para deduzir.

text expected = base64(hmac_sha256(request_body, SHARED_SECRET))
header  = split(X-GH-Signature, '=')[1]
assert header == expected

10) Ordem do fluxo de dinheiro (Wallet flow)

1. deposit (PSP → wallet. credit)

2. bet (hold/authorize или direct debit)

3. settlement (release hold; `win`/`lose`/`void`)

4. withdrawal (wallet. debit → PSP)

Os balanços hold e multi-carteiras (reais/bónus) são suportados.

11) Caixa de areia e cenários de teste

Jogadores de teste: 'p _ sbx _', moeda 'EUR' USD 'CAD'.
Os provedores de jogos emulam: win/lose/void, desonerações, atrasos.
KYC sandbox: respostas 'verificed' failed 'review' por modelos de passaporte.
PSP sandbox: статусы `authorized|captured|declined|reversed`.

• Stavka→vyplata→sverka de equilíbrio
• Reverter/Void round
• Idempotency para aposta repetida
• Falha no webhook com retais e posterior dedução
• 429 e correto 'Retry-After'
• 5xx com backoff exponencial do lado do cliente

12) Acertos e relatórios

Reconciliation API

yaml
GET /v1/reports/reconciliation? from=...&to=...&scope=wallet    bets
→ CSV/JSON: { player_id, bet_id, stake, win, currency, balance_delta, provider }

Resumos diários: rotação, GGR/NGP, provedores, corte de geo/moeda.
Exportar: S3/SFTP com manifestos e arquivos assinados (SHA256).
Timzon de relatórios: UTC (a não ser que o contrato especifique outra coisa).

13) Observabilidade e SLO

SLI: API de sucesso ≥ 99. 95% (28d), p95 latency para métodos críticos, sucesso na entrega de webhooks.
Burn-alerts (fast/slow) por um orçamento errado.
Correlação Trace: 'trace _ id' nas respostas/logs, drilldown nas pistas.
Página de status: componentes Edge, Wallet, Bets, Webhooks, PSP, KYC.

14) Segurança e complacência

Minimização PII; O PAN/segredos em logs/webhooks são proibidos.
Gestão de segredo e rotação de chaves.
RG - As bandeiras de auto-exclusão/limite devem resultar em uma falha automática nas taxas/pagamentos.
AML/KYC: eventos 'kyc. updated`, `aml. alert 'disponíveis por assinatura; toma decisões no seu sistema ou através do nosso módulo.
GDPR/DSAR: endpoint para descarga/remoção de dados pessoais do jogador por solicitação legal.
mTLS e HSTS estão incluídos padrão no ambiente prod.

15) Desempenho e quotas

• RPS: 50 (burst 100)
• Concurrent webhooks: 10
• Tamanho do corpo: ≤ 256 KB (eventos de jogo), ≤ 64 KB (carteira)

Peça um upgrade de plano por meio de sua conta-gerente, indicando a previsão de RPS/volume.

16) Gerenciamento de alterações e lançamentos

Mudança windows: agendamento programado, aviso ≥ 5 dias úteis.
Migração de versões: dual-write/dual-read durante o período de transição.
Testes Contracto no CI: esquema JSON, campos obrigatórios, estáveis 'erro _ código'.
Canary: ativação gradual do tráfego para novas fichas.

17) Certificação de integração (Check-list)

• Inscrição de apostas/pagamentos/void
• Idempotidade em todos os write-endpoentes
• Processamento correto 429/5xx + backoff
• Comprovação de assinatura de webhooks, dedução por 'X-GH-Event-Id'
• Ajuste de balanço após uma série de eventos (win/lose)
• Relatórios de reconciação coincidem com seus dados

• Retratos de webhooks implementados
• Timeouts clientes ≤ 10s, tentativa geral ≤ 30s
• Circuito-breaker dependente

• Armazenamento de segredos no gestor de segredos
• Redação PII em logs
• Bandeiras RG/AML são contabilizadas em tempo real

18) Cenários frequentemente usados

18. 1 Inscrição de taxa com Idumpotência

POST /v1/bets
Idempotency-Key: bet-p_123-rnd_aa1-1

{ "player_id":"p_123","game_id":"g_777","stake":"1. 50","currency":"EUR","round_id":"rnd_aa1" }
→ 201 Created { "bet_id":"b_456" }

18. 2 Webhook feel seguido de sucesso

1. Seu servidor não está disponível → 5xx → retrai por backoff.
2. Depois de restaurado - aceita o mesmo 'X-GH-Event-Id' → deve ignorar os duplicados.

18. 3 Degradação parcial do provedor

Vamos devolver 503; repita com backoff.
Quando a degradação é prolongada, a marcação para parar do provedor e a inserção do smart-routing (se no contrato).

19) DevEx e suporte

Portal: chaves, usage, webhooks, logs de entrega, dashboard SLO, exportação de relatórios.
Webhooks replay: reaproveitamento por faixa de data/ID.
Incidentes: auto-criação de tíquete, war-room, pós-mortem de ≤ 48 h por SEC-1.
Comunicações: # partners-status/e-mail on-call 24 x 7 (Enterprise).

20) Plano de rolagem (2-4 semanas)

1. Semana 1: emissão de chaves, conexão sandbox, cenários básicos (aposta/pagamento/carteira).
2. Semana 2: webhooks e controladores, bandeiras RG/KYC, testes de carga, 429/5xx comportamento.
3. Semana 3: relatórios (recepção, descarga), segurança (assinaturas, segredos), contrato-teste.
4. Semana 4: certificação, inclusão canary em venda, monitoramento, matriz de contatos.

21) Mini-FAQ

Posso gRPC?
Sim, a pedido; O mapping de códigos de erro HTTP é fornecido na especificação.

Como arranjar dados retráteis?
Por meio de relatórios de 'reconciação' (datas de 'from/to') ou S3/SFTP de descarga.

Como aumentar os limites?
Por meio de um portal/conta de gerente, indicando RPS/concorrência.

O que achar a fonte da verdade do equilíbrio?
Diário de carteira de transação GambleHub + Reposição diária.

Resultado

A integração com o GambleHub é baseada em um contrato claro: APIs estáveis e esquemas, webhooks assinados, idempotação e retraí, limites e relatórios transparentes, além de requisitos de segurança e complacência. Seguindo esta orientação e as folhas de cheque da certificação, você rapidamente entrará na base, garantindo fluxos de dinheiro confiáveis e relatórios alinhados sem discrepâncias.