GambleHub ინტეგრაციის სახელმძღვანელო

1) მიმოხილვა და ურთიერთქმედების მოდელი

• API პროვაიდერი: თქვენ ეძახით API GambleHub (საფულე, პრემია, მოხსენებები).
• ექსტერნალური მიმწოდებელი: ჩვენ ვურეკავთ თქვენს ვებჰუკებს/ენდოინტებს (ბალანსი, გარიგებები, KYC).

1. Edge/API (REST/gRPC, Webhooks)

2. მოვლენები (event bus: განაკვეთები/გადახდები/საფულე/CCC)

3. ანგარიშები (API + S3/SFTP ექსპორტი)

4. ოპერაციები (ინციდენტები, SLO, SLA სესხები)

2) გარემო, დომენები და IP

ხელშეკრულების SLA აღირიცხება ხელშეკრულებაში. IP განახლებები წინასწარ ქვეყნდება. ნება მომეცით Allowlist.

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

• OAuth2 Client Credentials: სერვერის სერვერი ('scope' -y: 'wallet: read', 'wallet: write', 'bet: write', 'read: read').
• JWT (issuer = GambleHub): RS256 ხელმოწერა, გასაღებები JWKS endpoint- ში.
• mTLS: ურთიერთგამომრიცხავი TLS ავთენტიფიკაცია (შესაბამისობის მოთხოვნით).

POST /oauth2/token grant_type=client_credentials&scope=wallet:write bet:write
→ { "access_token": "...", "token_type": "Bearer", "expires_in": 3600 }

სკოპები შემოწმებულია ყველა ზარზე. მაღალი რისკის ოპერაციებისთვის (გადახდები) გამოიყენება step-up: ცალკეული სკოპი და, სურვილისამებრ, IP/ASN სავალდებულო.

4) ვერსია და თავსებადობა

გზა: '/v1/... ', '/v2/... "(მთავარი ვერსია უკან არ არის შეუთავსებელი).
უმცირესობის და გაფართოების ცვლილებები - სქემის გაფართოების გზით (ახალი არჩევითი ველები).
დეპრესიები - შეტყობინებით 90 დღეში.
ვებჰუკები ვერსირებულია სათაურით 'X-GH-Event-Version: 1'.

5) ლიმიტები, კვოტები და იდემპოტენტობა

• `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.
• 429 ბრუნდება 'Retry-After- ით' (წამები).
• ყველა სახიფათო მეთოდს სჭირდება 'Idempotency-Key' (TTL 24-72 საათი). იდენტური მოთხოვნის გამეორება უბრუნებს წყაროს შედეგს (კონფლიქტის დროს '409 IDEMP _ REPLAY').

6) შეცდომის სტანდარტები

json
{
"type": "https://docs. gamblehub. io/errors/validation_failed",
"title": "Validation failed",
"status": 422,
"error_code": "VAL_001",
"trace_id": "a1b2c3...",
"retriable": false,
"errors": [{"field":"amount","code":"min","message":"Must be >= 1"}]
}

Retriable: 5xx/503/504/429 (с `Retry-After`). Non-retriable: 400/401/403/404/409/422/410/415/412.

7) მონაცემთა სქემები (ბირთვი)

7. 1 მოთამაშე

json
{
"player_id": "p_123",
"country": "CA",
"currency": "CAD",
"rg_flags": {"self_excluded": false, "limits": {"daily_loss": 100}},
"kyc_status": "verified    pending    failed"
}

7. 2 სესია

json
{
"session_id": "s_789",
"player_id": "p_123",
"started_at": "2025-11-03T17:55:00Z",
"ip": "203. 0. 113. 5",
"device": {"ua":"...", "os":"Android", "model":"..."}
}

7. 3 საფულე/გარიგებები

json
{
"txn_id": "t_001",
"player_id": "p_123",
"type": "deposit    withdrawal    bet    win    bonus    adjustment",
"amount": "12. 34",
"currency": "EUR",
"balance_after": "123. 45",
"metadata": {"provider":"psp_x","request_id":"r_456"}
}

7. 4 განაკვეთი/გადახდა

json
{
"bet_id": "b_456",
"player_id": "p_123",
"game_id": "g_777",
"stake": "1. 50",
"currency": "EUR",
"placed_at": "2025-11-03T17:58:10Z",
"round_id": "rnd_aa1",
"provider": "StudioX"
}

json
{
"settlement_id": "st_456",
"bet_id": "b_456",
"win_amount": "3. 75",
"settled_at": "2025-11-03T17:59:02Z",
"outcome": "win    lose    void"
}

7. 5 ბონუსი

json
{
"bonus_id": "bo_900",
"player_id": "p_123",
"type": "freespin    cash    wagered",
"state": "issued    active    expired    consumed",
"wagering": {"target": "100. 00","progress":"45. 20","currency":"EUR"}
}

8) REST API (OpenAPI ფრაგმენტები)

yaml paths:
/v1/wallet/balance/{player_id}:
get:
summary: Get wallet balance security: [{ oauth2: [wallet:read] }]
responses:
'200': { description: OK }
'401': { $ref: '#/components/responses/Problem' }
'404': { $ref: '#/components/responses/Problem' }

/v1/wallet/transactions:
post:
summary: Create wallet transaction security: [{ oauth2: [wallet:write] }]
parameters:
- name: Idempotency-Key in: header required: true schema: { type: string }
responses:
'201': { description: Created }
'409': { $ref: '#/components/responses/Problem' }
'422': { $ref: '#/components/responses/Problem' }

/v1/bets:
post:
summary: Register bet security: [{ oauth2: [bet:write] }]
responses:
'201': { description: Created }
'422': { $ref: '#/components/responses/Problem' }

9) ვებჰუკი (GambleHub- დან პარტნიორამდე)

• `X-GH-Event`: `player. created|session. started|bet. placed|bet. settled|wallet. changed|kyc. updated|rg. flagged`
• 'X-GH-Event-Id': უნიკალური UUID
• `X-GH-Signature`: `sha256=`
• 'X-GH-Retry': მცდელობა No
• `X-GH-Event-Version`: `1`

json
{
"event": "bet. settled",
"occurred_at": "2025-11-03T18:00:12Z",
"data": {
"settlement_id": "st_456",
"bet_id": "b_456",
"player_id": "p_123",
"win_amount": "3. 75",
"currency": "EUR",
"outcome": "win"
}
}

მასპინძელი მხარის პასუხი - მხოლოდ 2xx წარმატებულად ითვლება. წინააღმდეგ შემთხვევაში - retrais: ექსპონენციალური backoff (1s, 3s, 10s, 30s, 2m, 10m, 30 მ; მაქსიმუმ 24 საათი). დედაპლატაციისთვის გამოიყენეთ 'X-GH-Event-Id'.

text expected = base64(hmac_sha256(request_body, SHARED_SECRET))
header  = split(X-GH-Signature, '=')[1]
assert header == expected

10) ფულადი ნაკადის შეკვეთა (Wallet flow)

1. deposit (PSP → wallet. credit)

2. bet (hold/authorize или direct debit)

3. settlement (release hold; `win`/`lose`/`void`)

4. withdrawal (wallet. debit → PSP)

hold ბალანსები და მრავალ საფულე (რეალური/ბონუსი) მხარდაჭერილია.

11) ქვიშის ყუთი და ტესტის სცენარები

ტესტის მოთამაშეები: 'p _ sbx _', ვალუტა 'EUR' USD 'CAD'.
თამაშის პროვაიდერები ასახავენ: win/lose/void, ფასდაკლებით, შეფერხებებით.
KYC sandbox: პასუხები „პასპორტის შაბლონების მიხედვით“.
PSP sandbox: статусы `authorized|captured|declined|reversed`.

• განაკვეთი - გადახდა - ბალანსის შერწყმა
• დაბრუნება/void რაუნდი
• Idempotence ხელახალი კურსით
• Webhook Webhuk with rethers და შემდგომი deduplication
• 429 და სწორი 'Retry-After'
• 5xx ექსპონენტური backoff- ით კლიენტის მხარეს

12) შერიგება და მოხსენება

Reconciliation API

yaml
GET /v1/reports/reconciliation? from=...&to=...&scope=wallet    bets
→ CSV/JSON: { player_id, bet_id, stake, win, currency, balance_delta, provider }

ყოველდღიური ცნობები: ბრუნვა, GGR/NGP, პროვაიდერები, geo/ვალუტის ჭრილობები.
ექსპორტი: S3/SFTP ხელმოწერილი მანიფესტებითა და ფაილების ჰეშებით (SHA256).
მოხსენების დრო: UTC (თუ ხელშეკრულებაში სხვა რამ არ არის შეთანხმებული).

13) დაკვირვება და SLO

SLI: API- ის წარმატება 99. 95% (28d), კრიტიკული მეთოდების p95 ლატვია, ვებჰუკების მიწოდების წარმატება.
ბურნ-ალერტები (სწრაფი/ნული) არასწორი ბიუჯეტისთვის.
Trace კორელაცია: 'trace _ id' პასუხებში/ლოგოებში, drilldown ტრასებზე.
სტატუსის გვერდი: კომპონენტები Edge, Wallet, Bets, Webhooks, PSP, KYC.

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

PII მინიმიზაცია; აკრძალულია PAN/საიდუმლოებები ლოგოებში/ვებჰუკებში.
საიდუმლო მენეჯმენტი და გასაღებების როტაცია.
RG (Responsible Gambling): თვითგამორკვევის/ლიმიტების დროშებმა უნდა გამოიწვიოს განაკვეთების/გადახდების ავტომატური უარის თქმა.
AML/KYC: მოვლენები 'kyc. updated`, `aml. alert 'ხელმისაწვდომია გამოწერით; თქვენ მიიღებთ გადაწყვეტილებებს თქვენს სისტემაში ან ჩვენი მოდულის საშუალებით.
GDPR/DSAR: endpoints მოთამაშის პირადი მონაცემების გადმოტვირთვის/ამოღების იურიდიული მოთხოვნით.
mTLS და HSTS სტანდარტულად შედიან პროდ გარემოში.

15) პროდუქტიულობა და კვოტები

• RPS: 50 (burst 100)
• Concurrent webhooks: 10
• სხეულის ზომა: 256 KB (თამაშის მოვლენები), 64 KB (საფულე)

მოითხოვეთ გეგმის განახლება მენეჯერის ანგარიშის საშუალებით, მიუთითეთ RPS/მოცულობის პროგნოზი.

16) ცვლილებებისა და გამოშვებების მენეჯმენტი

Change Windows: დაგეგმილი სამუშაოები - გრაფიკის მიხედვით, შეტყობინება - 5 სამუშაო დღე.
ვერსიური მიგრაციები: ორმაგი-write/dul-read გარდამავალი პერიოდის განმავლობაში.
Contract ტესტები CI- ში: JSON სქემა, სავალდებულო ველები, სტაბილური 'error _ code'.
Canary: თანდათანობით ჩართვა ტრეფიკი ახალი ხაზებისთვის.

17) ინტეგრაციის სერტიფიკაცია

• განაკვეთის/გადახდის რეგისტრაცია/void
• Idempotention ყველა write endpoints
• სწორი დამუშავება 429/5xx + backoff
• ვებჰუკების ხელმოწერის გადამოწმება, 'X-GH-Event-ID'
• ბალანსის შერწყმა მთელი რიგი მოვლენების შემდეგ (win/lose)
• ჩანაწერების მოხსენებები ეთანხმება თქვენს მონაცემებს

• Webhuks Retrai განხორციელდა
• მომხმარებელთა ტაიმაუტები - 10s, ზოგადი მცდელობა - 30s
• Circuit-breaker დამოკიდებულია

• საიდუმლოების შენახვა საიდუმლოების მენეჯერში

• PII გამოცემა ლოგოებში
• RG/AML დროშები გათვალისწინებულია რეალურ დროში

18) ხშირად გამოყენებული სცენარები

18. 1 idempotence განაკვეთების რეგისტრაცია

POST /v1/bets
Idempotency-Key: bet-p_123-rnd_aa1-1

{ "player_id":"p_123","game_id":"g_777","stake":"1. 50","currency":"EUR","round_id":"rnd_aa1" }
→ 201 Created { "bet_id":"b_456" }

18. 2 Fail Webhuk შემდგომი წარმატებით

1. თქვენი სერვერი არ არის ხელმისაწვდომი 5xx backoff- ზე.
2. გამოჯანმრთელების შემდეგ - მიიღეთ იგივე „X-GH-Event-Id“ და უნდა უგულებელყოთ დუბლიკატები.

18. 3 პროვაიდერის ნაწილობრივი დეგრადაცია

ჩვენ დავუბრუნდებით 503; გაიმეორეთ backoff- დან.
გრძელი დეგრადაციით - პროვაიდერის გაჩერება და ნაზი. ჭკვიანი როუტინგი (თუ ხელშეკრულებაში).

19) DevEx და მხარდაჭერა

პორტალი: გასაღებები, დახმარება, ვებჰუკი, მიწოდების ლოგოები, SLO dashboards, ანგარიშების ექსპორტი.
Webhooks replay: ხელახალი მიწოდება თარიღების დიაპაზონში/ID.
ინციდენტები: ticet, war-room, postmortem - 48 საათი SEV-1.
კომუნიკაციები: # პარტნიორები-status არხი/ფოსტა 24 × 7 (Enterprise).

20) ონბორდის გეგმა (2-4 კვირა)

1. კვირა 1: გასაღების გაცემა, sandbox კავშირი, ძირითადი სკრიპტები (განაკვეთი/გადახდა/საფულე).
2. კვირა 2: ვებჰუკი და კრიპტები, RG/KYC დროშები, დატვირთული ტესტები, 429/5xx ქცევა.
3. კვირა 3: ანგარიშები (ჩანაწერები, გადმოტვირთვა), უსაფრთხოება (ხელმოწერები, საიდუმლოებები), კონტრაქტის ტესტები.
4. კვირა 4: სერტიფიკაცია, გაყიდვაში ჩართვა, მონიტორინგი, საკონტაქტო მატრიცა.

21) მინი-FAQ

შესაძლებელია GRPC?
დიახ, თხოვნით; HTTP შეცდომის კოდების mapping მოცემულია სპეციფიკაციაში.

როგორ მივიღოთ რეტრო მონაცემები?
'Reconciliation' (თარიღები 'from/to') ან S3/SFTP გადმოტვირთვის ანგარიშების საშუალებით.

როგორ გავზარდოთ ლიმიტები?
პორტალზე/ანგარიშზე მენეჯერის მეშვეობით, პროგნოზირებადი RPS/კონკურენტუნარიანობის მითითებით.

რა არის სიმართლის წყარო?
გარიგების ჟურნალი საფულე GambleHub + ყოველდღიური შერიგება.

შედეგი

GambleHub- სთან ინტეგრაცია ემყარება მკაფიო კონტრაქტს: სტაბილური API და სქემები, ხელმოწერილი ვებჰუკები, idempotence და retrais, გამჭვირვალე ლიმიტები და ანგარიშგებები, აგრეთვე უსაფრთხოების და შესაბამისობის მოთხოვნები. ამ ხელმძღვანელობისა და სასერთიფიკატო სიების შემდეგ, თქვენ სწრაფად გადადით პროდუქტში, უზრუნველყოთ საიმედო ფულადი ნაკადები და შეთანხმებული მოხსენებები შეუსაბამობის გარეშე.