Как работает API интеграция между студиями и платформами

Интеграция студии (провайдера игр) с платформой/агрегатором — это цепочка синхронных и асинхронных вызовов вокруг сессии, кошелька, результата спина и событийной телеметрии. Ниже — краткая, но практичная карта, как всё соединяется без боли для разработчиков и комплаенса.

1) Архитектура на ладони

Акторы:

Studio RGS (Remote Game Server) — логика игры, RNG, бонусы, джекпоты.
Платформа/Агрегатор — маршрутизация, биллинг, промо, комплаенс.
Оператор — кошелёк игрока, KYC/RG, витрина.
Клиент — веб/мобайл контейнер игры (iframe/webview/native).

Основные шины:

Sync API: сессии, кошелёк, outcome.
Async/Event Bus: события спинов, бонусов, джекпотов, RG, технические ошибки.
Метаданные/каталог: игры, market builds, RTP-профили, локали.

2) Протоколы и базовые решения

Транспорт: HTTPS/JSON (иногда gRPC для Event Bus/кошелька).

Версионирование: `Accept: application/vnd.rgs.v1+json` или `/v1/...`; деградация совместимости — только через новые версии.

Идентификация: `game_id`, `build_hash`, `operator_id`, `session_id`, `round_id`, `spin_id`.

Время: строго UTC, ISO-8601 с миллисекундами.

Валюты: ISO-4217 + точность (minor units). FX — на стороне оператора/агрегатора.

3) Аутентификация и авторизация

Server-to-server: OAuth2 Client Credentials или HMAC-подпись (`X-Signature: HMAC_SHA256(payload, shared_key)`).

Сессия игрока: short-lived JWT (подписывает платформа) c `sub`, `geo`, `rg_flags`, `exp`, `aud=studio`.

Списки доступа: IP allowlist + mTLS для прод-контуров.

4) Модели кошелька: debit/credit vs transfer

A) Debit/Credit (on-the-fly):

1. Платформа вызывает RGS: `SpinRequest(stake)` → RGS рассчитывает исход → возвращает `win`.

2. Параллельно платформа делает `debit(stake)` и `credit(win)` у себя/у оператора.

Плюсы: простая бухгалтерия. Минусы: больше сетевых вызовов, жёсткие требования к идемпотентности.

B) Transfer (session balance):

1. В начале сессии платформа делает `transferIn(amount)` на RGS.

2. Во время спинов RGS сам ведёт баланс сессии; при завершении — `transferOut(remaining)`.

Плюсы: меньше чатов кошелька. Минусы: учёт «денег на стороне RGS», дополнительные риски и reconciliations.

Рекомендации:

Для слотов чаще используют debit/credit с идемпотентными ключами.

На free spins и турниры удобно иметь отдельные типы ставок `spin_type=free	promo`.

5) Идемпотентность и согласованность

Каждый денежный шаг должен иметь уникальный `idempotency_key` (например, `round_id` или `spin_id`).

Повторы (`HTTP 409/425`) возвращают тот же результат, а не «ошибку уже выполнено».

Exactly-once добиться сложно, поэтому строим at-least-once + идемпотентность.

Идемпотентность распространяем на: `debit`, `credit`, `jackpot_contribution`, `bonus_award`.

6) Схемы ключевых запросов (сокращённые)

6.1. Старт сессии

json
POST /rgs/v1/sessions
{
"session_id": "s-…",  "operator_id": "op-…",  "player_id": "p-…",  "game_id": "g-BookOf…",  "build_hash": "sha256:…",  "jwt": "eyJhbGci…",  "geo": "DE",  "currency": "EUR",  "rg_flags": {"self_excluded": false, "time_limit_min": 60}
}

6.2. Спин (debit/credit)

json
POST /rgs/v1/spins
{
"spin_id": "spin-…",  "round_id": "rnd-…",  "session_id": "s-…",  "stake": {"amount": 1.00, "currency": "EUR"},  "spin_type": "cash",  "idempotency_key": "spin-…"
}

Ответ:

json
{
"spin_id": "spin-…",  "outcome": {
"win": {"amount": 3.40, "currency": "EUR"},   "features": [{"type":"bonus_trigger","name":"FreeSpins","count":10}],   "symbols": "opaque-or-omitted"
},  "rgs_txns": [
{"type":"jackpot_contribution","amount":0.01}
],  "telemetry_ref": "evt-…"
}

6.3. Событийный лог (Event Bus, формат батчей)

json
POST /rgs/v1/events/batch
{
"events":[
{
"type":"spin_finished",    "ts":"2025-10-20T11:22:33.123Z",    "spin_id":"spin-…",    "round_id":"rnd-…",    "stake":1.00,"win":3.40,"currency":"EUR",    "game_id":"g-…","build_hash":"sha256:…",    "player_id":"p-…","operator_id":"op-…",    "spin_type":"cash"
}
]
}

7) Версионирование билдов и market builds

`build_hash` (SHA-256) — обязательный на каждом событии.

Global vs Market build: язык, предупреждения, ограничения ставок, RTP-профиль.

Платформа валидирует: «играется ли сейчас билд, соответствующий сертификату данной страны».

Матрица: `game_id × country × rtp_profile × build_hash`.

8) RNG, математика и реплей

RNG живёт на RGS; бизнес-логика не меняет шансы «на лету».

Для форензики: `seed/nonce` на раунд/спин + версия механики.

Реплей: по `spin_id`/`seed` RGS воспроизводит исход и отдает аудит-след.

9) Responsible Gaming (RG) и комплаенс-хуки

Хуки времени/лимитов: `session_time_ms`, «напоминания», timeouts; `rg_event` в Event Bus.

Самоисключение/блок: при флаге — немедленный `403 RG_BLOCKED`.

UI-инварианты: платформа проверяет, чтобы клиент показывал предупреждения/возрастные метки из market build.

10) Ошибки, ретраи и SLA

Коды: `400` (валидация), `401/403` (аутентификация/RG), `409` (конфликт идемпотентности), `422` (бизнес-ошибка), `429` (rate limit), `5xx` (временная).

Политика ретраев: экспоненциальная, с идемпотентным ключом и дедупликацией на приёмнике.

SLA: доступность API ≥99.9%, p95 latency для `spin` ≤200–300 мс (регионально), Event Bus — near-real-time < 60 с.

11) Наблюдаемость и аудит

Логи: необрезанные серверные логи c кореляцией `trace_id`.

Метрики: p95/p99 latency, error rate по методам, отклонения RTP/частот бонусов, доля «eligible spins».

Алерты: по SLA, по аномалиям математики, по росту отказов кошелька.

Аудит: WORM-хранилище на события ставок/результатов; экспорт по запросу.

12) Безопасность

mTLS + TLS 1.2+, HSTS, строгие CORS на клиентском лоадере.

Кей-ротация, короткие TTL токенов, JTI/nonce-проверки.

Anti-tamper для клиента: подписи ассетов, проверка целостности, защита от дебаггеров.

Секреты — только в секрет-менеджере; никакого «ключа в конфиге игры».

13) Тестовые среды и сертификация

Sandbox: фиктивные кошельки, детерминированные RNG (fixed seed), авто-провал RG-сценариев.

Staging: копия прод-инфры без реальных денег.

Пакет для лабораторий: GDD/математика, RNG-досье, схемы логов, repeatable build и хэши.

14) Промо и джекпоты в API

Free Spins: передача пакета: `grant_free_spins(count, bet_size, rtp_profile?)`; события тратятся в RGS и логируются.

Турниры: атрибут `spin_type=tournament` + отдельные агрегаты в Event Bus.

Джекпоты: `jackpot_contribution` и `jackpot_win` как отдельные транзакции; консистентность через идемпотентность и «подписанные» события.

15) Отчётность и биллинг

Блоки выгрузок: `spins_total`, `eligible_spins`, `turnover`, `ggr`, `netwin`, `jackpot_contrib`, `bonus_cost`, `royalty_due`.

Per-spin / turnover-fee: счёт по `eligible_spins` или `Σ stake × rate`.

Rev-share: от `NetWin` после «водопада» удержаний; квартальный true-up для FX/исключений.

16) Типовые последовательности (словесные диаграммы)

Spin (debit/credit):

Client → Platform: StartRound → Platform → RGS: Spin → RGS → Platform: Outcome → Platform → Wallet: Debit → Platform → Wallet: Credit → Platform → Client: Result → Platform → EventBus: spin_finished.

Free Spins:

Platform → RGS: GrantFreeSpins → Client: Start → RGS: Consume/Log each → EventBus: spin_finished (spin_type=free).

17) Change-management и совместимость

Контракт-сначала (contract-first): OpenAPI/Protobuf — единый источник схем.

SemVer: только добавляйте поля; удаление/изменение — в /v2.

Feature flags: включение опций (Bonus Buy/Ante) — только через сертифицированные профили.

Deprecation: announce → grace period → выключение в неактивных регионах.

18) Чек-листы

Студия → Платформа

OpenAPI/gRPC-спеки и примерные пэйлоады.
Идемпотентность `spin/debit/credit/jackpot`.
`build_hash` и реестр market builds.
RNG-реплей и аудит-лог.
RG-хуки и ошибки `403 RG_BLOCKED`.
Sandbox с фикс-seed, тест-кошельком и автосценариями.

Платформа → Студия

JWT-подпись с коротким TTL, allowlist IP, mTLS.
Валидатор market builds и сертификатов.
Event Bus и дашборды (latency/error/RTP drift).
Квоты и rate-limits с честной обратной связью `429-Retry-After`.
SLA/инциденты/каналы связи 24×7.

19) 30-60-90 план запуска

0–30 дней

Согласовать контракты API и схемы событий, выбрать модель кошелька.

Поднять sandbox: fixed-seed RNG, тест-кошелёк, автотесты идемпотентности.

Реестр `build_hash` и первичная матрица market builds.

31–60 дней

Интеграция кошелька и спинов; включить Event Bus и дашборды.

Нагрузочные тесты (p95/p99), ретраи/идемпотентность, хаос-сценарии сети.

Комплаенс: RG-хуки, локали, age-labels; пакет в лабораторию.

61–90 дней

Пилот у 1–2 операторов, A/B на промо (free spins/турниры).

Ввод true-up/отчётности, алерты RTP-дрейфа/bonus-freq.

Подготовка v2 улучшений: батч-события, gRPC для кошелька, geo-routing.

20) Короткий FAQ

Где проверяется RTP/версия? На платфоме: `build_hash` ↔ сертификат ↔ страна.

Можно ли менять RTP динамически? Нет. Только заранее сертифицированные профили и только переключением market build.

Как решать «двойной debit»? Идемпотентный ключ + хранение статуса транзакции; повтор — возвращает исход.

Нужен ли gRPC? Полезен для кошелька/ивентов при высоких объемах; REST остаётся для метаданных/админки.

Стабильная интеграция — это контракты + идемпотентность + наблюдаемость. Прозрачные схемы событий, контроль билдов/рынков, RG-хуки и дисциплина версий снимают 90% рисков на старте. Дальше — автоматизация промо и отчётности, жёсткий SLA и бережное развитие API без «ломающих» изменений.