Guía de integración de GambleHub

1) Revisión y modelo de interacción

• Proveedor de API: usted llama a la API de GambleHub (billetera, bonos, informes).
• Proveedor externo: llamamos a sus webhooks/endpoints (balance, transacciones, KYC).

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

2. Eventos (bus de eventos: apuestas/pagos/billetera/CUS)

3. Informes (API + exportación S3/SFTP)

4. Operaciones (incidentes, SLO, préstamos SLA)

2) Entornos, dominios y IP

El SLA contractual se fija en el contrato. Las actualizaciones de IP se publican con suficiente antelación. Permitir Allowlist.

3) Autenticación y autorización

• OAuth2 Credenciales del cliente: servidor a servidor ('scope' -s: 'wallet: read', 'wallet: write', 'bet: write', 'report: read').
• JWT (issuer = GambleHub): firma RS256, claves en JWKS endpoint.
• mTLS: autenticación TLS recíproca a nivel de ingreso (bajo petición de cumplimiento).

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

Los scopes se comprueban en cada llamada. Para operaciones de alto riesgo (pagos) se utiliza el paso a paso: un scope separado y, opcionalmente, un enlace IP/ASN.

4) Versificación e interoperabilidad

Ruta: '/v1/... ', '/v2/...' (la versión mayor es incompatible hacia atrás).
Cambios menores y extensibles - a través de la extensión del esquema (nuevos campos opcionales).
Deprecaciones - 90 días con la notificación.
Los webhooks se versionan con el título 'X-GH-Event-Version: 1'.

5) Límites, cuotas e idempotencia

• `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
• El 429 regresa con 'Retry-After' (segundos).
• Todos los métodos inseguros requieren 'Idempotency-Key' (TTL 24-72 h). La repetición de una consulta idéntica devuelve el resultado original ('409 IDEMP_REPLAY' en caso de conflicto).

6) Normas de error

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) Esquemas de datos (núcleo)

7. 1 Jugador

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 Período de sesiones

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 Monedero/transacciones

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 Tasa/Pago

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 Bono

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) APROX API (fragmentos 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 a un socio)

• `X-GH-Event`: `player. created|session. started|bet. placed|bet. settled|wallet. changed|kyc. updated|rg. flagged`
• 'X-GH-Event-Id': UUID único
• `X-GH-Signature`: `sha256=`
• 'X-GH-Retry': intento No
• `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"
}
}

Respuesta del anfitrión - sólo 2xx se considera un éxito. De lo contrario, son retraídas: retroceso exponencial (1s, 3s, 10s, 30s, 2m, 10m, 30m; máximo 24 horas). Para la deduplicación, utilice 'X-GH-Event-Id'.

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

10) Orden de flujo de efectivo (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)

Se admiten balances hold y multi-billeteras (reales/bonus).

11) Sandbox y escenarios de prueba

Jugadores de prueba: 'p _ sbx _', monedas 'EUR' USD 'CAD'.
Los proveedores de juegos emulan: win/lose/void, descuentos, retrasos.
KYC sandbox: respuestas 'verified' failed 'por plantillas de pasaportes.
PSP sandbox: статусы `authorized|captured|declined|reversed`.

• Stavka→vyplata→sverka de balance
• Vuelta/void ronda
• Idempotencia al volver a apostar
• Fallo del webhook con retraídas y posterior deduplicación
• 429 y correcto 'Retry-After'
• 5xx con backoff exponencial en el lado del cliente

12) Conciliación y presentación de informes

Reconciliation API

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

Resumen diario: revoluciones, GGR/NGP, proveedores, corte por geo/divisas.
Exportación: S3/SFTP con los manifiestos firmados y los hashes de archivo (SHA256).
Informes de tiempo: UTC (a menos que se especifique lo contrario en el contrato).

13) Observabilidad y SLO

SLI: éxito de la API ≥ 99. 95% (28d), p95 latencia para métodos críticos, éxito en la entrega de webhooks.
Burn-alerts (fast/slow) por un presupuesto erróneo.
Correlación trace: 'trace _ id' en respuestas/logs, drilldown a tracks.
Página de estado: componentes Edge, Wallet, Bets, Webhooks, PSP, KYC.

14) Seguridad y cumplimiento

PII-minimización; PAN/secretos prohibidos en logs/webhooks.
Administración secreta y rotación de claves.
RG (Responsible Gambling): las banderas de autoexclusión/límites deben dar lugar a una denegación automática de apuestas/pagos.
AML/KYC: eventos 'kyc. updated`, `aml. alert 'están disponibles por suscripción; toma decisiones en su sistema, ya sea a través de nuestro módulo.
GDPR/DSAR: endpoints para descargar/eliminar datos personales del jugador a petición legal.
mTLS y HSTS están habilitados de forma predeterminada en el entorno prod.

15) Productividad y cuotas

• RPS: 50 (burst 100)
• Concurrent webhooks: 10
• Tamaño del cuerpo: ≤ 256 KB (eventos de juego), ≤ 64 KB (billetera)

Solicite una actualización del plan a través del gestor de cuentas, indicando la previsión de RPS/volúmenes.

16) Gestión de cambios y lanzamientos

Cambiar Windows: trabajo programado - programado, notificación ≥ 5 días hábiles.
Migraciones de versión: dual-write/dual-read durante el período de transición.
Pruebas de contrato en CI: esquema JSON, campos obligatorios, estable 'error _ code'.
Canarias: incorporación gradual del tráfico para los nuevos fiches.

17) Certificación de integración (Check-list)

• Registro de apuestas/pagos/void
• Idempotencia en todos los endpoints write
• Tratamiento correcto 429/5xx + backoff
• Verificación de la firma de webhooks, deduplicación por 'X-GH-Event-Id'
• Conciliación del balance después de una serie de eventos (ganar/perder)
• Los informes de reconciliación convergen con sus datos

• Retraídas de webhooks realizadas
• Timeout de los clientes ≤ 10s, intento total ≤ 30s
• Circuit-breaker en las dependencias

• Guardar secretos en el gestor de secretos
• Edición PII en logs
• Las banderas RG/AML se contabilizan en tiempo real

18) Scripts de uso frecuente

18. 1 Registro de la apuesta con idempotencia

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 Fail webhook seguido de éxito

1. Su servidor no está disponible → 5xx → retrae por backoff.
2. Después de la recuperación - tomar el mismo 'X-GH-Event-Id' → están obligados a ignorar duplicados.

18. 3 Degradación parcial del proveedor

Devolveremos 503; repita con backoff.
En el caso de degradación prolongada, la marca de parada del proveedor y la activación de la ruta inteligente (si está en el contrato).

19) DevEx y soporte

Portal: llaves, usage, webhooks, logs de envío, dashboards SLO, informes de exportación.
Webhooks replay: volver a enviar por intervalo de fechas/ID.
Incidentes: creación automática de ticket, sala de guerra, post mortem ≤ 48 h por SEV-1.
Comunicaciones: # partners-status canal/correo on-call 24 × 7 (Enterprise).

20) Plan de onboarding (2-4 semanas)

1. Semana 1: entrega de llaves, conexión de sandbox, escenarios básicos (apuesta/pago/billetera).
2. Semana 2: webhooks y conciliaciones, banderas RG/KYC, pruebas de carga, comportamiento 429/5xx.
3. Semana 3: informes (reconciliación, descargas), seguridad (firmas, secretos), pruebas de contrato.
4. Semana 4: certificación, canario-inclusión en la venta, monitoreo, matriz de contacto.

21) Mini preguntas frecuentes

¿Puede gRPC?
Sí, a petición; el mapeo de códigos de error en HTTP se proporciona en la especificación.

¿Cómo puedo obtener datos retro?
A través de los informes 'reconciliation' (fechas 'from/to') o S3/SFTP de descarga.

¿Cómo puedo aumentar los límites?
A través del portal/gestor de cuentas con indicación de RPS/competencia predictiva.

¿Cuál es la fuente de la verdad del equilibrio?
Registro transaccional de la cartera GambleHub + conciliación diaria (reconciliation).

Resultado

La integración con GambleHub se basa en un contrato claro: API y esquemas estables, webhooks firmados, idempotencia y retrés, límites transparentes e informes, y requisitos de seguridad y cumplimiento. Al seguir esta guía y los cheques de certificación, saldrá rápidamente al paso, asegurando flujos de efectivo confiables e informes coherentes sin discrepancias.