Როგორ მუშაობს API ინტეგრაცია სტუდიებსა და პლატფორმებს შორის

სტუდიის ინტეგრაცია (თამაშების პროვაიდერი) პლატფორმასთან/აგრეგატორთან არის სესიის გარშემო სინქრონული და ასინქრონული გამოწვევების ჯაჭვი, საფულე, უკანა და ღონისძიების ტელემეტრიის შედეგი. ქვემოთ მოცემულია მოკლე, მაგრამ პრაქტიკული რუკა, თუ როგორ უკავშირდება ყველაფერი ტკივილის გარეშე დეველოპერებისა და კომპლენსისთვის.

1) პალმის არქიტექტურა

აქტორები:

სტუდია RGS (Remote Game Server) - თამაშის ლოგიკა, RNG, პრემია, ჯეკპოტები.
პლატფორმა/აგრეგატორი - მარშრუტიზაცია, ბილინგი, პრომო, შესაბამისობა.
ოპერატორი - მოთამაშის საფულე, KYC/RG, ვიტრინა.
კლიენტი არის თამაშის ვებ/მობილური კონტეინერი (iframe/webview/native).

ძირითადი საბურავები:

Sync API: სესიები, საფულე, გარე.
Async/Event Bus: სპინების, პრემიების, ჯეკპოტის, RG- ის მოვლენები, ტექნიკური შეცდომები.
მეტამონაცემები/კატალოგი: თამაშები, ბაზარი მაღაზიები, RTP პროფილები, იდაყვის.

2) ოქმები და ძირითადი გადაწყვეტილებები

ტრანსპორტი: HTTPS/JSON (ზოგჯერ GRPC Event Bus/საფულისთვის).

ვერსია: 'Accept: განაცხადი/vnd. rgs. v1 + json 'ან '/v1/...'; თავსებადობის დეგრადაცია - მხოლოდ ახალი ვერსიების საშუალებით.

იდენტიფიკაცია: 'game _ id', 'build _ hash', 'operator _ id', 'session _ id', 'round _ id', 'spin _ id'.

დრო: მკაცრად UTC, ISO-8601 მილიწამებით.

ვალუტები: ISO-4217 + სიზუსტე (მცირე ერთეულები). FX - ოპერატორის/აგრეგატორის მხარეს.

3) ავთენტიფიკაცია და ავტორიზაცია

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

მოთამაშის სესია: მოკლე lived JWT (ხელს აწერს პლატფორმას) c 'sub', 'geo', 'rg _ flags', 'exp', 'aud = studio'.

წვდომის სიები: IP allowlist + mTLS პროტოკოლებისთვის.

4) საფულის მოდელები: debit/credit vs transfer

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

1. პლატფორმა იწვევს RGS: 'SpinRequest (SpinRequest)' - RGS ელოდება შედეგს და უბრუნებს 'win' - ს.

2. პარალელურად, პლატფორმა აკეთებს 'debit (stake)' და 'credit (win)' ოპერატორთან.

დადებითი: მარტივი ბუღალტრული აღრიცხვა. უარყოფითი მხარეები: მეტი ქსელის გამოწვევა, იდემპოტენტურობის მკაცრი მოთხოვნები.

B) Transfer (session balance):

1. სესიის დასაწყისში პლატფორმა აკეთებს 'transferIn (amount)' RGS- ზე.

2. ზურგჩანთების დროს, RGS თავად აწარმოებს სხდომის ბალანსს; დასასრულს - 'transferOut'.

დადებითი: ნაკლები ჩატი საფულე. უარყოფითი მხარეები: აღრიცხავს „ფულს RGS- ის მხარეზე“, დამატებით რისკებს და ჩანაწერებს.

რეკომენდაციები:

Slots- ისთვის ხშირად გამოიყენება idempotent კლავიშების debit/credit.

უფასო სპინებზე და ტურნირებზე მოსახერხებელია ცალკეული ტიპის განაკვეთები "spin _ type = free	promo`.

5) Idempotence და კოორდინაცია

თითოეულ ფულადი ნაბიჯით უნდა ჰქონდეს უნიკალური idempotence _ key (მაგალითად, 'round _ id' ან 'spin _ id').

გამეორებები ('HTTP 409/425') იგივე შედეგს უბრუნებს და არა „შეცდომა უკვე დასრულებულია“.

Exactly once- ის მიღწევა რთულია, ამიტომ ჩვენ ვაშენებთ idempotence at-least-once +.

Idempotention ვრცელდება: 'debit', 'credit', 'jackpot _ contribution', 'bonus _ award'.

6) ძირითადი მოთხოვნების სქემები (შემცირებული)

6. 1. სესიის დაწყება

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. სპინი (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-…"
}

პასუხი:

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 Bus, ბრძოლის ფორმატი)

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) ბილეთების და ბაზრის ვერსიები

'build _ hash' (SHA-256) სავალდებულოა თითოეულ ღონისძიებაზე.

Global vs Market build: ენა, გაფრთხილებები, განაკვეთების შეზღუდვები, RTP პროფილი.

პლატფორმა ლიდერობს: „თამაშობს თუ არა ბილეთი, რომელიც შეესაბამება ამ ქვეყნის სერთიფიკატს“.

მატრიცა: 'game _ id × country × rtp _ profile × build _ hash'.

8) RNG, მათემატიკა და რეპლიკები

RNG ცხოვრობს RGS- ში; ბიზნეს ლოგიკა არ ცვლის ფრენის შანსებს.

წინსვლისთვის: 'seed/nonce' რაუნდი/spin + მექანიკის ვერსია.

რეპლიკა: 'spin _ id '/' seed' RGS ასახავს შედეგს და აძლევს აუდიტს.

9) Responsible Gaming (RG) და შესაბამისობის ჰუკი

დროის/ლიმიტის ხოჭოები: 'session _ time _ ms', „შეხსენებები“, timeouts; 'rg _ event' Event Bus- ში.

თვითგამორკვევა/ბლოკი: დროშის დროს - დაუყოვნებლივი „403 RG _ BLOCKED“.

UI ინვარიანტები: პლატფორმა ამოწმებს კლიენტს, რომ აჩვენოს გაფრთხილებები/ასაკობრივი ეტიკეტები ბაზარზე.

10) შეცდომები, რეტრაები და SLA

კოდები: '400' (შესაბამისობა), '401/403' (ავთენტიფიკაცია/RG), '409' (იდეოლოგიური კონფლიქტი), '422' (ბიზნეს შეცდომა), '429' (საბაზო ლიმიტი), '5xx' (დროებითი).

Retray- ის პოლიტიკა: ექსპონენციალური, იდემპოტენტური კლავიშით და მიმღები.

SLA: API წვდომა 99. 9%, p95 latence 'spin' 200-300 ms (რეგიონალური), Event Bus - ნამდვილი დრო <60.

11) დაკვირვება და აუდიტი

ლოგოები: მოჩუქურთმებული სერვერის ლოგოები „trace _ id“ კორელაციით.

მეტრიკა: p95/p99 ლატენცია, error rate მეთოდების მიხედვით, RTP/ბონუსის სიხშირის გადახრები, „ელიგიური სპინების“ წილი.

ალერტები: SLA- ში, მათემატიკის ანომალიებში, საფულეზე უარის თქმის ზრდაზე.

აუდიტი: WORM საცავი განაკვეთების/შედეგების მოვლენებისთვის; ექსპორტი მოთხოვნით.

12) უსაფრთხოება

mTLS + TLS 1. 2 +, HSTS, მკაცრი CORS კლიენტის ლოადერზე.

კეი როტაცია, მოკლე TTL tokens, JTI/nonce ტესტები.

კლიენტისთვის Anti-tamper: ასეტების ხელმოწერები, მთლიანობის შემოწმება, თავდაცვა მორბენალებისგან.

საიდუმლოებები - მხოლოდ საიდუმლო მენეჯერში; თამაშის კონფისკაციის გასაღები არ არის.

13) ტესტის გარემო და სერტიფიკაცია

Sandbox: ფიქტიური საფულეები, დეტერმინირებული RNG (fixed seed), RG სცენარების ავტომატური წარუმატებლობა.

Staging: prod ინფოს ასლი რეალური ფულის გარეშე.

ლაბორატორიების პაკეტი: GDD/მათემატიკა, RNG დოსიე, ლოგოს სქემები, რეპეტიციების შესყიდვა და ჰეშები.

14) პრომო და ჯეკპოტები API- ში

უფასო სპინსი: პაკეტის გადაცემა: 'გრანტი _ უფასო _ სპინსი (count, bet _ size, rtp _ profile?) "; მოვლენები იხარჯება RGS- ში და არის ლოგიკური.

ტურნირები: ატრიბუტი 'spin _ type = tournament' + ცალკეული ერთეულები Event Bus- ში.

ჯეკპოტები: „jackpot _ contribution“ და „jackpot _ win“, როგორც ცალკეული გარიგებები; თანმიმდევრულობა იდემპოტენტურობისა და „ხელმოწერილი“ მოვლენების საშუალებით.

15) მოხსენება და ბილინგი

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

Per-spin/turnover-fee: ანგარიში 'eligible _ spins' ან „stake × rate“.

Rev-share: 'NetWin' - დან ჩამორჩენის „ჩანჩქერის“ შემდეგ; კვარტალური ნამდვილი გამონაკლისი FX/გამონაკლისი.

16) ტიპიური თანმიმდევრობა (სიტყვიერი დიაგრამები)

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) ჩანაცვლება მენეჯმენტი და თავსებადობა

კონტრაქტი პირველი: OpenAPI/Protobuf არის სქემების ერთი წყარო.

SemVer: უბრალოდ დაამატეთ ველები; მოცილება/ცვლილება - iv/v2.

Feature flags: პარამეტრების ჩართვა (Bonus Buy/Ante) - მხოლოდ სერთიფიცირებული პროფილების საშუალებით.

დეპრესია: announce - grace period გამორთვა არააქტიურ რეგიონებში.

18) ჩეკის ფურცლები

სტუდია - პლატფორმა

OpenAPI/gRPC სპეკები და სავარაუდო payloads.
Idempotence 'spin/debit/credit/jackpot'.
'build _ hash' და ბაზრის შესყიდვების რეესტრი.
RNG მიმღები და აუდიტის ჟურნალი.
RG ჰუკები და შეცდომები „403 RG _ BLOCKED“.
Sandbox ერთად ფიქსირებული თესლი, საცდელი საფულე და ავტომობილების შემოწმება.

პლატფორმა - სტუდია

JWT ხელმოწერა მოკლე TTL, allowlist IP, mTLS.
ბაზრის ბარათებისა და სერთიფიკატების შემსრულებელი.
Event Bus და dushbords (latency/error/RTP drift).
კვოტები და საბაზო ლიმიტები გულწრფელი გამოხმაურებით „429-Retry-After“.
SLA/ინციდენტები/საკომუნიკაციო არხები 24 × 7.

19) 30-60-90 გაშვების გეგმა

0-30 დღე

შეთანხმდნენ API კონტრაქტებზე და მოვლენების სქემებზე, შეარჩიეთ საფულე მოდელი.

ამაღლება sandbox: fixed-seed RNG, ტესტის საფულე, idempotenty ავტოტრანსპორტი.

რეესტრი „build _ hash“ და პირველადი ბაზრის მაღაზიების მატრიცა.

31-60 დღე

საფულისა და ზურგების ინტეგრაცია; ჩართეთ Event Bus და დაშბორდები.

დატვირთვის ტესტები (p95/p99), retrai/idempotence, ქსელის ქაოსი სცენარები.

შესაბამისობა: RG hukes, იდაყვის, age-labels; ჩანთა ლაბორატორიაში.

61-90 დღე

მფრინავს აქვს 1-2 ოპერატორი, A/B პრომო (უფასო სპინები/ტურნირები).

ნამდვილი up/ანგარიშების შეყვანა, RTP დრიფტის ალერტები/bonus-freq.

V2 გაუმჯობესების მომზადება: საბრძოლო მოვლენები, gRPC საფულისთვის, geo-routing.

20) მოკლე FAQ

სად არის შემოწმებული RTP/ვერსია? პლატფორმაზე: „build _ hash“ - სერთიფიკატი ქვეყნის წინაშე.

შესაძლებელია RTP- ის დინამიურად შეცვლა? არა. მხოლოდ წინასწარ დამოწმებული პროფილები და მხოლოდ ბაზრის გადართვა.

როგორ გადავწყვიტოთ „ორმაგი debit“? Idempotent გასაღები + გარიგების სტატუსის შენახვა; გამეორება - ბრუნდება შედეგი.

გჭირდებათ GRPC? სასარგებლოა საფულე/ტირაჟი მაღალი მოცულობით; REST რჩება მეტამონაცემებისთვის/ჯოჯოხეთისთვის.

სტაბილური ინტეგრაცია არის კონტრაქტები + იდემპოტენტურობა + დაკვირვება. გამჭვირვალე მოვლენების სქემები, ბილეთების/ბაზრების კონტროლი, RG ჰუკები და ვერსიების დისციპლინა თავიდანვე ამოიღებს რისკების 90% -ს. შემდეგი - პრომო და ანგარიშგების ავტომატიზაცია, მკაცრი SLA და API- ს ფრთხილად განვითარება „გატეხილი“ ცვლილებების გარეშე.