Stüdyolar ve platformlar arasında API entegrasyonu nasıl çalışır

Stüdyonun (oyun sağlayıcısı) platform/toplayıcı ile entegrasyonu, oturum, cüzdan, spin sonucu ve olay telemetrisi etrafında senkronize ve asenkron aramalar zinciridir. Aşağıda, geliştiriciler ve uyumluluk için her şeyin acı çekmeden nasıl bağlandığına dair kısa ama pratik bir harita bulunmaktadır.

1) Avucunuzun içindeki mimari

Aktörler:

Studio RGS (Uzaktan Oyun Sunucusu) - oyun mantığı, RNG, bonuslar, ikramiyeler.
Platform/Toplayıcı - yönlendirme, faturalandırma, promosyon, uyumluluk.
Operatör - oyuncunun cüzdanı, KYC/RG, vitrin.
Müşteri - web/mobil oyun konteyneri (iframe/webview/native).

Ana otobüsler:

API'yi senkronize edin: oturumlar, cüzdan, sonuç.
Async/Event Bus: spin etkinlikleri, bonuslar, ikramiyeler, RG, teknik hatalar.
Meta veriler/katalog: oyunlar, pazar yapıları, RTP profilleri, yerel ayarlar.

2) Protokoller ve temel çözümler

Taşıma: HTTPS/JSON (bazen Olay Veriyolu/Cüzdan için gRPC).

Sürüm oluşturma: 'Accept: application/vnd. Rgs. v1 + json 'veya'/v1/...'; Uyumluluk bozulması - sadece yeni sürümlerle.

Tanımlama: 'game _ id', 'build _ hash', 'operator _ id', 'session _ id', 'round _ id', 'spin _ id'.

Zaman: kesinlikle UTC, milisaniye ile ISO-8601.

Para birimleri: ISO-4217 + doğruluk (küçük birimler). FX - operatör/toplayıcı tarafı.

3) Kimlik doğrulama ve yetkilendirme

Sunucudan sunucuya: OAuth2 İstemci Kimlik Bilgileri или HMAC- подпись ('X-Signature: HMAC_SHA256 (payload, shared_key)').

Oyuncu oturumu: kısa ömürlü JWT (işaret platformu) c 'sub', 'geo','rg _ flags ',' exp ',' aud = studio '.

Erişim listeleri: IP, üretim döngüleri için + mTLS'ye izin verir.

4) Cüzdan modelleri: banka/kredi vs transfer

A) Borç/Kredi (anında):

1. Platform RGS'yi çağırır: 'SpinRequest (bahis)' - RGS sonucu hesaplar - 'kazan' döndürür.

2. Buna paralel olarak, platform operatörün yerinde 'debit (stake)'ve' credit (win) 'yapar.

Artılar: Basit defter tutma. Eksileri: daha fazla ağ çağrısı, idempotency için katı gereksinimler.

B) Transfer (oturum bakiyesi):

1. Oturumun başında, platform RGS'de 'transferIn (miktar)' yapar.

2. Spinler sırasında, RGS'nin kendisi oturumu dengeler; tamamlandığında - 'transferOut (kalan)'.

Artılar: Daha az cüzdan sohbeti. Eksileri: "RGS tarafında para", ek riskler ve mutabakatlar için muhasebe.

Öneriler:

Yuvalar için, idempotent anahtarlı borç/kredi daha sık kullanılır.

Ücretsiz dönüşlerde ve turnuvalarda ayrı bahis türlerinin olması uygundur 'spin _ type = free	promo '.

5) Idempotency ve tutarlılık

Her para adımında benzersiz bir 'idempotency _ key' (örneğin, 'round _ id' veya 'spin _ id') olmalıdır.

Duplicates ('HTTP 409/425'), "zaten yürütülen bir hata'değil, aynı sonucu döndürür.

Tam olarak bir kez elde etmek zordur, bu yüzden en az bir kez + idempotency oluştururuz.

Idempotence şu şekilde genişletilir: 'debit', 'credit', 'jackpot _ contribution', 'bonus _ award'.

6) Anahtar sorgu şemaları (kısaltılmış)

6. 1. Oturum başlangıcı

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 (borç/kredi)

Json
POST/rgs/v1/spins
{
"spin_id": "spin-...", "round_id": "rnd-...", "session_id": "s-...", "kazık": {"miktar": 1. 00, "para birimi": "EUR"}, "spin_type": "nakit", "idempotency_key": "spin-"...
}

Cevap:

Json
{
"spin_id": "spin-...", "sonuç": {
"win": {"miktar": 3. 40, "para birimi": "EUR"}, "özellikler": [{"type ": "bonus _ trigger ", "name":" FreeSpins"," count": 10}], "semboller": "opak-veya-atlanmış"
}, "rgs_txns": [
{"type ": "jackpot _ contribution"," amount": 0. 01}
], "telemetry_ref": "evt-"..
}

6. 3. Olay Otobüsü

Json
POST/rgs/v1/events/batch
{
"olaylar": [
{
"type ": "spin _ finished", "ts ":" 2025-10-20T11: 22:33. 123Z," "spin_id":"spin-...," "round_id":"rnd-...," "kazık": 1. 00, "kazan": 3. 40, "para birimi": "EUR", "game_id":"g-...,""build_hash":"sha256:...," player_id":"p-...,""operator_id":"op-..., "spin_type":"cash"
}
]
}

7) Sürüm oluşturma ve pazar oluşturma

'build _ hash' (SHA-256) - her etkinlikte gereklidir.

Global vs Market yapısı: dil, uyarılar, oran sınırları, RTP profili.

Platform şunları doğrular: "Şu anda oynanan ve belirli bir ülkenin sertifikasıyla eşleşen bir yapıdır".

Matrix: 'game _ id ülke .

8) RNG, Matematik ve Tekrar

RNG RGS'de yaşıyor; İş mantığı anında şansı değiştirmez.

Adli tıp için: Yuvarlak/spin + mekanik versiyon başına 'tohum/nonce'.

Tekrarlama: 'Spin _ id'/' seed'ile, RGS sonucu yeniden üretir ve bir denetim izi verir.

9) Sorumlu Oyun (RG) ve uyumluluk kancaları

Hooks of time/limits: 'session _ time _ ms', "reminders", zaman aşımları; Event Bus'ta'rg _ event '.

Kendini dışlama/blok: bayraklı - hemen '403 RG_BLOCKED'.

UI değişmezleri: Platform, müşterinin piyasa yapısından uyarılar/yaş etiketleri gösterdiğini kontrol eder.

10) Hatalar, Retrays ve SLA'lar

Kodlar: '400' (doğrulama), '401/403' (kimlik doğrulama/RG), '409' (idempotency çakışması), '422' (iş hatası), '429' (oran sınırı), '5xx' (geçici).

Retray ilkesi: üstel, alıcıda bir idempotent anahtar ve veri tekilleştirme ile.

SLA ≥99 API kullanılabilirliği. 9 %, 'spin' için p95 gecikme süresi ≤200 -300 ms (bölgesel), Event Bus - neredeyse gerçek zamanlı <60 s.

11) Gözlemlenebilirlik ve denetim

Günlükler: 'trace _ id' korelasyonuna sahip kesilmemiş sunucu günlükleri.

Metrikler: p95/p99 gecikme, yöntemlere göre hata oranı, RTP/bonus frekanslarının sapmaları, "elastik spinlerin" oranı.

Uyarılar: SLA tarafından, matematik anomalileri tarafından, cüzdan başarısızlıklarındaki artışla.

Denetim: Bahis/sonuç etkinlikleri için WORM depolama; Talep üzerine ihracat.

12) Güvenlik

mTLS + TLS 1. 2 +, HSTS, istemci yükleyici üzerinde sıkı CORS.

Anahtar döndürme, kısa TTL belirteçleri, JTI/nonce kontrolleri.

İstemci için anti-kurcalayıcı: varlık imzaları, bütünlük denetimi, hata ayıklayıcı koruması.

Sırlar - sadece gizli yöneticide; "Oyunun konfigürasyonunda anahtar yok".

13) Test ortamları ve sertifikasyon

Sandbox: hayali cüzdanlar, deterministik RNG (sabit tohum), RG senaryolarının otomatik başarısızlığı.

Evreleme: gerçek para olmadan prod-infra bir kopyası.

Laboratuvarlar için paket: GDD/matematik, RNG dosyası, log diyagramları, tekrarlanabilir yapı ve hash.

14) API'da tanıtımlar ve ikramiyeler

Free Spins: paket transferi: 'grant _ free _ spins (count, bet_size, rtp_profile?)'; Olaylar RGS'de geçirilir ve kaydedilir.

Turnuvalar: 'spin _ type = tournament' özniteliği + Event Bus'taki bireysel toplamlar.

Jackpotlar: Ayrı işlemler olarak 'jackpot _ contribution've' jackpot _ win '; idempotency ve "imzalı" olaylar yoluyla tutarlılık.

15) Raporlama ve Faturalandırma

Блоки выгрузок: 'spins _ total', 'eligible _ spins', 'ciro', 'gr', 'netwin', 'jackpot _', 'bonus _ cost', 'royalty _ due'.

Per-spin/ciro-ücreti: 'eligible _ spins' veya 'Σ bahis × oranı'ile hesap.

Rev-share: 'şelale' sonra 'NetWin' tutar; FX/istisnalar için üç aylık gerçek.

16) Tipik diziler (kelime çizelgeleri)

Spin (borç/kredi):

Client? Platform: StartRound? Platform? RGS: Spin? RGS? Platform: Outcome? Platform? Wallet: Debit? Platform? Wallet: Credit? Platform? Client: Result? Platform? EventBus: spin_finished.

Bedava Spinler:

Platform> RGS: GrantFreeSpins> İstemci: Başlat> RGS: Her birini tüket/Kaydet> EventBus: spin_finished (spin_type=free).

17) Değişim yönetimi ve birlikte çalışabilirlik

Contract-first: OpenAPI/Protobuf tek bir şema kaynağıdır.

SemVer: sadece alan ekle; sil/değiştir - in/v2.

Özellik bayrakları-Yalnızca sertifikalı profiller aracılığıyla seçenekleri (Bonus Satın Alma/Ante) etkinleştirin.

Reddetme: duyurmak - ödemesiz dönem - etkin olmayan bölgelerde kapatma.

18) Kontrol listeleri

Stüdyo - Platform

OpenAPI/gRPC özellikleri ve örnek yükler.
IDempotency 'spin/debit/credit/jackpot'.
'build _ hash've piyasa kayıt oluşturur.
RNG kopyaları ve denetim günlüğü.
RG kancaları ve hatalar '403 RG_BLOCKED'.
Fix-seed, test cüzdanı ve otomatik komut dosyaları ile sandbox.

Platform - Stüdyo

Kısa TTL, allowlist IP, mTLS ile JWT imzası.
Piyasa yapılarının ve sertifikaların doğrulayıcısı.
Olay Veriyolu ve gösterge panoları (gecikme/hata/RTP sürüklenmesi).
Dürüst geribildirim ile kotalar ve oran limitleri '429-Retry-After'.
SLA'lar/Olaylar/Bağlantılar 24 × 7.

19) 30-60-90 fırlatma planı

0-30 gün

API sözleşmeleri ve olay şemaları üzerinde anlaşın, bir cüzdan modeli seçin.

Kum havuzunu yükseltin: sabit tohum RNG, test cüzdanı, idempotency'nin ototestleri.

Kayıt defteri 'build _ hash've birincil matris piyasası oluşturur.

31-60 gün

Cüzdan ve spin entegrasyonu; Olay Veriyolu ve panoları etkinleştir.

Yük testleri (p95/p99), retrai/idempotency, ağ kaos senaryoları.

Uyumluluk: RG kancaları, lokaller, yaş etiketleri; Laboratuara paketle.

61-90 gün

1-2 operatör için pilot, promosyon için A/B (ücretsiz dönüşler/turnuvalar).

True-up/raporlama, RTP drift uyarıları/bonus-freq giriliyor.

V2 iyileştirmelerinin hazırlanması: toplu etkinlikler, cüzdan için gRPC, coğrafi yönlendirme.

20) Kısa SSS

RTP/sürüm nerede kontrol edilir? Platformda: 'build _ hash' ↔ sertifika ↔ ülke.

RTP dinamik olarak değiştirilebilir mi? Hayır. Yalnızca önceden onaylanmış profiller ve yalnızca anahtarlamalı pazar yapısı.

"Çift borç" nasıl çözülür? Idempotent anahtar + işlem durumunu saklama; redo-Sonucu döndürür.

Bir gRPC'ye ihtiyacım var mı? Yüksek hacimlerde cüzdan/etkinlikler için yararlıdır; REST, meta veriler/yönetici paneli için kalır.

Kararlı entegrasyon, sözleşmeler + idempotency + gözlemlenebilirliktir. Şeffaf etkinlik şemaları, yapı/pazar kontrolü, RG kancaları ve sürüm disiplini başlangıçta risklerin %90'ını ortadan kaldırır. Ayrıca - promosyon ve raporlama otomasyonu, sert SLA ve API'nin "kırılma" değişiklikleri olmadan dikkatli bir şekilde geliştirilmesi.