Comment fonctionne l'API d'intégration entre les studios et les plates-formes

L'intégration du studio (fournisseur de jeux) avec la plate-forme/agrégateur est une chaîne d'appels synchrones et asynchrones autour de la session, du portefeuille, du résultat du dos et de la télémétrie de l'événement. Ci-dessous, une carte brève, mais pratique, comment les choses se connectent sans douleur pour les développeurs et la complication.

1) Architecture dans la paume de votre main

Acteurs :

Studio RGS (Remote Game Server) - logique du jeu, RNG, bonus, jackpots.
Plate-forme/Agrégateur - routage, facturation, promo, conformité.
L'opérateur est le portefeuille du joueur, KYC/RG, la vitrine.
Le client est le conteneur web/mobile du jeu (iframe/webview/native).

Pneumatiques de base :

API Sync : sessions, portefeuille, outcome.
Async/Event Bus : événements spin, bonus, jackpots, RG, erreurs techniques.
Métadonnées/annuaire : jeux, market builds, profils RTP, local.

2) Protocoles et solutions de base

Transport : HTTPS/JSON (parfois gRPC pour Event Bus/portefeuille).

Versioning : 'Accept : application/vnd. rgs. v1 + json 'ou '/v1/...' ; dégradation de l'interopérabilité - uniquement par le biais de nouvelles versions.

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

Temps : strictement UTC, ISO-8601 avec millisecondes.

Devises : ISO-4217 + précision (unités mineures). FX - côté opérateur/agrégateur.

3) Authentification et autorisation

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

Session du joueur : short-lived JWT (signe la plateforme) c 'sub', 'geo', 'rg _ flags', 'bou', 'aud = studio'.

Listes d'accès : IP allowlist + mTLS pour les tracés.

4) Modèles de portefeuille : debit/credit vs transfer

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

1. La plate-forme appelle RGS : 'SpinRequest (stake)' → RGS calcule le résultat → renvoie 'win'.

2. En parallèle, la plateforme fait 'debit (stake)' et 'credit (win)' chez elle/chez l'opérateur.

Avantages : comptabilité simple. Inconvénients : plus d'appels réseau, des exigences strictes d'idempotence.

B) Transfer (session balance):

1. Au début de la session, la plate-forme fait 'transferIn (amount)' sur RGS.

2. Pendant le dos, le RGS tient lui-même l'équilibre de la session ; lorsque vous avez terminé - 'transferOut (remaining)'.

Avantages : moins de chats portefeuille. Inconvénients : comptabilisation de « l'argent du côté de la RGS », risques supplémentaires et reconstitutions.

Recommandations :

Les slots utilisent plus souvent debit/credit avec des clés idempotentes.

Sur les free spins et les tournois, il est commode d'avoir des types de paris distincts 'spin _ type = free	promo`.

5) Idempotence et cohérence

Chaque pas d'argent doit avoir un 'idempotency _ key' unique (par exemple, 'round _ id' ou 'spin _ id').

Les répétitions ('HTTP 409/425') renvoient le même résultat, pas « erreur déjà faite ».

Exactly-once est difficile à réaliser, donc nous construisons at-least-once + idempotence.

L'idempotence est étendue à : 'debit', 'credit', 'jackpot _ contribution', 'bonus _ award'.

6) Schémas de demandes clés (abrégés)

6. 1. Début de la session

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

Réponse :

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. Journal d'événements (Event Bus, format de trampoline)

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) Versioning builds et market builds

'build _ hash' (SHA-256) est obligatoire à chaque événement.

Global vs Market build : langage, avertissements, limites de taux, profil RTP.

La plate-forme valide : « Est-ce que le projet de loi correspondant au certificat de ce pays est en cours de lecture ».

Matrice : 'game _ id × country × rtp_profile × build_hash'.

8) RNG, mathématiques et relais

RNG vit sur RGS ; la logique des affaires ne change pas les chances « à la volée ».

Pour forenser : 'seed/nonce' par tour/spin + version mécanique.

Replay : par 'spin _ id '/' seed', RGS reproduit le résultat et donne une piste d'audit.

9) Responsible Gaming (RG) et hooks de conformité

"session _ time _ ms'," rappels ", timeouts ;" rg _ event "dans Event Bus.

Auto-exclusion/bloc : avec le drapeau - immédiat '403 RG_BLOCKED'.

UI-invariants : la plate-forme vérifie que le client affiche des avertissements/étiquettes d'âge du marché build.

10) Erreurs, retraits et SLA

Codes : « 400 » (validation), « 401/403 » (authentification/RG), « 409 » (conflit d'idempotence), « 422 » (erreur professionnelle), « 429 » (rate limit), « 5xx » (temporaire).

Politique rétroactive : exponentielle, avec clé idempotente et déduplication sur le récepteur.

SLA : disponibilité de l'API ≥99. 9 %, p95 latency pour 'spin' ≤200 -300 ms (régional), Event Bus - near-real-time <60 s.

11) Observation et audit

Logs : Logs serveur non coupés avec la corulation 'trace _ id'.

Métriques : p95/p99 latency, taux d'erreur par méthode, écarts RTP/taux de bonus, part « éligible spins ».

Alert : Par SLA, par les anomalies des mathématiques, par l'augmentation des défauts de portefeuille.

Audit : Stockage WORM pour les événements de taux/résultats ; exportation sur demande.

12) Sécurité

mTLS + TLS 1. 2 +, HSTS, rigoureux CORS sur le loader client.

Kay-rotation, tokens TTL courts, contrôle JTI/nonce.

Anti-tamper pour le client : signatures d'assets, contrôle d'intégrité, protection contre les débaggers.

Secrets - seulement dans le gestionnaire secret ; pas de « clé dans le flig du jeu ».

13) Environnement d'essai et certification

Sandbox : portefeuille fictif déterminé par RNG (seed fixe), auto-échec des scénarios RG.

Staging : copie de prod infra sans argent réel.

Pack pour les laboratoires : GDD/maths, dossier RNG, logs, build repeatable et hash.

14) Promos et jackpots dans l'API

Free Spins : transmission du paquet : 'grant _ free _ spins (count, bet_size, rtp_profile?)' ; les événements sont dépensés dans RGS et logés.

Tournois : attribut 'spin _ type = tournament' + unités individuelles dans Event Bus.

Jackpot : 'jackpot _ contribution' et 'jackpot _ win' en tant que transactions distinctes ; consistance par idempotence et événements « signés ».

15) Comptabilité et facturation

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

Per-spin/turnover-fee : compte par 'eligible _ spins' ou 'Σ stake × rate'.

Rev-share : de 'NetWin'après la « cascade » des retenues ; true-up trimestriel pour FX/exceptions.

16) Séquences types (diagrammes verbaux)

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) Gestion du changement et interopérabilité

Contrat-first : OpenAPI/Protobuf est une source unique de schémas.

BouVer : n'ajoutez que des champs ; suppression/modification - dans/v2.

Feature flags : activez les options (Bonus Buy/Ante) uniquement via des profils certifiés.

Deprecation : announce → grace period → éteint dans les régions inactives.

18) Chèques-feuilles

Studio → Plateforme

Speakes OpenAPI/gRPC et payloades exemplaires.
Idempotentialité 'spin/debit/credit/jackpot'.
'build _ hash' et le registre market builds.
RNG-replay et audit-log.
RG-hooks et erreurs '403 RG_BLOCKED'.
Sandbox avec fix-seed, porte-monnaie de test et auto-devis.

Plate-forme → Studio

Signature JWT avec une courte TTL, allowlist IP, mTLS.
Validateur de market builds et certificats.
Event Bus et dashboards (latency/error/RTP drift).
Quotas et taux-limites avec une rétroaction honnête '429-Retry-After'.
SLA/incidents/canaux de communication 24 × 7.

19) Plan de lancement 30-60-90

0-30 jours

Négocier des contrats API et des schémas d'événements, choisir un modèle de portefeuille.

Soulevez la sandbox : RNG seed-seed, portefeuille de test, auto-tests d'idempotence.

Le registre 'build _ hash' et la matrice principale de market builds.

31-60 jours

Intégration du portefeuille et des spins ; activer Event Bus et dashboards.

Tests de charge (p95/p99), retrai/idempotence, scénarios de chaos du réseau.

Conformité : RG-hooks, locals, age-labels ; paquet au labo.

61-90 jours

Pilote avec 1-2 opérateurs, A/B par promo (spins gratuits/tournois).

Entrez true-up/reporting, alertes RTP-dérive/bonus-freq.

Préparation v2 améliorations : butch events, gRPC pour portefeuille, géo-routing.

20) FAQ courte

Où la version RTP/est-elle vérifiée ? Sur le platphome : 'build _ hash' ↔ le certificat ↔ le pays.

Puis-je changer le RTP dynamiquement ? Non. Seulement des profils pré-certifiés et seulement en changeant de market build.

Comment résoudre le « double débit » ? Clé idempotent + stockage de l'état de la transaction ; répétition - renvoie le résultat.

Ai-je besoin de gRPC ? Utile pour porte-monnaie/events à des volumes élevés ; REST reste pour les métadonnées/adminka.

L'intégration stable est un contrat + idempotence + observabilité. Les schémas d'événements transparents, le contrôle des bilds/marchés, les hooks RG et la discipline des versions éliminent 90 % des risques au départ. Ensuite, l'automatisation de la promo et de la comptabilité, le SLA dur et le développement prudent de l'API sans changements « cassants ».