Studiyalar və platformalar arasında API inteqrasiyası necə işləyir

Studiyanın platforma/aqreqator ilə inteqrasiyası sessiya, pul kisəsi, arxa nəticə və hadisə telemetriyası ətrafında sinxron və asenxron zənglər zənciridir. Aşağıda - qısa, lakin praktik xəritə, hər şey inkişaf etdiricilər və uyğunluq üçün ağrısız birləşir.

1) Palma üzərində memarlıq

Aktyorlar:

Studio RGS (Remote Game Server) - oyunun məntiqi, RNG, bonuslar, cekpotlar.
Platforma/Aqreqator - marşrutlaşdırma, billing, promo, komplayens.
Operator - oyunçunun cüzdanı, KYC/RG, vitrin.
Müştəri - web/mobile konteyner oyun (iframe/webview/native).

Əsas şinlər:

Sync API: sessiyalar, cüzdan, outcome.
Async/Event Bus: spin hadisələri, bonuslar, cekpotlar, RG, texniki səhvlər.
Metadata/kataloq: oyunlar, market builds, RTP profilləri, lokallar.

2) Protokollar və əsas həllər

Nəqliyyat: HTTPS/JSON (bəzən Event Bus/cüzdan üçün gRPC).

Versiyası: 'Accept: application/vnd. rgs. v1 + json 'və ya '/v1/...'; uyğunluğun deqradasiyası - yalnız yeni versiyalar vasitəsilə.

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

Vaxt: ciddi UTC, millisaniyələrlə ISO-8601.

Valyutalar: ISO-4217 + dəqiqlik (minor units). FX - operator/aqreqator tərəfində.

3) Autentifikasiya və avtorizasiya

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

Oyunçu sessiyası: short-lived JWT (platforma imzalayır) c 'sub', 'geo', 'rg _ flags', 'exp', 'aud = studio'.

Giriş siyahıları: Prod-konturlar üçün IP allowlist + mTLS.

4) Cüzdan modelləri: debit/credit vs transfer

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

1. Platforma RGS çağırır: 'SpinRequest (stake)' → RGS nəticəsini hesablayır → qaytarır 'win'.

2. Paralel olaraq, platforma debit (stake) və credit (win) edir.

Üstünlüklər: sadə mühasibat. Mənfi cəhətləri: daha çox şəbəkə çağırışları, ciddi idempotentlik tələbləri.

B) Transfer (session balance):

1. Seansın əvvəlində platforma RGS-də 'transferIn (amount)' edir.

2. Spin zamanı RGS özü sessiyanın balansını aparır; tamamlandıqda - 'transferOut (remaining)'.

Üstünlüklər: daha az cüzdan söhbətləri. Mənfi cəhətləri: «RGS tərəfində pul» uçotu, əlavə risklər və reconciliations.

Tövsiyələr:

Slotlarda daha çox idempotent açarları olan debit/credit istifadə olunur.

Free spins və turnirlərdə spin _ type = free	promo`.

5) İdempotentlik və uyğunluq

Hər bir pul addımı unikal 'idempotency _ key' olmalıdır (məsələn, 'round _ id' və ya 'spin _ id').

Təkrar ('HTTP 409/425') «səhv artıq yerinə yetirilib» deyil, eyni nəticəni qaytarır.

Exactly-once nail olmaq çətindir, buna görə at-least-once + idempotentlik qurmaq.

İdempotentlik: 'debit', 'credit', 'jackpot _ contribution', 'bonus _ award'.

6) Əsas sorğu sxemləri (qısaldılmış)

6. 1. Sessiyaya start

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

Cavab:

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. Hadisə Log (Event Bus, Batch formatı)

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) Binaların versiyası və market builds

'build _ hash' (SHA-256) - hər bir hadisə üçün məcburidir.

Global vs Market build: dil, xəbərdarlıqlar, bahis məhdudiyyətləri, RTP profili.

Platforma validasiya edir: 'bu ölkənin sertifikatına uyğun olan bild indi oynayır ".

Matris: 'game _ id country .

8) RNG, riyaziyyat və reple

RNG RGS yaşayır; biznes məntiqi «uçmaq» şansını dəyişmir.

Forensika üçün: raund/spin + mexanika versiyası üçün 'seed/nonce'.

Replay: 'spin _ id '/' seed' RGS nəticəni təkrarlayır və audit izini verir.

9) Responsible Gaming (RG) və komplayens-huki

Zaman/limit Hook: 'session _ time _ ms', «xatırlatmalar», timeouts; 'rg _ event' in Event Bus.

Özünü istisna/blok: bayraqda - dərhal '403 RG_BLOCKED'.

UI invariantları: platforma müştərinin market build-dan xəbərdarlıq/yaş etiketlərini göstərdiyini yoxlayır.

10) Səhvlər, retralar və SLA

Kodlar: '400' (validasiya), '401/403' (autentifikasiya/RG), '409' (idempotentlik münaqişəsi), '422' (biznes səhvi), '429' (rate limit), '5xx' (müvəqqəti).

Retraj siyasəti: eksponensial, idempotent açar və qəbuledicidə deduplikasiya.

SLA: API mövcudluğu ≥ 99. 9%, p95 latency üçün 'spin' ≤ 200-300 ms (regional), Event Bus - near-real-time <60 s.

11) Müşahidə və audit

Qeydlər: 'trace _ id' korelyasiyası ilə kəsilməmiş server qeydləri.

Metriklər: p95/p99 latency, metodlara görə error rate, RTP/bonus tezliklərinin sapmaları, «eligible spins» payı.

Alertlər: SLA, riyaziyyat anomaliyaları, cüzdan uğursuzluqlarının artması.

Audit: bahis/nəticə hadisələri üçün WORM-saxlama; tələb üzrə ixrac.

12) Təhlükəsizlik

mTLS + TLS 1. 2 +, HSTS, müştəri loader ciddi CORS.

Key-rotasiya, qısa TTL tokenləri, JTI/nonce-yoxlamalar.

Müştəri üçün anti-tamper: asset imzaları, bütövlük yoxlaması, debagger qorunması.

Sirlər - yalnız gizli menecerdə; heç bir «oyun konfiqasında açar».

13) Test mühitləri və sertifikatlaşdırma

Sandbox: uydurma pul kisələri, determinated RNG (fixed seed), avto uğursuzluq RG ssenariləri.

Staging: real pul olmadan prod infra surəti.

Laboratoriyalar üçün paket: GDD/riyaziyyat, RNG dosyesi, log sxemləri, repeatable build və hash.

14) Promo və API cekpotlar

Free Spins: paketin ötürülməsi: 'grant _ free _ spins (count, bet_size, rtp_profile?)'; hadisələr RGS sərf və loging.

Turnirlər: 'spin _ type = tournament' atributu + Event Bus-da ayrı-ayrı aqreqatlar.

Jackpotlar: 'jackpot _ contribution' və 'jackpot _ win' ayrı-ayrı əməliyyatlar kimi; idempotentlik və «imzalanmış» hadisələr vasitəsilə sabitlik.

15) Hesabat və billing

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

Per-spin/turnover-fee: 'eligible _ spins' və ya 'Σ stake × rate' hesabı.

Rev-share: «şəlalədən» sonra «NetWin» -dən; FX/istisnalar üçün üç aylıq true-up.

16) Tipik ardıcıllıqlar (şifahi diaqramlar)

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 və uyğunluq

İlk müqavilə (contract-first): OpenAPI/Protobuf - sxemlərin vahid mənbəyi.

SemVer: Yalnız sahələr əlavə edin; silinməsi/dəyişdirilməsi - v/v2.

Feature flags: Seçenəklərin daxil edilməsi (Bonus Buy/Ante) - yalnız sertifikatlı profillər vasitəsilə.

Deprecation: announce → grace period → aktiv olmayan bölgələrdə off.

18) Çek vərəqləri

Studiya → Platforma

OpenAPI/gRPC paylayıcıları və nümunəvi paylayıcılar.
İdempotentlik 'spin/debit/credit/jackpot'.
'build _ hash' və reyestr market builds.
RNG replay və audit log.
RG-huki və səhvlər '403 RG_BLOCKED'.
Fiks-seed, test-cüzdan və avtosenariyalar ilə Sandbox.

Platforma → Studiya

Qısa TTL, allowlist IP, mTLS ilə JWT imzası.
Validator market builds və sertifikatlar.
Event Bus və dashboard (latency/error/RTP drift).
Kvotalar və rate-limits dürüst rəy ilə '429-Retry-After'.
SLA/insidentlər/rabitə kanalları 24 × 7.

19) 30-60-90 başlanğıc planı

0-30 gün

API müqavilələri və hadisələr sxemləri ilə razılaşın, cüzdan modelini seçin.

Sandbox qaldırın: fixed-seed RNG, test cüzdan, idempotentlik avtomatik testlər.

'build _ hash' reyestri və birincil matris market builds.

31-60 gün

cüzdan və spins inteqrasiya; Event Bus və dashboard daxildir.

Yük testləri (p95/p99), retraj/idempotentlik, xaos şəbəkə ssenariləri.

Komplayens: RG-huki, lokal, age-labels; laboratoriya paketi.

61-90 gün

1-2 operatorda pilot, promosyonda A/B (pulsuz spins/turnirlər).

true-up/hesabatların daxil edilməsi, RTP-dreyf/bonus-freq alertləri.

v2 təkmilləşdirmələri hazırlamaq: batch hadisələr, cüzdan üçün gRPC, geo-routing.

20) Qısa FAQ

RTP/versiyası harada yoxlanılır? Platformada: 'build _ hash' sertifikatı ölkə.

RTP dinamik olaraq dəyişdirilə bilərmi? Yox. Yalnız əvvəlcədən sertifikatlaşdırılmış profillər və yalnız market build keçid.

«Double debit» necə həll etmək olar? İdempotent açarı + əməliyyat statusunun saxlanması; təkrar - nəticə verir.

gRPC lazımdır? Yüksək həcmdə cüzdan/tədbirlər üçün faydalıdır; REST metadata/admin üçün qalır.

Sabit inteqrasiya müqavilələr + idempotentlik + müşahidə qabiliyyətidir. Şəffaf hadisə sxemləri, binaların/bazarların nəzarəti, RG-huki və nizam-intizam versiyaları başlanğıcda risklərin 90% -ni aradan qaldırır. Sonra - promo və hesabat avtomatlaşdırılması, sərt SLA və «qırıcı» dəyişikliklər olmadan API-nin diqqətli inkişafı.