Cum funcționează integrarea API între studiouri și platforme

Integrarea studioului (furnizorului de jocuri) cu platforma/agregatorul este un lanț de apeluri sincrone și asincrone în jurul sesiunii, portofelului, rezultatului rotirii și telemetriei evenimentului. Mai jos este o hartă scurtă, dar practică a modului în care totul se conectează fără durere pentru dezvoltatori și conformitate.

1) Arhitectura în palmă

Actori:

Studio RGS (Server de jocuri la distanță) - logica jocului, RNG, bonusuri, jackpot-uri.
Platformă/Agregator - rutare, facturare, promo, conformitate.
Operator - portofelul jucătorului, KYC/RG, casetă de prezentare.
Client - container de jocuri web/mobile (iframe/webview/nativ).

Autobuze principale:

Sincronizare API: sesiuni, portofel, rezultat.
Async/Event Bus: evenimente de spin, bonusuri, jackpot-uri, RG, erori tehnice.
Metadate/catalog: jocuri, market builds, profile RTP, localizări.

2) Protocoale și soluții de bază

Transport: HTTPS/JSON (uneori gRPC pentru Event Bus/Wallet).

Versioning: 'Accept: cerere/vnd. rgs. v1 + json "sau "/v1/"...; degradarea compatibilității - numai prin versiuni noi.

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

Timp: strict UTC, ISO-8601 cu milisecunde.

Valute: ISO-4217 + precizie (unități minore). FX - operator/agregator lateral.

3) Autentificare și autorizare

Server-to-server: OAuth2 Client Acreditări или HMAC- подпись ('X-Signature: HMAC_SHA256 (sarcină utilă, shared_key)').

Player session: JWT (signs platform) de scurtă durată c 'sub', 'geo', 'rg _ flags',' exp ',' aud = studio '.

Liste de acces: IP permite + mTLS pentru bucle de producție.

4) Modele de portofel: debit/credit vs transfer

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

1. Platforma apelează RGS: 'SpinRequest (miză)' → RGS calculează rezultatul → returnează 'win'.

2. În paralel, platforma face „debit (miză)” și „credit (câștig)” la locul operatorului.

Pro: Contabilitate simplă. Contra: mai multe apeluri de rețea, cerințe stricte pentru idempotență.

B) Transfer (sold sesiune):

1. La începutul sesiunii, platforma face „transferIn (suma)” pe RGS.

2. În timpul rotirilor, RGS în sine echilibrează sesiunea; la finalizare - „TransferOut (rămas)”.

Pro: Mai puține chat-uri cu portofel. Contra: contabilizarea „banilor pe partea de RGS”, riscuri suplimentare și reconcilieri.

Recomandări:

Pentru sloturi, debitul/creditul cu chei idempotente este mai des utilizat.

La rotirile gratuite și turnee este convenabil să aveți tipuri de pariuri separate 'spin _ type = free	promo ".

5) Idempotență și consecvență

Fiecare pas de bani trebuie să aibă o „idempotency _ key” unică (de exemplu, „round _ id' sau” spin _ id').

Duplicatele ('HTTP 409/425') returnează același rezultat, nu o „eroare deja executată”.

Exact-o dată este dificil de realizat, așa că construim cel puțin o dată + idempotență.

Idempotence este extins la: 'debit', 'credit', 'jackpot _ contribution', 'bonus _ award'.

6) Scheme de interogare cheie (abreviat)

6. 1. Începerea sesiunii

json
POST/rgs/v1/sesiuni
{
"session_id":" s- "...," operator_id": "op-", "player_id":" p- "," game_id": "g-BookOf"..., "build_hash":" sha256: "...," jwt': "eyJhbGci"..., "geo": "DE", "valută": "EUR", "rg_flags": {" self _ exclused ": fals', time_limit_min": 60}
}

6. 2. Spin (debit/credit)

json
POST/rgs/v1/rotiri
{
"spin_id": "spin-"..., "round_id": "rnd-"..., "session_id": "s-"..., "miza": {"suma": 1. 00, „valută”: „EUR”} „, spin_type": „cash”, „idempotency_key": „spin-”...
}

Răspuns:

json
{
"spin_id": "spin-"..., "rezultat": {
„win”: {„cantitate”: 3. 40, „valută”: „EUR”}, „caracteristici”: [{„tip „: „bonus _ trigger „, „nume”:” FreeSpins”,” număr”: 10}], „simboluri”: „opac-sau-omis”
", rgs_txns": [
{„tip „: „jackpot _ contribution”,” sumă”: 0. 01}
", telemetry_ref": "evt-"..
}

6. 3. Eveniment Autobuz

json
POST/rgs/v1/evenimente/lot
{
„evenimente”: [
{
„type”: „spin _ finished”, „ts':” 2025-10-20T11: 22:33. 123Z, „” spin_id":"spin-..., „round_id":"rnd-...,” „miză”: 1. 00, „win”: 3. 40, „monedă”:” EUR”, „game_id":"g-...,""build_hash":"sha256:...,” „player_id":"p-...,""operator_id":"op-...,” spin_type":"cash „”
}
]
}

7) Versioning construiește și construiește piața

'build _ hash' (SHA-256) - necesar la fiecare eveniment.

Global vs Market build: limbă, avertismente, limite de rată, profil RTP.

Platforma validează: „este o construcție jucată în prezent care se potrivește cu certificatul unei anumite țări”.

Matrix: 'game _ id country .

8) RNG, matematică și reluare

RNG trăiește pe RGS; logica de afaceri nu schimbă șansele pe zbor.

Pentru criminalistică: „semințe/nonce” pe rotund/rotire + versiune mecanică.

Replay: prin 'spin _ id'/' seed', RGS reproduce rezultatul și oferă o pistă de audit.

9) Joc responsabil (RG) și cârlige de conformitate

Cârlige de timp/limite: 'session _ time _ ms', „reminders”, timeout; 'rg _ event' în Event Bus.

Auto-excludere/bloc: cu pavilion - imediat '403 RG_BLOCKED'.

UI invariante: platforma verifică dacă clientul prezintă avertismente/etichete de vârstă de pe piață construi.

10) Bug-uri, Retray-uri și SLA-uri

Coduri: „400” (validare), „401/403” (autentificare/RG), „409” (conflict de idempotență), „422” (eroare de afaceri), „429” (limită de rată), „5xx” (temporar).

Politica Retray: exponențial, cu o cheie idempotent și deduplicare la receptor.

SLA ≥99 API disponibilitate. 9%, p95 latență pentru 'spin' ≤200 -300 ms (regional), Event Bus - aproape în timp real <60 s.

11) Observabilitate și audit

Jurnale: jurnale de server netăiate cu corelație "trace _ id'.

Metrici: p95/p99 latență, rata de eroare prin metode, abateri ale frecvențelor RTP/bonus, proporția de „rotiri elastice”.

Alerte: prin SLA, prin anomalii matematice, prin creșterea eșecurilor portofelului.

Audit: stocare WORM pentru evenimente de pariuri/rezultate; export la cerere.

12) Siguranță

mTLS + TLS 1. 2 +, HSTS, CORS strict pe încărcătorul clientului.

Rotație cheie, jetoane TTL scurte, verificări JTI/nonce.

Anti-tamper pentru client: semnături de active, verificarea integrității, protecția depanatorului.

Secretele - numai în managerul secret; nici o „cheie în configurarea jocului”.

13) Medii de testare și certificare

Sandbox: portofele fictive, RNG determinist (semințe fixe), eșecul automat al scenariilor RG.

Montarea: o copie a prod-infra fără bani reali.

Pachet pentru laboratoare: GDD/matematică, dosar RNG, diagrame jurnal, construcție repetabilă și hash-uri.

14) Promo-uri și jackpot-uri în API

Învârtiri gratuite: transfer de pachete: 'grant _ free _ spins (count, bet_size, rtp_profile?)'; evenimentele sunt petrecute în RGS și înregistrate.

Turnee: atribut 'spin _ type = turneu' + agregate individuale în Event Bus.

Jackpot-uri: 'jackpot _ contribution' și 'jackpot _ win' ca tranzacții separate; consecvență prin idempotență și evenimente „semnate”.

15) Raportarea și facturarea

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

Per-spin/turnover-fee: cont by 'eligible _ spins' sau 'Σ miză × rată'.

Rev-share: de la „NetWin” după „cascadă” deține; verificare trimestrială pentru FX/excepții.

16) Secvențe tipice (diagrame de cuvinte)

Spin (debit/credit):

Platforma de a clientului: Platforma de StartRound RGS: Platforma de Spin RGS: Platforma Platforma de debit

Rotiri gratuite:

Platforma RGS: GrantFreeSpins Client: Start RGS: Consumați/Conectați fiecare EventBus: (.

17) Managementul schimbărilor și interoperabilitatea

Contract-first: OpenAPI/Protobuf este o singură sursă de scheme.

SemVer: numai adăugați câmpuri; sterge/modifica - in/v2.

Opțiuni de activare a steagurilor (Bonus Buy/Ante) numai prin intermediul profilurilor certificate.

Respingere: anunțați → perioadă de grație → închiderea în regiunile inactive.

18) Liste de verificare

Platforma → Studio

Specificații OpenAPI/gRPC și sarcini utile de probă.
IDempotency 'spin/debit/credit/jackpot'.
'build _ hash' și piața construiește registru.
Replici RNG și jurnal de audit.
Cârlige RG și erori '403 RG_BLOCKED'.
Sandbox cu semințe fixe, portofel de testare și scripturi auto.

Platforma → Studio

Semnătură JWT cu TTL scurt, IP allowlist, mTLS.
Validatorul pieței construiește și certificate.
Event Bus și tablouri de bord (latență/eroare/derivă RTP).
Cote și limite de rată cu feedback onest '429-Retry-After'.
SLAs/Incidente/Link-uri 24 × 7.

19) Planul de lansare a 30-60-90

0-30 zile

Conveniți asupra contractelor API și schemelor de evenimente, alegeți un model de portofel.

Raise sandbox: RNG cu semințe fixe, portofel de testare, autoteste de idempotență.

Registry 'build _ hash' și piața primară matrice construiește.

31-60 zile

Integrarea portofel și spin; activați Event Bus și tablouri de bord.

Teste de încărcare (p95/p99), retrai/idempotency, scenarii de haos de rețea.

Conformitate: cârlige RG, localizări, etichete de vârstă; pachet la laborator.

61-90 zile

Pilot pentru 1-2 operatori, A/B pentru promo (rotiri gratuite/turnee).

Introducerea true-up/raportare, alerte RTP drift/bonus-freq.

Pregătirea v2 îmbunătățiri: evenimente de lot, gRPC pentru portofel, geo-rutare.

20) Întrebări frecvente scurte

Unde este verificat RTP/versiune? Pe platformă: „build _ hash” ↔ certificat ↔ țară.

Poate fi schimbat dinamic RTP? Nu, nu este. Numai profiluri pre-certificate și numai construcția pieței de comutare.

Cum de a rezolva „debit dublu”? Cheie idempotentă + starea tranzacției de stocare; redo-Returnează rezultatul.

Am nevoie de un gRPC? Util pentru portofel/evenimente la volume mari; REST rămâne pentru panoul de metadate/admin.

Integrarea stabilă este contracte + idempotență + observabilitate. Schemele transparente de evenimente, controlul construirii/pieței, cârligele RG și disciplina versiunii elimină 90% din riscuri la început. În continuare - automatizarea promo și de raportare, SLA greu și dezvoltarea atentă a API fără „rupere” modificări.