Wie API-Integration zwischen Studios und Plattformen funktioniert

Die Integration des Studios (Spieleanbieter) mit der Plattform/dem Aggregator ist eine Kette von synchronen und asynchronen Anrufen rund um Sitzung, Wallet, Spin-Ergebnis und Ereignistelemetrie. Unten ist eine kurze, aber praktische Karte, wie alles ohne Schmerzen für Entwickler und Compliance verbindet.

1) Architektur in der Handfläche

Akteure:

Studio RGS (Remote Game Server) - Spiellogik, RNG, Boni, Jackpots.
Plattform/Aggregator - Routing, Abrechnung, Promo, Compliance.
Betreiber ist die Geldbörse des Spielers, KYC/RG, Schaufenster.
Client - Web/Mobile Container Spiele (iframe/webview/native).

Hauptreifen:

Sync API: Sitzungen, Wallet, Outcome.
Async/Event Bus: Ereignisse von Spins, Boni, Jackpots, RG, technische Fehler.
Metadaten/Katalog: Spiele, Market Builds, RTP-Profile, Locals.

2) Protokolle und Basislösungen

Transport: HTTPS/JSON (manchmal gRPC für Event Bus/Wallet).

Versionierung: 'Accept: application/vnd. rgs. v1 + json "oder "/v1/..."; Verschlechterung der Kompatibilität - nur durch neue Versionen.

Identifizierung: „game _ id“, „build _ hash“, „operator _ id“, „session _ id“, „round _ id“, „spin _ id“.

Zeit: streng UTC, ISO-8601 mit Millisekunden.

Währungen: ISO-4217 + Genauigkeit (minor units). FX - auf der Seite des Operators/Aggregators.

3) Authentifizierung und Autorisierung

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

Spieler-Session: short-lived JWT (signiert Plattform) c 'sub', 'geo', 'rg _ flags', 'exp', 'aud = studio'.

Zugriffslisten: IP allowlist + mTLS für Prod-Loops.

4) Wallet-Modelle: debit/credit vs transfer

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

1. Die Plattform ruft RGS auf: 'SpinRequest (stake)' → RGS berechnet das Ergebnis → gibt 'win' zurück.

2. Parallel dazu macht die Plattform 'debit (stake)' und 'credit (win)' am eigenen/am Betreiber.

Vorteile: einfache Buchhaltung. Nachteile: mehr Netzwerkanrufe, strenge Anforderungen an die Idempotenz.

B) Transfer (session balance):

1. Zu Beginn der Session macht die Plattform 'transferIn (amount)' auf dem RGS.

2. Während der Spins RGS selbst hält das Gleichgewicht der Sitzung; wenn abgeschlossen - „transferOut (remaining)“.

Vorteile: weniger Wallet-Chats. Nachteile: Bilanzierung von „Geld auf der RGS-Seite“, zusätzliche Risiken und Reconciliations.

Empfehlungen:

Debit/Credit mit idempotenten Schlüsseln werden häufiger für Slots verwendet.

Bei Freispielen und Turnieren ist es praktisch, separate Wettarten zu haben 'spin _ type = free	promo`.

5) Idempotenz und Konsistenz

Jeder Geldschritt muss einen eindeutigen 'idempotency _ key' haben (z.B. 'round _ id' oder 'spin _ id').

Wiederholungen („HTTP 409/425“) geben das gleiche Ergebnis zurück, nicht „Fehler bereits gemacht“.

Exactly-once ist schwer zu erreichen, also bauen wir at-least-once + idempotence.

Wir erweitern die Idempotenz auf: 'debit', 'credit', 'jackpot _ contribution', 'bonus _ award'.

6) Muster der Schlüsselabfragen (verkürzt)

6. 1. Beginn der Sitzung

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

Die Antwort lautet:

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. Event-Log (Event-Bus, Battle-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) Versionierung von Builds und Market Builds

„build _ hash“ (SHA-256) ist bei jedem Event ein Muss.

Global vs Market build: Sprache, Warnungen, Gebotsbeschränkungen, RTP-Profil.

Die Plattform validiert: „Wird jetzt eine dem Zertifikat eines bestimmten Landes entsprechende Karte gespielt“.

Die Matrix: ' game_id × country × rtp_profile × build_hash '.

8) RNG, Mathematik und Replik

RNG lebt von RGS; Geschäftslogik ändert nichts an den Chancen „on the fly“.

Für Forensics: 'seed/nonce' pro Runde/Spin + Mechanik-Version.

Replays: durch 'spin _ id '/' seed' reproduziert RGS das Ergebnis und gibt den Audit-Trail ab.

9) Responsible Gaming (RG) und Compliance Hooks

Hooks der Zeit/Limits: 'session _ time _ ms', 'reminders', timeouts; 'rg _ event' im Event Bus.

Selbstausschluss/Block: mit der Flagge - sofort '403 RG_BLOCKED'.

UI-Invarianten: Die Plattform überprüft, ob der Client Warnungen/Altersbezeichnungen aus dem Market Build anzeigt.

10) Fehler, Retrays und SLAs

Codes: „400“ (Validierung), „401/403“ (Authentifizierung/RG), „409“ (Idempotenzkonflikt), „422“ (Geschäftsfehler), „429“ (Preislimit), „5xx“ (temporär).

Retrayrichtlinie: exponentiell, mit idempotentem Schlüssel und Deduplizierung am Empfänger.

SLA: API-Verfügbarkeit ≥99. 9%, p95 Latenz für 'spin' ≤200 -300ms (regional), Event Bus - near-real-time <60s.

11) Beobachtbarkeit und Auditierung

Protokolle: Unbeschnittene Serverprotokolle mit der Korrelation 'trace _ id'.

Metriken: p95/p99 Latenz, Fehlerrate nach Methoden, RTP/Bonusfrequenzabweichungen, Anteil „eligible spins“.

Alerts: durch SLA, durch mathematische Anomalien, durch die Zunahme von Wallet-Fehlern.

Audit: WORM-Speicher für Wett-/Ergebnisereignisse; Export auf Anfrage.

12) Sicherheit

mTLS + TLS 1. 2 +, HSTS, strenge CORS auf Kundenloader.

Kei-Rotation, kurze TTL-Token, JTI/Nonce-Prüfungen.

Anti-Tamper für den Kunden: Asset-Signaturen, Integritätsprüfung, Schutz vor Debaggern.

Geheimnisse - nur im Secret Manager; kein „Schlüssel im Spiel“.

13) Testumgebungen und Zertifizierung

Sandbox: fiktive Geldbörsen, deterministisch durch RNG (fixed seed), Auto-Flop RG-Szenarien.

Staging: Eine Kopie der Prod Infra ohne echtes Geld.

Paket für Labore: GDD/Mathematik, RNG-Dossier, Log-Diagramme, repeatable Build und Hashes.

14) Promo und Jackpots in der API

Free Spins: Übertragung des Pakets: 'grant _ free _ spins (count, bet_size, rtp_profile?)'; Ereignisse werden in RGS ausgegeben und protokolliert.

Turniere: Attribut 'spin _ type = turnier' + einzelne Aggregate im Event Bus.

Jackpots: 'jackpot _ contribution' und 'jackpot _ win' als separate Transaktionen; Konsistenz durch Idempotenz und „signierte“ Ereignisse.

15) Berichterstattung und Abrechnung

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

Per-Spin/Turnover-Fee: Konto mit „eligible _ spins“ oder „Σ stake × rate“.

Rev-share: von 'NetWin' nach dem „Wasserfall“ der Retention; vierteljährliches True-Up für FX/Exceptions.

16) Typische Sequenzen (Wortdiagramme)

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 und Kompatibilität

Contract-first: OpenAPI/Protobuf ist eine einzige Quelle für Schemata.

SemVer: Fügen Sie nur Felder hinzu; Löschen/Ändern - in/v2.

Feature Flags: Aktivierung von Optionen (Bonus Buy/Ante) - nur über zertifizierte Profile.

Deprecation: announce → grace period → Abschaltung in inaktiven Regionen.

18) Checklisten

Studio → Plattform

OpenAPI/gRPC-Specs und Beispielpayloads.
Idempotenz' spin/debit/credit/jackpot'.
'build _ hash' und die Registry der Market Builds.
RNG-Replikate und Audit-Log.
RG-Haken und Fehler '403 RG_BLOCKED'.
Sandbox mit Fix-Seed, Test-Wallet und Auto-Scenarios.

Plattform → Studio

JWT-Signatur mit kurzer TTL, allowlist IP, mTLS.
Validator von Market Builds und Zertifikaten.
Event Bus und Dashboards (latency/error/RTP drift).
Quoten und Rate-Limits mit ehrlichem Feedback „429-Retry-After“.
SLA/Vorfälle/Kommunikationskanäle 24 × 7.

19) 30-60-90 Startplan

0-30 Tage

Vereinbaren Sie API-Verträge und Ereignismuster, wählen Sie ein Wallet-Modell.

Heben Sie die Sandbox an: fixed-seed RNG, Testgeldbörse, Autotests der Idempotenz.

Das Register 'build _ hash' und die primäre Matrix der Market Builds.

31-60 Tage

Integration von Wallet und Spins; Event Bus und Dashboards aktivieren.

Belastungstests (p95/p99), Retrays/Idempotenz, Chaosnetzwerkszenarien.

Compliance: RG-Hooks, Locals, Age-Labels; Paket zum Labor.

61-90 Tage

Pilot bei 1-2 Operatoren, A/B auf Promo (Freispiele/Turniere).

Eingabe von True-Up/Reporting, RTP-Drift/Bonus-Freq-Alerts.

Vorbereitung v2 Verbesserungen: Batch-Events, gRPC für Wallet, Geo-Routing.

20) Kurze FAQ

Wo wird die RTP/Version geprüft? Auf der Plattform: „build _ hash“ ↔ Zertifikat ↔ Land.

Kann ich RTP dynamisch ändern? Nein. Nur vorab zertifizierte Profile und nur durch Marktaufbau umschalten.

Wie löst man „double debit“? Idempotenter Schlüssel + Speicherung des Transaktionsstatus; wiederholen - Gibt das Ergebnis zurück.

Brauche ich gRPC? Nützlich für Brieftasche/Veranstaltungen mit hohen Volumina; REST bleibt für Metadaten/Admins.

Stabile Integration sind Verträge + Idempotenz + Beobachtbarkeit. Transparente Ereignismuster, Bild-/Marktkontrollen, RG-Hooks und Versionsdisziplin eliminieren 90% der Risiken zu Beginn. Dann - Automatisierung von Promo und Reporting, starre SLA und sorgfältige API-Entwicklung ohne „brechende“ Änderungen.