Studiyalar va platformalar o’rtasidagi API integratsiyasi qanday ishlaydi

Studiya (oʻyin provayderi) ning platforma/agregator bilan integratsiyalashuvi - sessiya, hamyon, bel natijasi va voqea telemetriyasi atrofida sinxron va asinxron qoʻngʻiroqlar zanjiridir. Quyida hamma narsa ishlab chiquvchilar va komplayens uchun og’riqsiz bog’lanishi haqida qisqacha, ammo amaliy xarita mavjud.

1) Kaftdagi arxitektura

Aktyorlar:

Studio RGS (Remote Game Server) - o’yin mantig’i, RNG, bonuslar, jekpotlar.
Platforma/Agregator - yo’naltirish, billing, promo, komplayens.
Operator - o’yinchining hamyoni, KYC/RG, vitrin.
Mijoz - veb/mobil konteyner o’yini (iframe/webview/native).

Asosiy shinalar:

Sync API: seanslar, hamyon, outcome.
Async/Event Bus: spin voqealari, bonuslar, jekpotlar, RG, texnik xatolar.
Meta maʼlumotlar/katalog: oʻyinlar, market builds, RTP profillari, lokallar.

2) Bayonnomalar va bazaviy qarorlar

Transport: HTTPS/JSON (ba’zan Event Bus/hamyon uchun gRPC).

Version:’Accept: application/vnd. rgs. v1 + json’ili ’/v1/...’; moslashuvchanlikning buzilishi - faqat yangi versiyalar orqali.

Identifikatsiya:’game _ id’,’build _ hash’,’operator _ id’,’session _ id’,’round _ id’,’spin _ id’.

Vaqt: qat’iy ravishda UTC, millisekundli ISO-8601.

Valyutalar: ISO-4217 + aniqlik (minor units). FX - operator/agregator tomonida.

3) Autentifikatsiya va avtorizatsiya

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

O’yinchining sessiyasi: short-lived JWT (platformaga imzo chekadi) c’sub’,’geo’,’rg _ flags’,’exp’,’aud = studio’.

Kirish roʻyxati: proto-konturlar uchun IP allowlist + mTLS.

4) Hamyon modellari: debit/credit vs transfer

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

1. Platforma RGSni chaqiradi:’SpinRequest (stake)’→ RGS natijani hisoblaydi → qaytaradi’win’.

2. Shu bilan birga, platforma o’z/operatorda’debit (stake)’va’credit (win)’ni yaratadi.

Afzalliklari: oddiy buxgalteriya. Kamchiliklar: ko’proq tarmoq qo’ng’iroqlari, idempotentlikka nisbatan qat’iy talablar.

B) Transfer (session balance):

1. Seans boshida platforma’transferIn (amount)’ni RGSda yaratadi.

2. RGS spinlari vaqtida sessiya balansini o’zi yuritadi; tugallanganda -’transferOut (remaining)’.

Afzalliklari: hamyon suhbatlari kamroq. Kamchiliklar: «RGS tomonida pul» hisobi, qo’shimcha xavflar va reconciliations.

Tavsiyalar:

Slotlar uchun idempotent kalitli debit/credit foydalaniladi.

Free spins va turnirlarda alohida stavkalar turiga ega bo’lish qulay’spin _ type = free	promo`.

5) Idempotentlik va kelishuv

Har bir pul qadami o’ziga xos’idempotency _ key’ga ega bo’lishi kerak (masalan,’round _ id’yoki’spin _ id’).

Takrorlash (’HTTP 409/425’) «xato allaqachon bajarilgan» emas, balki bir xil natijani qaytaradi.

Exactly-once ga erishish qiyin, shuning uchun biz at-least-once + idempotentlikni quramiz.

Idempotentlik’debit’,’credit’,’jackpot _ contribution’,’bonus _ award’ga tatbiq etiladi.

6) Asosiy so’rovlar sxemalari (qisqartirilgan)

6. 1. Sessiyani boshlash

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. Spin (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-…"
}

Javob:

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. Hodisa log (Event Bus, batch formati)

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) Byuld va market builds versiyalari

’build _ hash’ (SHA-256) - har bir hodisada majburiy.

Global vs Market build: til, ogohlantirish, stavkalarni cheklash, RTP profili.

Platforma: «Hozirda ushbu mamlakat sertifikatiga mos keladigan bild o’ynayaptimi?»

Matrix:’game _ id country .

8) RNG, matematika va replay

RNG RGS da yashaydi; biznes-mantiq «uchish» imkoniyatini o’zgartirmaydi.

Forensika uchun: raund/spin + mexanika versiyasi uchun’seed/nonce’.

Replay:’spin _ id ’/’ seed’bo’yicha RGS natijani takrorlaydi va audit izini beradi.

9) Responsible Gaming (RG) va komplayens-xuki

Vaqt/limit xoki:’session _ time _ ms’,’eslatmalar’, timeouts;’rg _ event’ga Event Bus.

O’zini istisno qilish/blok: bayroqda - darhol’403 RG_BLOCKED'.

UI invarantlari: platforma mijozning market build’dagi ogohlantirishlarni/yosh belgilarini ko’rsatishini tekshiradi.

10) Xatolar, retralar va SLA

Kodlar:’400’(validatsiya),’401/403’(autentifikatsiya/RG),’409’(idempotentlik mojarosi),’422’(biznes xatosi),’429’(rate limit),’5xx’(vaqtinchalik).

Retraj siyosati: eksponensial, idempotent kalitli va qabul qiluvchida deduplikatsiyaga ega.

SLA: API foydalanish imkoniyati ≥ 99. 9%, p95 latency uchun’spin’≤ 200-300 ms (mintaqaviy), Event Bus - near-real-time <60 s.

11) Kuzatuv va audit

Loglar:’trace _ id’bilan kesilmagan server loglari.

Metriklar: p95/p99 latency, error rate metodlari bo’yicha, RTP/bonuslar chastotalarining chetga chiqishi, «eligible spins» ulushi.

Alertlar: SLA bo’yicha, matematika anomaliyalari bo’yicha, hamyon nosozligining o’sishi bo’yicha.

Audit: stavkalar/natijalar hodisalari uchun WORM ombori; so’rov bo’yicha eksport qilish.

12) Xavfsizlik

mTLS + TLS 1. 2 +, HSTS, mijoz loaderida qattiq CORS.

Key-rotatsiya, qisqa TTL tokenlari, JTI/nonce-tekshiruvlar.

Mijoz uchun anti-tamper: assetalar imzosi, yaxlitlikni tekshirish, debaggerlardan himoya qilish.

Sirlar - faqat sir-menejerda; «o’yin konfigurasida kalit» yo’q.

13) Test muhitlari va sertifikatlashtirish

Sandbox: soxta hamyonlar, determinirlangan RNG (fixed seed), RG stsenariylarining avto muvaffaqiyatsizligi.

Staging: haqiqiy pulsiz prod-infra nusxasi.

Laboratoriyalar uchun to’plam: GDD/matematika, RNG-dosye, loglar sxemalari, repeatable build va xeshlar.

14) APIdagi promo va jekpotlar

Free Spins:’grant _ free _ spins (count, bet_size, rtp_profile?)’paketini uzatish; voqealar RGSda sarflanadi va loglar.

Turnirlar:’spin _ type = tournament’+ Event Bus’dagi alohida agregatlar.

Jekpotlar:’jackpot _ contribution’va’jackpot _ win’alohida tranzaksiyalar sifatida; idempotentlik va «imzolangan» voqealar orqali konsistentlik.

15) Hisobot va billing

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

Per-spin/turnover-fee:’eligible _ spins’yoki’Σ stake × rate’boʻyicha hisob.

Rev-share:’NetWin’dan «sharsharani» ushlab qolishdan keyin; FX/istisnolar uchun choraklik true-up.

16) Namunaviy ketma-ketliklar (so’z diagrammalari)

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 va muvofiqlik

Birinchi kontrakt (contract-first): OpenAPI/Protobuf - sxemalarning yagona manbai.

SemVer: Faqat maydonlarni qoʻshing; olib tashlash/o’zgartirish - v/v2.

Feature flags: (Bonus Buy/Ante) - faqat sertifikatlangan profillar orqali.

Deprecation: announce → grace period → harakatsiz hududlarda oʻchirish.

18) Chek varaqlari

Studiya → Platforma

OpenAPI/gRPC speklar va taxminiy fayllar.
Idempotentlik’spin/debit/credit/jackpot’.
’build _ hash’va market builds reyestri.
RNG replay va audit-log.
RG-xuklar va xatolar’403 RG_BLOCKED'.
Fix-seed, test hamyoni va avtosanariyali Sandbox.

Platforma → Studiya

Qisqa TTL, allowlist IP, mTLS bilan JWT-imzo.
Validator market builds va sertifikatlar.
Event Bus va dashbordlar (latency/error/RTP drift).
Kvotalar va rate-limits «429-Retry-After».
SLA/hodisalar/aloqa kanallari 24 × 7.

19) 30-60-90 ishga tushirish rejasi

0-30 kun

API shartnomalari va voqealar sxemalarini kelishish, hamyonning modelini tanlash.

Sandbox: fixed-seed RNG, test hamyon, idempotentlik avtotestlarini koʻtarish.

’build _ hash’ reyestri va birlamchi matritsasi market builds.

31-60 kun

Hamyon va spinlarni integratsiyalash; Event Bus va dashbordlarni yoqish.

Yuklash testlari (p95/p99), retray/idempotentlik, tarmoqning xaos-stsenariylari.

Komplayens: RG-xuki, lokali, age-labels; laboratoriyaga paket.

61-90 kun

1-2 operatorda uchuvchi, A/B promo (free spins/turnirlar).

True-up/hisobotlarni kiritish, RTP-dreyf/bonus-freq alertlari.

v2 yaxshilanishlarni tayyorlash: batch-event, gRPC uchun hamyon, geo-routing.

20) Qisqa FAQ

RTP/versiyasi qayerda tekshirilmoqda? ’build _ hash’ sertifikati mamlakat.

RTPni dinamik oʻzgartirish mumkinmi? Yo’q. Faqat oldindan sertifikatlangan profillar va faqat market build.

«Ikki marta debit» ni qanday hal qilish mumkin? Idempotent kaliti + tranzaksiya maqomini saqlash; takrorlash - natijani qaytaradi.

gRPC kerakmi? Yuqori hajmlarda hamyon/iventlar uchun foydalidir; REST meta maʼlumot/admin uchun qoladi.

Barqaror integratsiya - bu shartnomalar + idempotentlik + kuzatish. Voqealarning shaffof sxemalari, bild/bozorlar nazorati, RG-xuklar va versiyalar tartibi boshlanishdagi xavflarning 90 foizini olib tashlaydi. Keyingi - reklama va hisobotni avtomatlashtirish, qattiq SLA va «buzuvchi» o’zgarishlarsiz APIni ehtiyotkorlik bilan rivojlantirish.