Студиялар мен платформалар арасындағы 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 (кейде Event Bus/әмиян үшін gRPC).

Нұсқалау: '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. Сессияның басында платформа RGS-де 'transferIn (amount)' жасайды.

2. RGS спиндері кезінде сессияның теңгерімін өзі жүргізеді; аяқталғанда - 'transferOut (remaining)'.

Артықшылықтары: әмиян чаттары аз. Минустар: «RGS жағындағы ақшаны» есепке алу, қосымша тәуекелдер мен reconciliations.

Ұсынымдар:

Слоттар үшін көбінесе дебит/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 .

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: assets қолтаңбалары, тұтастығын тексеру, дебаггерлерден қорғау.

Құпиялар - құпия-менеджерде ғана; «ойын конфигасының кілті» жоқ.

13) Тест ортасы және сертификаттау

Sandbox: жалған әмияндар, детерминирленген RNG (fixed seed), RG сценарийлерінің авто-сәтсіздігі.

Staging: нақты ақшасыз прод-инфраның көшірмесі.

Зертханаларға арналған пакет: GDD/математика, RNG-досье, логтар схемасы, қалпына келтірілетін құрылғы және хэштер.

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' -тен «сарқырамадан» кейін ұстап қалу; FX/ерекшеліктер үшін тоқсандық true-up.

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).
Квоталар және '429-Retry-After' деген адал кері байланысы бар rate-limits.
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-ны ұқыпты дамыту.