API única para proveedores: diseño, versión, compatibilidad

Texto completo del artículo

💡 18+. Material técnico para equipos de integración y plataformas. No es una llamada al juego.

1) Por qué una «API única» y lo que es

Una API única es una especificación y conjunto de endpoints/eventos a través de los cuales cualquier proveedor de contenido (RGS, live studio, jackpot, KYC/AML, afiliados) se comunica con la plataforma bajo una sola regla:

un único modelo de recursos (players, sessions, bets, settlements, bonuses, jackpots, payments), contratos de eventos comunes e identificadores, estándares de seguridad y compatibilidad inversa, herramientas SDK/para acelerar las integraciones.

Objetivo: reducir el tiempo de integración, reducir los errores en las «rutas monetarias» y proporcionar actualizaciones predecibles.

2) Principios de diseño

1. Domain-first. Primero diccionario e invariantes (apuesta, settlement, límites RG), luego endpoints.

2. Compatibility by default. Cualquier cambio es compatible por defecto; cambios de breaking estrictamente por el proceso.

3. Idempotency everywhere. Todos los comandos de dinero son repetibles sin efectos secundarios.

4. Eventos son fuente de verdad (en distribución). Operaciones → eventos en el bus; los analistas escuchan el bus en lugar de golpear el OLTP.

5. Least privilege & zero-trust. Tokens, firmas, segmentación por marca/región.

6. Observability. «Trace _ id» de extremo a extremo, modelo de error comprensible, métricas p95/p99.

3) Modelo de recursos (simplificado)

Player: pseudo-ID del jugador en el lado de la plataforma, geo/moneda/estados RG.

Sesión: canal entre el proveedor y la plataforma ('session _ id', TTL, geo/restricciones).

Apuesta: autorización/débito de la apuesta.

Settlement: el resultado de la ronda y el crédito de la victoria.

Bonus/Wager: estado de bonificación/saldo del vager.

Jackpot: contribuciones/desencadenantes/pagos.

Evento: eventos de dominio inmutables (Kafka/análogos).

Identificadores: 'tenant _ id', 'brand _ id', 'region', 'player _ id', 'session _ id', 'round _ id', 'bet _ id', 'settlement _ id'. Todas son cadenas, exclusivas globalmente (UUID/KSUID/Snowflake), incluidas en los registros y eventos.

4) Contratos API: consultas, respuestas, errores

4. 1 Autorización y seguridad

OAuth2 Credentials de cliente o firma de cuerpo de solicitud mTLS + (HMAC/EdDSA).

Скоупы вида: `bets:write`, `settlements:write`, `sessions:read`, `events:publish`.

Los encabezados son obligatorios en cada solicitud:

`X-Trace-Id`, `X-Brand-Id`, `X-Region`, `X-Idempotency-Key`.

4. 2 Ejemplos de endpoints

Creación de una sesión


POST /v1/sessions
{
"player_id":"p_19f3",  "game_id":"studio:slot_forge_02",  "currency":"EUR",  "locale":"de-DE",  "constraints":{"max_bet":5,"rg_flags":["self_exclusion":false]}
}
→ 201
{
"session_id":"s_456",  "expires_at":"2025-10-23T19:10:00Z"
}

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

Settlment


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. 3 Errores (modelo único)

`code`: машинное имя (`RG_BLOCK`, `LIMIT_EXCEEDED`, `DUPLICATE`, `IDEMPOTENCY_MISMATCH`, `INVALID_STATE`, `AUTH_FAILED`).

'mensaje': breve para una persona.

`retryable`: `true/false`.

'trace _ id': para buscar en los logs.

Ejemplo:


409 CONFLICT
{
"code":"DUPLICATE",  "message":"Bet already authorized with a different amount",  "retryable":false,  "trace_id":"tr_a1b2c3"
}

5) Bus de evento y circuitos

5. 1 Topics básicos

`player. registered`, `session. started	ended`
`bet. authorized	settled
`bonus. issued	consumed
`wager. progress. updated`
`jackpot. contribution	triggered
`rg. limit. hit`, `rg. reality_check`
`wallet. debit.`, `wallet. credit.`

5. 2 Esquema de eventos (Avro/JSON Schema)

json
{
"event_id":"uuid",  "event_type":"bet. settled",  "occurred_at":"2025-10-23T16:21:05Z",  "tenant_id":"brand-7",  "region":"EU",  "player_id":"p_19f3",  "trace_id":"tr_a1b2c3",  "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",  "schema_version":"1. 2. 0"
}

Reglas: backward-compatible evolución de circuitos, registro + pruebas contractuales.

6) Versión de la API: estrategias y reglas

6. 1 Dónde almacenar la versión

Versión path: '/v1/... '(sólo caché/enrutamiento).

Versión header: 'Accept: application/vnd. platform. api+json; version=1. 2`.

Eventos: 'schema _ version' en el campo de evento + registro.

Práctica: path para HTTP, schema_version para eventos, phichflags para capacidades puntuales.

6. 2 SemVer y tipos de cambios

PATCH (minor) - acoplamiento inverso: nuevos campos opcionales, nuevos endpoints, nuevos tipos de eventos.

MAJOR - breaking: cambiar el nombre de los campos, cambiar la semántica, eliminar. Sólo se permiten a través de la nueva '/vN/' y la deprecación de la antigua.

6. 3 Contratos estables (que no se pueden romper)

Nombres y tipos de campos de identificación clave ('_ id', 'idempotency _ key').

Modelo monetario ('amount/currency', precisión).

Semántica de estados ('autorizados', 'acreditados', 'forfeited', etc.).

Idempotencia: el comportamiento en la repetición está estrictamente definido.

7) Compatibilidad y evolución

7. 1 Adiciones (seguro)

Nuevos campos opcionales con impagos.

Nuevos eventos/endpoints sin alterar los existentes.

Extensión enum con fallback en 'unknown'.

7. 2 Cambios (risky)

Cambia el tipo de campo (número → fila).

Cambio de obligatoriedad (optional → required).

Reversión de la lógica empresarial ('settle' antes 'authorize').

→ requiere una nueva versión mayor y un hyde migratorio.

7. 3 Deprecación

El campo/endpoint se marca con 'deprecated _ since: 1. 7`, `removed_in: 2. 0`.

Comunicación: notas release, newsletter, deprecation-headers ('Sunset', 'Deprecation').

Rastreo del uso de rutas «obsoletas» para notificaciones proactivas de socios.

8) Idempotencia y coherencia

El encabezado 'X-Idempotency-Key' es obligatorio para todas las operaciones de grabación.

Semántica: repetición con la misma clave → el mismo resultado (200 con el cuerpo anterior).

Las claves están enlazadas a la composición de parámetros (por ejemplo, 'bet _ id + amount').

Sagas en procesos largos: 'authorize → commit/lock → settle → credit'; compensación - eventos 'rollback'.

9) Paginación, filtros, clasificación

Paginación cursor-based (estrictamente preferible a 'page/limit' para flujos grandes).

Unificación: '? cursor =... & limit = 200 & order = asc'.

En la respuesta: 'next _ cursor', 'has _ more'.

Filtros: por tiempo ('occurred _ at _ from/to'), 'tenant _ id', 'game _ id', 'status'.

10) Locali, monedas, datos de residencia

Moneda en ISO-4217; la precisión se almacena en el diagrama ('escala'), los cálculos en minor-units (centros).

Locali es BCP 47 ('en-GB', 'pt-BR').

En cada consulta - 'región'; El PII y las transacciones monetarias no cruzan regiones.

Enmascaramiento de PII y RLS en vitrinas BI.

11) Observabilidad y límites

Títulos obligatorios: 'X-Trace-Id', 'X-Provider-Id', correlación con eventos.

Métricas: p50/p95/p99 latency, error rate (por códigos), throughput, queue lag (para eventos).

Rate limits: per provider / per brand; respuestas con 'Retry-After'.

Auditoría WORM de cambios críticos (límites, grupos RTP, fórmulas de jackpot).

12) Pruebas y calidad de los contratos

Pruebas contractuales (Nat/otros): proveedor ↔ plataforma ↔ consumidores de eventos.

Carga: «tormenta» de apuestas/settlement; objetivos p95.

Casos de caos: entrega de toma, fuera de orden, retrasos en la cartera.

Sandbox '/sandbox 'con dinero ficticio y' player _ id 'de prueba.

13) SDK, generadores y documentación

OpenAPI/AsyncAPI → generación SDK (TypeScript/Java/Kotlin/Go/Rust).

Ejemplos de código para 'authorize/settle/rollback', retrés y manejo de errores.

Dock en vivo con ejemplos de consulta/respuesta (curl + JSON), colección Postman/Insomnia.

Changelog con tipos de cambios y etiquetas de compatibilidad.

14) Hoja de ruta para las migraciones (ejemplo)

1. v1. 6 → v1. 7 (menor): añadió el campo 'bonus _ state' a 'settle' (optional).

2. v1. x EOL anuncio: 6 meses - carta + 'Deprecation' header + dashboard de uso.

3. v2. 0 (mayor): separado 'wallet. commit '(anteriormente implícito), el nuevo campo' settlement _ id 'es obligatorio.

4. Hyde migratorio: mapping de campos, timeline, fichflag de «doble escritura» (publicación paralela de eventos 'v1 '/' v2').

5. Sunset v1: bloquear nuevas integraciones, extendiéndose sólo con excepciones SLA.

15) Hojas de cheques

Para los arquitectos de la plataforma

Hay un solo diccionario de entidades de dominio e invariantes.
OpenAPI/AsyncAPI + Schema Registry, semver, procesar deprecaciones.
Idempotencia en todas las operaciones de escritura; las claves están documentadas.
Un único modelo de error y códigos.
Sagas y outbox/CDC en las rutas monetarias.
Rate-limits, observabilidad, auditoría WORM.
La caja de arena y las pruebas contractuales están disponibles para los socios.
Residencia de datos y RLS/enmascaramiento.

Para el proveedor

Envío 'X-Trace-Id' y 'X-Idempotency-Key' siempre.
Las repeticiones de solicitudes se manejan de forma segura; No creo tomas.
Manejo 'Deprecation/Sunset' y leo Changelog.
Publico/leo eventos sobre esquemas de registro; Conservo la versión.
Tengo retry/backoff y deduplicación a mi lado.

16) Anti-patrones (banderas rojas)

Correcciones manuales de balances/settlents en la DB.

Publicación de eventos «más allá» outbox/CDC.

Ausencia de idempotency → toma de pagos/adeudos.

Mezcla de PII/dinero de diferentes regiones sin etiquetar 'región'.

Cambios de breaking «silenciosos» sin nueva versión y deprecación.

Generación de SDK manualmente (derivación con sinterización real).

Big-bang migración sin fichflags y doble escritura de eventos.

Una API única no es solo una "colección de endpoints', sino un contrato de ecosistema: un diccionario negociado, invariantes monetarios estables, eventos con versionados, reglas de compatibilidad comprensibles y depreciaciones administradas. Apoyándose en la versión semántica, la idempotencia, la outbox/CDC, la vigilancia y la seguridad estricta, la plataforma conecta a los proveedores de forma rápida y sin dolor, y las actualizaciones se convierten de riesgo en rutina.