Студиялар менен платформалардын ортосундагы API интеграциясы кандай иштейт

Студиянын (оюн провайдеринин) платформа/агрегатор менен интеграциясы сессиянын, капчыктын, арканын натыйжасынын жана окуя телеметриясынын айланасында синхрондуу жана асинхрондук чалуулардын чынжырчасы болуп саналат. Төмөндө - кыска, бирок практикалык карта, баары иштеп чыгуучулар жана комплаенс үчүн оорутпай кошулат.

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

Актёрлор:

Studio RGS (Remote Game Server) - оюндун логикасы, RNG, бонустар, джекпот.
Платформа/Агрегатор - багыттоо, биллинг, промо, комплаенс.
Оператор - оюнчунун капчыгы, KYC/RG, витрина.
Кардар - Web/Mobile контейнер оюн (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/...'; деградация - жаңы версиялар аркылуу гана.

ID: 'game _ id', 'build _ hash', 'operator _ id', 'session _ id', 'round _ id', 'spin _ id'.

Убакыт: катуу UTC, миллисекунддар менен ISO-8601.

Акча: ISO-4217 + тактык (чакан бирдиктер). 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/кредит vs которуу

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.

Сунуштар:

Слоттор үчүн көбүнчө демпотенттик ачкычтар менен debit/credit колдонулат.

free spins жана турнирлерде ар кандай түрлөрү бар 'spin _ type = free	promo`.

5) Идемпотенттүүлүк жана ырааттуулук

Ар бир акча кадамы уникалдуу 'idempotency _ key' болушу керек (мисалы, 'round _ id' же 'spin _ id').

Кайталоолор ('HTTP 409/425') "ката буга чейин аткарылган" эмес, ошол эле натыйжаны кайтарат.

Exactly-once жетишүү кыйын, ошондуктан биз ат-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) Version имараттарды жана Market Builds

'build _ hash' (SHA-256) - ар бир иш-чарага милдеттүү.

Global vs Market build: тил, эскертүү, чендерди чектөө, RTP-кароо.

Платформа: "Бул өлкөнүн сертификатына ылайык келген билд ойноп жатабы".

Matrix: 'game _ id country .

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

RNG RGS жашайт; бизнес-логика "учуу" мүмкүнчүлүгүн өзгөртпөйт.

Forensics үчүн: '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) Каталар, Retray жана SLA

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

Ретрациялардын саясаты: экспоненциалдык, демпотенттик ачкыч жана кабыл алуучуда дедупликация.

SLA: 99 ≥ API жеткиликтүүлүгү. 9%, p95 latency үчүн 'spin' ≤ 200-300 ms (аймактык), 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, кардар loader боюнча катуу CORS.

Key-айлануу, кыска TTL токендер, JTI/nonce-текшерүү.

кардар үчүн Anti-tamper: кол assets, бүтүндүгүн текшерүү, Дебаггер коргоо.

Сырлар - бир гана жашыруун менеджер; эч кандай "оюн ачкычы".

13) Тесттик чөйрө жана күбөлүк

Sandbox: жасалма капчыктар, determinated RNG (fixed seed), auto-ийгиликсиз 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: '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-бөлүшүү: '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-башкаруу жана шайкештик

Биринчи келишим (contract-first): OpenAPI/Protobuf - схемалардын бир булагы.

SemVer: гана талаа кошуу; алып салуу/өзгөртүү - v/v2.

Feature flags: параметрлерин киргизүү (Bonus Buy/Ante) - гана күбөлөндүрүлгөн Profiles аркылуу.

Deprecation: announce → grace period → активдүү эмес аймактарда өчүрүү.

18) Чек баракчалары

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

OpenAPI/gRPC спек жана болжолдуу pailoads.
Idempotentity 'spin/debit/credit/jackpot'.
'build _ hash' жана market builds реестри.
RNG реплика жана аудит журналы.
RG-хаки жана каталар '403 RG_BLOCKED'.
fix-seed менен Sandbox, сыноо капчык жана autoscaries.

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

JWT кол кыска TTL, allowlist IP, mTLS.
Validator market builds жана күбөлүктөр.
Event Bus жана dashboard (latency/error/RTP drift).
чынчыл пикир менен квота жана rate-limits '429-Retry-After'.
SLA/окуялар/байланыш каналдары 24 × 7.

19) 30-60-90 ишке киргизүү планы

0-30 күн

келишимдер API жана иш-чаралардын схемаларын макулдашуу, капчык моделин тандоо.

Көтөрүү sandbox: fixed-seed RNG, сыноо капчык, ottestes idempotentity.

Реестр 'build _ hash' жана баштапкы матрица market builds.

31-60 күн

Капчыкты жана спинди интеграциялоо; Event Bus жана dashboard кирет.

Load Tests (p95/p99), retry/демпотенттик, хаос-тармак жагдайлар.

Комплаенс: 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 которуу.

"Double Debit" кантип чечүү керек? Idempotent ачкычы + транзакция статусун сактоо; кайталоо - натыйжасын кайтарат.

gRPC керекпи? Жогорку көлөмдө капчык/иш-чаралар үчүн пайдалуу; REST метадеректер/администратор үчүн калат.

Туруктуу интеграция - бул келишимдер + демпотенттик + байкоо. Ачык-айкын иш-чаралардын схемалары, имараттарды/рынокторду көзөмөлдөө, RG-хаки жана тартип версиялары башында тобокелдиктердин 90% алып салат. Андан ары - жарнамалык жана отчеттуулукту автоматташтыруу, катуу SLA жана "бузуучу" өзгөрүүлөрсүз APIди кылдат өнүктүрүү.