Როგორ დავუკავშირდეთ პროვაიდერებს API- ს საშუალებით: Handshake, სერტიფიკაცია, sandbox

სტატიის სრული ტექსტი

💡 18+. მასალა არის საინჟინრო და გამოყენებითი, არა თამაშის მოწოდება. „პროვაიდერი“ გვესმის RGS/ცოცხალი სტუდია/ჯეკპოტი/სერვისი; „პლატფორმის“ ქვეშ - PAM/საფულე/სალარო/პრემია/RG.

1) ინტეგრაციის რუკა: განაცხადიდან წარმოებამდე

ეტაპები:

1. პრესალი და Due Diligence: იურიდიული პირები, გეო/ლიცენზია, შინაარსის თავსებადობა და RG პოლიტიკოსი.

2. Handshake და უსაფრთხოება: sandbox წვდომის გაცემა, კლავიშების გაცვლა (mTLS/HMAC), რეგისტრაცია Schema Registry- ში.

3. Techdisaine: ჩვენ ვადასტურებთ დომენის მოდელს (sessions/bets/settlements/events), idempotenty, შეცდომების კოდი.

4. Sandbox ინტეგრაცია: საფულის ემულატორები/PSP/RG, ტესტის მოთამაშეები, წვიმის სცენარები და დუბლები.

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

6. Staging/UAT: საბრძოლო კონფიგურაცია რეალური ფულის გარეშე, კანარის ტრაფიკი.

7. Go-Live: კლავიშების კომპანია, წინა დროშების ჩართვა, SLO- ს მონიტორინგი, პოსტ - ინციდენტის მზადყოფნა.

2) Handschake: ავთენტურობა, საავტორო უფლებები, კვალი

2. 1 საიდუმლოების გაცვლა

mTLS (სერთიფიკატები per brand/region) და/ან OAuth2 Client Credentials.

HMAC/EdDSA მოთხოვნის სხეულის ხელმოწერა (დასძენს non-repudiation).

Скоупы: `sessions:write`, `bets:write`, `settlements:write`, `events:publish`.

2. 2 სავალდებულო სათაურები

'X-Trace-Id' - კვალი.

`X-Brand-Id`, `X-Region`, `X-Provider-Id`.

'X-Idempotency-Key' - ყველა write ოპერაციისთვის.

2. 3 ჯანმრთელობის შემოწმება (კოდამდე)


GET /health
→ 200 {"status":"ok","version":"1. 7. 2","time":"2025-10-23T10:00:00Z"}

3) Sandbox: რა არის იქ და როგორ გამოიყენოთ იგი

გარემოს შემადგენლობა:

საფულის ემულატორი ('/wallet/debit	credit	rollback ') იდემპოტენტურობით და შეფერხებებით.
RG huks ('/rg/check ',' rg. limit. hit ') და ტესტის პროფილები (თვითშეფასება/ლიმიტები).
ყალბი აგრეგატორი/ჯეკპოტი შენატანებისთვის/გამომწვევებისთვის.
ყალბი KYC/AML პასუხები (allow/deny/pending).
მოვლენების ავტობუსი (Kafka/Pulsar) ტესტის ტოპებით და Schema Registry.

ჰარმონია რეალობასთან:

სქემების და ქონების ლიმიტების მსგავსი ვერსიები, როგორც გაყიდვაში.
დროა, მიწოდების დუბლები, out-of-order - ჩაშენებული ემულაციის ღილაკებით.

ტესტის მოთამაშეთა/ვალუტების ნაკრები:


p_demo_1 (EUR), p_demo_2 (USD), p_blocked_rg (denied), p_low_balance

4) რესურსების მოდელი და მინიმალური კონტრაქტი

4. 1 სესიის შექმნა


POST /v1/sessions
{
"player_id":"p_demo_1",  "game_id":"studio:slot_forge_02",  "currency":"EUR",  "locale":"de-DE"
}
→ 201 {"session_id":"s_456","expires_at":"2025-10-23T19:10:00Z"}

4. 2 განაკვეთის დამტკიცება


POST /v1/bets/authorize
Headers: X-Idempotency-Key: bet_r_8c12_1
{
"session_id":"s_456",  "bet_id":"b_001",  "round_id":"r_8c12",  "amount":{"amount":2. 00,"currency":"EUR"}
}
→ 200 {"status":"authorized","hold_id":"h_zz1"}

4. 3 Settlent (რაუნდის შედეგი)


POST /v1/bets/settle
Headers: X-Idempotency-Key: settle_r_8c12_1
{
"bet_id":"b_001",  "round_id":"r_8c12",  "win":{"amount":14. 60,"currency":"EUR"},  "bonus_state":{"in_bonus":true,"freespins_left":7}
}
→ 200 {"status":"credited","settlement_id":"st_77"}

4. 4 შეცდომები (ერთი სქემა)


409
{"code":"DUPLICATE","message":"Bet already authorized","retryable":false,"trace_id":"tr_a1b2"}

5) მოვლენები და სქემები: ამის გარეშე, თქვენ არ გაივლით სერტიფიკაციას

საბაზო ტოპიკები:

`session. started	ended`, `bet. authorized	settled	rolled_back`, `bonus. issued	consumed`, `wager. progress. updated`, `wallet. debit.`, `wallet. credit.`, `rg. limit. hit`, `rg. reality_check`.

მაგალითი Avro/JSON Schema (ფრაგმენტი 'bet. settled`):

json
{
"event_type":"bet. settled",  "schema_version":"1. 2. 0",  "event_id":"uuid",  "occurred_at":"2025-10-23T16:21:05Z",  "tenant_id":"brand-7",  "region":"EU",  "player_id":"p_demo_1",  "trace_id":"tr_a1b2",  "payload":{
"round_id":"r_8c12",   "bet":{"amount":1. 00,"currency":"EUR"},   "win":{"amount":14. 60,"currency":"EUR"},   "in_bonus":true
},  "idempotency_key":"bet_r_8c12_1"
}

წესები: backward-compatible ევოლუცია, ტესტი „დუბლიკატები და გვიანდელი მოვლენები“, „tenant _ id/player _ id“.

6) ინტეგრაციის სერტიფიკაცია: რას ამოწმებენ

6. 1 ფუნქციური სკრიპტები (მინიმალური)

Authorize/settle მოთხოვნის განმეორება იგივე 'X-Idempotency-Key' იგივე პასუხია.

Out-of-order: მოვიდა 'settle' '' authorize '- ის გარეშე, სწორი უარი.

Rollback ჯაჭვები საფულე/ქსელის დაცემის დროს.

RG გაჩერებები: თვითგამორკვევა/ზარალის/დროის ლიმიტი, განაკვეთის აკრძალვა.

ბონუს/ვეგერი: წვლილი თამაშის ტიპში, მაქს ბეტში, ვადებში.

6. 2 დატვირთვა

ბიუჯეტებში p95 'bet/settle' (მაგ. '<200-300 ms'), „ქარიშხლების“ არარსებობა.

მოვლენების ნაკადები აღწევს BI-5 წუთს.

6. 3 ქაოსის შემთხვევები

მიწოდების დუბლები, გარე/CDC შეფერხებები, რეგიონის „განადგურება“, ნაწილობრივი დარტყმა.

6. 4 დოკუმენტები

ტესტის ოქმი დროის კოდებით/trace-id.

ანგარიში SLO (latency/error/lag).

უსაფრთხოების შეჯამება (გასაღებები, როტაცია, წვდომა, Vault/HSM).

7) ვერსია და მიგრაცია

HTTP: '/v1/... 'გზაზე, მოვლენები:' schema _ version 'სხეულში.

SemVer: minor - სურვილისამებრ ველების დამატება; მაიორი - მხოლოდ ახალი პრეფიქსი '/v2/' მეშვეობით.

Deprecation headers: 'Deprecation', 'Sunset', dushboard- ში გამოყენების სარკე.

Fich დროშები: გარდამავალ პერიოდში მოვლენების „ორმაგი წერა“ ('v1' და 'v2').

8) უსაფრთხოება და შესაბამისობა

mTLS + S2S ხელმოწერები, მოკლემეტრაჟიანი ნიშნები, შეზღუდული ნაკრები.

Zero-trust: ქსელის პოლიტიკა, per-brand/გასაღებები.

მონაცემთა რეგულირება და PII: შენახვა და ლოგოები რეგიონში; RLS/ნიღაბი.

WORM აუდიტი: ლიმიტის ცვლილებები, RTP პროფილები, ჯეკპოტის კონფიგურაცია.

RG/AML: სინქრონული გაჩერების სიგნალები/გადახდის განაკვეთზე; SAR/STR მოხსენება.

9) გამოსავალი პროდუქტში: გაშვების საკონტროლო სია

ტრაფიკის ჩართვამდე

Sandbox საიდუმლოებების როტაცია.

Dashbords p95/p99, error-rate, queue-lag, settle-lag შედის.

Alerty SLO: breach latency/error/lag, black 'DUPLICATE/IDEMPOTENCY _ MISMATCH'.

DR გეგმა: RPO - 5 წთ, RTO - 30 წთ; „წითელი ღილაკი“ - ახალი სესიების გაჩერება.

კანარეიკა

აუდიტორიის/თამაშების/გეოს 1-5%; ავტომატური rollback SLO დარღვევის შემთხვევაში.

პოსტ-მონიტორინგი 24-72 საათის განმავლობაში, მენეჯერის/მოხსენებების შერიგება.

10) ანტი-ნიმუშები (წითელი დროშები)

მოვლენების გამოქვეყნება outbox/CDC გვერდის ავლით.

write ოპერაციებზე „X-Idempotency-Key“ არარსებობა.

ბალანსების/settlement- ის ხელით რედაქტირება მონაცემთა ბაზაში.

რამდენიმე ბრენდის/რეგიონის საერთო გასაღებები.

BI და მარეგულირებელი მოხსენებები OLTP საბრძოლო DD- ზე.

ნულოვანი დეგრადაცია: პროვაიდერის დაცემამ საფულე/პლატფორმა დააგდო.

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

პროვაიდერისთვის

ყოველთვის გამოგიგზავნით 'X-Trace-Id' და 'X-Idempotency-Key'.
მხარს ვუჭერ იგივე გასაღების გამეორებას გვერდითი მოვლენების გარეშე.
აუდიტორიის მოვლენები რეგისტრის სქემების მიხედვით; schema _ version '.
განხორციელდა backoff- ის რეტრაები და დედუპლიკაცია.
RG ფეხები და ბონუსის შეზღუდვები დაფიქსირებულია რეალურ დროში.
წვდომა და საიდუმლოებები - per brand/region, როტაცია.

პლატფორმისთვის

Outbox/CDC ყველა ფულადი გზით; კვალი დასრულდება.
SLO დაშბორდები: p95/99, error-rate, queue-lag, settle-lag.
დეპრესია/Sunset პროცესი, ორმაგი წერა მიგრაციის მოვლენებზე.
DR/xaoc სწავლებები, ინციდენტის მენეჯმენტი და პოსტმორტემი.
დეგრადაციის რეჟიმები: 'no new sessions', პრომო/ჯეკპოტის გათიშვა.

12) „მინიმალური“ ინტეგრაციის პლეიბუკის მაგალითი (TL; DR)

1. ხელი მოაწერეთ NDA/ხელშეკრულებას, რომ გაიცეს sandbox წვდომა და სქემები.

2. MTLS/HMAC სერთიფიკატების გაცვლა; დაიწყეთ 'provider _ id'.

3. კოორდინირებული მინიმალური ენდოინტები: 'sessions', 'bets/authorize', 'bets/settle', 'rollback'.

4. დაუკავშირდით Sandbox ავტობუსს და Registry- ს; გადაიტანეთ ფუნქციური/ქაოსის შემთხვევები.

5. გადასცეს სასერთიფიკატო პროტოკოლი: logs, trace-id, SLO ანგარიში.

6. გადართეთ პროდუქტების გასაღებები, ჩართეთ კანარი, დააკვირდით SLO- ს.

7. ჩაწერეთ პოსტ-გამოშვებული მეტრიკა და „გაკვეთილები“ ჩანგელოგში.

პროვაიდერის წარმატებული კავშირი არა მხოლოდ API, არამედ კონტროლირებადი პროცესია: უსაფრთხო handshake, რეალისტური sandbox, მკაცრი სერტიფიკაცია, დაკვირვება და თავსებადობის მკაფიო წესები. აღწერილი ინვარიანტების შემდეგ (idempotention, outbox/CDC, RG/AML გაჩერებები, SLO და DR), თქვენ აჩქარებთ ინტეგრაციას, თავიდან აიცილებთ ფულადი ინციდენტები და იღებთ პროგნოზირებულ გამოშვებებს - მოთამაშეების, რეგულატორებისა და ბიზნესისთვის სიურპრიზების გარეშე.