Studiýalar bilen platformalaryň arasynda API integrasiýasy nähili işleýär

Studiýanyň (oýun üpjün edijisiniň) platforma/agregator bilen integrasiýasy - sessiýanyň, gapjygyň, arka netijesiniň we waka telemetriýasynyň töwereginde sinhron we asinhron jaňlaryň zynjyrydyr. Aşakda - gysga, ýöne amaly kartoçka, hemme zat döredijiler we laýyklyk üçin agyrysyz birleşdirilýär.

1) Eliňizdäki binagärlik

Aktýorlar:

Studio RGS (Remote Game Server) - oýnuň logikasy, RNG, bonuslar, jekpotlar.
Platforma/Agregator - marşrut, billing, mahabat, laýyklyk.
Operator - oýunçynyň gapjygy, KYC/RG, vitrin.
Müşderi - web/mobil oýun konteýneri (iframe/webview/native).

Esasy tekerler:

Sync API: sessiýalar, gapjyk, outcome.
Async/Event Bus: spin, bonus, jekpot, RG wakalary, tehniki ýalňyşlyklar.
Meta maglumatlar/katalog: oýunlar, market builds, RTP profilleri, lokallar.

2) Teswirnamalar we esasy çözgütler

Ulag: HTTPS/JSON (käwagt "Event Bus/gapjyk" üçin gRPC).

Wersiýasy: 'Accept: application/vnd. rgs. v1 + json 'ili '/v1/...'; laýyklygyň peselmegi - diňe täze wersiýalar arkaly.

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

Wagt: gaty UTC, ISO-8601 millisekuntda.

Walýuta: ISO-4217 + takyklyk (minor units). FX - operatoryň/agregatoryň tarapynda.

3) Tassyklamak we ygtyýarlandyrmak

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

Oýunçynyň sessiýasy: short-lived JWT (platforma gol çekýär) c 'sub', 'geo', 'rg _ flags', 'exp', 'aud = studio'.

Giriş sanawlary: Prod-konturlar üçin IP allowlist + mTLS.

4) Gapjyk modelleri: debit/credit vs transfer

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

1. Platforma RGS-i çagyrýar: 'SpinRequest (stake)' → RGS netijäni hasaplaýar → 'win' -i yzyna gaýtarýar.

2. Şol bir wagtyň özünde, platforma öz operatorynda 'debit (stake)' we 'credit (win)' edýär.

Artykmaçlyklary: ýönekeý buhgalteriýa. Minuslar: has köp onlaýn jaňlar, idempotentlige berk talaplar.

B) Transfer (session balance):

1. Sessiýanyň başynda platforma RGS-de 'transferIn (amount)' edýär.

2. Spin wagtynda RGS sessiýanyň balansyny özi ýöredýär; Tamamlananda - 'transferOut (remaining)'.

Artykmaçlyklary: gapjyk söhbetdeşlikleri az. Minuslar: "RGS tarapyndaky pullary" hasaba almak, goşmaça töwekgelçilikler we reconciliations.

Teklipler:

Slotlar üçin idempotent açarlary bolan debit/credit has köp ulanylýar.

Mugt spins we ýaryşlarda jedelleriň aýratyn görnüşleri bar 'spin _ type = free	promo`.

5) Idempotentlik we ylalaşyklylyk

Her pul ädiminde özboluşly 'idempotency _ key' bolmaly (mysal üçin 'round _ id' ýa-da 'spin _ id').

Gaýtalanmalar ('HTTP 409/425') "ýalňyşlyk eýýäm ýerine ýetirildi" däl-de, şol netijäni yzyna gaýtarýar.

Exactly-once gazanmak kyn, şonuň üçin at-least-once + idempotentligi gurýarys.

Idempotentligi 'debit', 'credit', 'jackpot _ contribution', 'bonus _ award' -a ýaýradýarys.

6) Esasy haýyşlaryň shemalary (gysgaldylan)

6. 1. Sessiýa başlamak

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-…"
}

Jogap:

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. Waka log (Waka Bus, batch formaty)

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) Bild wersiýalary we market builds

'build _ hash' (SHA-256) - her bir hadysada hökmany.

Global vs Market build: dil, duýduryş, nyrh çäklendirmeleri, RTP profili.

Platforma: "häzirki wagtda şol ýurduň şahadatnamasyna laýyk gelýän bild oýnaýarmy" diýip tassyklaýar.

Matrisa: 'game _ id country .

8) RNG, matematika we bellik

RNG RGS-de ýaşaýar; işewürlik logikasy "uçmak" mümkinçiligini üýtgetmeýär.

Forensika üçin: 'seed/nonce '/spin + mehanika wersiýasy.

Replay: 'spin _ id '/' seed' RGS netijäni gaýtalaýar we audit yzyny berýär.

9) Responsible Gaming (RG) we Complayens-huki

Wagt/çäk haklary: 'session _ time _ ms', 'ýatlatmalar', timeouts; 'rg _ event' -de Event Bus.

Öz-özüňi aýyrmak/blok: baýdakda - derrew '403 RG_BLOCKED'.

UI-Invariants: platforma, müşderiniň market build-den duýduryşlary/ýaş belliklerini görkezýändigini barlaýar.

10) Ýalňyşlyklar, retralar we SLA

Kodlar: '400' (tassyklama), '401/403' (autentifikasiýa/RG), '409' (idempotentlik gapma-garşylygy), '422' (iş ýalňyşlygy), '429' (rate limit), '5xx' (wagtlaýyn).

Retraýyň syýasaty: eksponensial, kabul edişde indempotent açary we de-duplikasiýa.

SLA: API elýeterliligi ≥ 99. 9%, p95 latency for 'spin' ≤ 200-300 ms (sebitleýin), Event Bus - near-real-time <60 s.

11) Gözegçilik we audit

Loglar: 'trace _ id' korelýasiýasy bolan kesilmedik serwer loglary.

Metrikler: p95/p99 latency, error rate, usullar boýunça, gyşarmalar RTP/ýygylyk bonuslary, paýy "eligible spins".

Alertler: SLA, matematikanyň anomaliýalary, gapjygyň şowsuzlygynyň ýokarlanmagy.

Audit: Jedelleriň/netijeleriň wakalary üçin WORM-ammar; talap boýunça eksport.

12) Howpsuzlyk

mTLS + TLS 1. 2 +, HSTS, müşderi ýükleýjisinde berk CORS.

Keý-rotasiýa, gysga TTL bellikleri, JTI/nonce-barlaglar.

Müşderi üçin anti-tamper: assetleriň gollary, bitewiligini barlamak, debaggerlerden goramak.

Syrlar - diňe gizlin dolandyryjyda; "oýun konfigasynda açar ýok".

13) Synag gurşawy we sertifikatlaşdyrmak

Sandbox: toslama gapjyklar, kesgitlenen RNG (fixed seed), RG ssenarileriniň awto-şowsuzlygy.

Staging: hakyky pulsyz prod-infranyň nusgasy.

Laboratoriýalar üçin paket: GDD/matematika, RNG-dossier, log shemalary, gaýtadan dikeldilýän bina we heş.

14) API-de mahabat we jekpotlar

Free Spins: bukjany geçirmek: 'grant _ free _ spins (count, bet_size, rtp_profile?)'; wakalar RGS-de sarp edilýär we loglar.

Ýaryşlar: 'spin _ type = tournament' atributy + Event Bus-daky aýry-aýry agregatlar.

Jekpotlar: 'jackpot _ contribution' we 'jackpot _ win' aýratyn amallar hökmünde; idempotentlik we "gol çekilen" wakalar arkaly yzygiderlilik.

15) Hasabat we billing

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

Per-spin/turnover-fee: 'eligible _ spins' ýa-da 'Σ stake × rate'.

Rev-share: "Şelaleden" soň 'NetWin' -den; FX/kadadan çykmalar üçin çärýekleýin true-up.

16) Nusgawy yzygiderlilik (söz diagrammalary)

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 we gabat gelmek

Ilki bilen şertnama (contract-first): OpenAPI/Protobuf - shemalaryň ýeke-täk çeşmesi.

SemVer: Diňe meýdanlary goşuň; aýyrmak/üýtgetmek - v/v2.

Feature flags: (Bonus Buy/Ante) opsiýalaryny goşmak - diňe tassyklanan profiller arkaly.

Deprecation: announce → grace period → hereketsiz sebitlerde öçürmek.

18) Çek-listler

Studiýa → Platforma

OpenAPI/gRPC-spekulýatorlar we takmynan pailoadlar.
Idempotentlik 'spin/debit/credit/jackpot'.
'build _ hash' we market builds sanawy.
RNG-bellik we audit-log.
RG-huki we ýalňyşlyklar '403 RG_BLOCKED'.
Fix-seed, synag gapjygy we awtosenariýalary bolan Sandbox.

Platforma → Studiýa

JWT-gysga TTL, allowlist IP, mTLS bilen gol.
Walidator market builds we şahadatnamalar.
Event Bus we dashbordlar (latency/error/RTP drift).
Kwotalar we dogruçyl seslenme bilen rate-limits '429-Retry-After'.
SLA/hadysalar/aragatnaşyk kanallary 24 × 7.

19) Işe girizmegiň 30-60-90 meýilnamasy

0-30 gün

API şertnamalary we wakalaryň shemalary barada ylalaşyň, gapjygyň modelini saýlaň.

Sandbox götermek: fixed-seed RNG, synag gapjygy, idempotentlik awtotestleri.

'build _ hash' sanawy we market builds başlangyç matrisi.

31-60 gün

Gapjygyň we arkalaryň integrasiýasy; "Event Bus" we "Dashboard" -lary öz içine alyň.

Ýükleýiş synaglary (p95/p99), retra/idempotentlik, toruň bulam-bujarlygy.

Gabat gelmek: RG-huki, lokallar, age-labels; laboratoriýa bukjasy.

61-90 gün

1-2 operatorda pilot, mahabat üçin A/B (erkin spins/ýaryşlar).

True-up/hasabat girişi, RTP-dreýf/bonus-freq alertleri.

v2 gowulaşmalary taýýarlamak: gapjyk çäreleri, gapjyk üçin gRPC, geo-routing.

20) Gysga FAQ

RTP/wersiýasy nirede barlanýar? Platfomda: 'build _ hash' ýurt.

RTP-ni dinamiki üýtgedip bolarmy? Ýok. Diňe öňünden tassyklanan profiller we diňe market build.

"Goşa debit" -i nädip çözmeli? Idempotent açary + geleşik statusyny saklamak; gaýtalamak - netijäni getirýär.

gRPC gerekmi? Uly göwrümli gapjyk/iwentler üçin peýdalydyr; REST metadata/administrator üçin galýar.

Durnukly integrasiýa - şertnamalar + idempotentlik + gözegçilik. Wakalaryň aç-açan shemalary, bild/bazarlara gözegçilik etmek, RG-huki we wersiýalaryň tertibi başda töwekgelçilikleriň 90% -ini aýyrýar. Soňra - mahabaty we hasabatlylygy awtomatlaşdyrmak, berk SLA we API-ni "döwýän" üýtgeşmeler bolmazdan seresaply ösdürmek.