Як працює 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) Спостережуваність і аудит

Логи: необрізані серверні логи з кореляцією'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 без «ламаючих» змін.