Cómo conectar proveedores a través de la API: handshake, certificación, sandbox

Texto completo del artículo

💡 18+. El material es de ingeniería y aplicación, no es una llamada al juego. Por «proveedor» se entiende el estudio/jackpot/servicio RGS/live; bajo «plataforma» - PAM/billetera/taquilla/bonos/RG.

1) Tarjeta de integración: desde la solicitud hasta la producción

Etapas:

1. Presale y Due Diligence: verificaciones juradas, geo/licencias, compatibilidad de contenido y políticas RG.

2. Handshake y seguridad: emisión de accesos sandbox, intercambio de claves (mTLS/HMAC), registro en Schema Registry.

3. Diseño técnico: confirmamos el modelo de dominio (sessions/bets/settlements/events), idempotencia, códigos de error.

4. Integración de sandbox: emuladores de billetera/PSP/RG, jugadores de prueba, escenarios de «lluvia» y tomas.

5. Certificación: ejecución de pruebas obligatorias, firma de protocolos, cargas y casos de caos.

6. Staging/UAT: confiscaciones de combate sin dinero real, tráfico canario.

7. Go-Live: compañía de llaves, encendido de banderas, monitoreo de SLO, preparación post-incidente.

2) Handshake: autenticación, autorización, rastreo

2. 1 Intercambio de secretos y escopetas

mTLS (certificados por marca/región) y/o OAuth2 Credentials de clientes.

Firma del cuerpo de la solicitud HMAC/EdDSA (agrega non-repudiation).

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

2. 2 Títulos obligatorios

'X-Trace-Id' es un rastreo de extremo a extremo.

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

'X-Idempotency-Key' - para todas las operaciones de escritura.

2. 3 Control de salud (hasta código)


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

3) Sandbox: qué hay allí y cómo usarlo

Composición del entorno:

Emulador de billetera ('/wallet/debit	credit	rollback ') con idempotencia y retrasos.
RG-hooks ('/rg/check ',' rg. limit. hit ') y perfiles de prueba (autoexclusión/límites).
Agregador de falsos/jackpot para contribuciones/disparadores.
Fake KYC/AML respuestas (allow/deny/pending).
Bus de eventos (Kafka/Pulsar) con topics de prueba y Registro de Schema.

Armonía con la realidad:

Versiones similares de circuitos y rate limits que en la venta.
Tiempo de espera, tomas de entrega, fuera de orden - integrado por los botones de emulación.

Conjunto de jugadores/monedas de prueba:


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

4) Modelo de recursos y contrato mínimo

4. 1 Creación de una sesión


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 Autorización de apuestas (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 Settlement (resultado de la ronda)


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 Errores (esquema único)


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

5) Eventos y esquemas: sin esto, no pasarás la certificación

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`.

Ejemplo de Avro/JSON Schema (fragmento '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"
}

Reglas: evolución compatible con backward, prueba de «eventos duplicados y posteriores», partición por 'tenant _ id/player _ id'.

6) Certificación de integración: qué se comprueba exactamente

6. 1 Scripts funcionales (mínimo)

Repetir la consulta 'authorize/settle' con la misma 'X-Idempotency-Key' → la misma respuesta.

Out-of-order: llegó el 'settle' sin 'authorize' → el fallo correcto.

Rollback-chain cuando el monedero/red se cae.

RG-pies: auto-exclusión/límite de pérdida/tiempo → prohibir la tasa.

Bonus/Wager: contribución por tipo de juego, max bet, deadline.

6. 2 Carga

p95 'bet/settle' en los presupuestos (por ejemplo, '<200-300 ms'), la ausencia de «tormentas» retraídas.

Los flujos de eventos llegan a BI ≤ 5 minutos.

6. 3 Casos de caos

Las tomas de entrega, los retrasos de outbox/CDC, «arruinaron» a la región, el settlement parcial.

6. 4 Documentos de resultados

Protocolo de pruebas con códigos de tiempo/trace-id.

Informe SLO (latency/error/lag).

Resumen de seguridad (claves, rotaciones, accesos, Vault/HSM).

7) Versión y migración

HTTP: '/v1/... 'en ruta, eventos:' schema _ version 'en el cuerpo.

SemVer: menor - agregar campos opcionales; mayor - sólo a través del nuevo prefijo '/v2/'.

Deprecation headers: 'Deprecation', 'Sunset', espejo de uso en dashboard.

Banderas Fich: la «doble letra» de los acontecimientos ('v1' y 'v2') en la transición.

8) Seguridad y cumplimiento

mTLS + firmas de S2S, tokens de vida corta, scopes limitados.

Zero-trust: directivas de red, claves per-brand/region.

Data residency & PII: almacenamiento y registros en la región; RLS/enmascaramiento.

Auditoría WORM: cambios en los límites, perfiles RTP, configuraciones de jackpot.

RG/AML: señales de parada sincrónicas en la apuesta/pago; Informe SAR/NAT.

9) Salida de prueba: lista de comprobación de inicio

Antes de activar el tráfico

La rotación de los secretos de sandbox → claves de prod.

Se incluyen los dashboards p95/p99, error-rate, queue-lag, settle-lag.

Alertas SLO: breach por latency/error/lag, estallido de 'DUPLICATE/IDEMPOTENCY _ MISMATCH'.

Plan DR: RPO ≤ 5 min, RTO ≤ 30 min; «botón rojo» - parada de nuevas sesiones.

Canario

1-5% de audiencia/juegos/geo; rollback automático cuando se infringe el SLO.

Monitoreo posterior de 24-72 horas, comprobación del ledger/informes.

10) Anti-patrones (banderas rojas)

Publicación de eventos omitiendo outbox/CDC.

Ausencia de 'X-Idempotency-Key' en las operaciones de escritura.

Correcciones manuales de balances/settlents en la DB.

Llaves únicas en varias marcas/regiones.

BI y los informes regulatorios en la parte superior de la BD de combate OLTP.

Cero degradación: la caída del proveedor valora la billetera/plataforma.

11) Hojas de cheques

Para el proveedor

Envío 'X-Trace-Id' y 'X-Idempotency-Key' siempre.
Mantengo la repetición con la misma clave sin efectos secundarios.
Publico los eventos de los esquemas del Registro; Almaceno 'schema _ version'.
Se han implementado retraídas con backoff y deduplicación.
Los pies de RG y las restricciones de bonificación se respetan en tiempo real.
Accesos y secretos - por marca/región, rotación configurada.

Para la plataforma

Outbox/CDC en todas las vías monetarias; seguimiento de fin a fin.
SLO-dashboards: p95/99, error-rate, queue-lag, settle-lag.
Deprecation/Sunset-process, doble escritura de eventos en migraciones.
Ejercicios de DR/xaoc, gestión de incidentes y postmortem.
Modos de degradación: 'no nuevas sesiones', desactivación de promo/jackpot.

12) Ejemplo de un «mínimo» playbook de integración (TL; DR)

1. Firmar un NDA/contrato → emitir accesos y esquemas de sandbox.

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

3. Acordar endpoints mínimos: 'sessions',' bets/authorize ',' bets/settle ',' rollback '.

4. Conectarse a un bus Sandbox y Registry; ahuyentar casos funcionales/de caos.

5. Entregar el protocolo de certificación: logs, trace-id, informe SLO.

6. Cambie las llaves a la primera línea, active el canario, observe el SLO.

7. Fijar métricas post-lanzamiento y «lecciones» en changelog.

La conexión exitosa del proveedor no es solo una API, sino un proceso administrado: handshake seguro, sandbox realista, certificación estricta, observabilidad y reglas claras de compatibilidad. Siguiendo los invariantes descritos (idempotencia, outbox/CDC, RG/AML-stop, SLO y DR), acelera la integración, evita incidentes monetarios y obtiene lanzamientos predecibles, sin sorpresas para jugadores, reguladores y empresas.