Przewodnik integracyjny Gam, Hub

1) Przegląd i model interakcji

• Dostawca API: dzwonisz do API Gamz Hub (portfel, bonusy, raporty).
• Zewnętrzny dostawca: nazywamy Twoje haki/punkty końcowe (saldo, transakcje, KYC).

1. Krawędź/API (REST/gRPC, Webhooks)

2. Wydarzenia (autobus wydarzeń: zakłady/wypłaty/portfel/ICC)

3. Sprawozdawczość (API + S3/SFTP eksport)

4. Operacje (incydenty, SLO, kredyty SLA)

2) Środowiska, domeny i IP

Umowa SLA jest ustalona w umowie. Aktualizacje IP są publikowane z wyprzedzeniem. Zezwala na listę dopuszczalną.

3) Uwierzytelnianie i autoryzacja

• OAuth2 poświadczenia klienta: serwer-serwer ('zakres': 'portfel: read', 'portfel: write', 'bet: write', 'report: read').
• JWT (emitent = GamلHub): podpis RS256, klucze w punkcie końcowym JWKS.
• mTLS: wzajemne uwierzytelnianie TLS na poziomie ingress (na żądanie zgodności).

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

Scopy są sprawdzane przy każdym połączeniu. W przypadku operacji wysokiego ryzyka (płatności) stosuje się stopień zaawansowania: odrębny zakres i, opcjonalnie, powiązanie z IP/ASN.

4) Wersioning i kompatybilność

Ścieżka: '/v1/... ", "/v2/..." (główna wersja jest niezgodna z plecami).
Drobne i rozszerzające się zmiany - poprzez rozszerzenie schematu (nowe pola opcjonalne).
Spadki - 90 dni z powiadomieniem.
Haki są wersjonowane z tytułem „X-GH-Event-Version: 1”.

5) Limity, kwoty i idempotencja

• 'Limit-Limit-X', 'Limit-Pozostały', 'X-Limit-Reset'.
• 429 wraca z 'Retry-After' (sekundy).
• Wszystkie niebezpieczne metody wymagają 'Idempotency-Key' (TTL 24-72 h). Powtarzanie identycznego zapytania zwraca oryginalny wynik ('409 IDEMP_REPLAY' w sprawie konfliktu).

6) Normy błędów

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”). Nie do odzyskania: 400/401/403/404/409/ 422/410/415/412.

7) Schematy danych (rdzeń)

7. 1 Gracz

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 Sesja

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 Portfel/transakcje

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 Stopa/wypłata

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 Bonus

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 (fragmenty 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) Haki internetowe (Gam, Hub do partnera)

• 'X-GH-Event': 'gracz. stworzona "sesja. zaczął 'bet. umieszczone 'bet. settled 'portfel. zmienił 'kyc. zaktualizowany 'rg. flagowany "
• 'X-GH-Event-Id': unikalny UUID
• „Podpis X-GH”: „sha256 = ”
• 'X-GH-Retry': Próba nr
• „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"
}
}

Odpowiedź gospodarza - tylko 2xx jest uważany za sukces. Inaczej - retrai: wykładniczy backoff (1s, 3s, 10s, 30s, 2m, 10m, 30m; maksymalnie 24 godziny). Użyj 'X-GH-Event-Id' do deduplikacji.

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

10) Przepływ środków pieniężnych (przepływ portfela)

1. depozyt (PSP → portfel. kredyt)

2. zakład (hold/authorize ила direct debit)

3. rozrachunek (zwolnienie; „wygrana ”/„ przegrana ”/„ nieważność”)

4. wycofanie (portfel. debit → PSP)

Obsługiwane są salda i portfele wielofunkcyjne (real/bonus).

11) Piaskownica i scenariusze testów

Gracze testowi: 'p _ sbx _', waluty' EUR 'USD' CAD '.
Dostawcy gier emulate: win/lose/void, rabaty, opóźnienia.
Piaskownica KYC: „zweryfikowany” nieudany „przegląd” odpowiedzi na szablony paszportów.
PSP sandbox: статеса 'authorized' captied 'declined' reversed '.

• Bilans Stavka → vyplata → sverka
• Pullback/pustka okrągła
• Idempotencja przy ponownej ofercie
• Awaria haka z przekładkami i późniejszą deduplikacją
• 429 i poprawne „Retry-After”
• 5xx z klientem-side wykładnicze backoff

12) Uzgodnienia i sprawozdawczość

Uzgodnienie API

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

Podsumowania dzienne: obroty, GGR/NGP, dostawcy, podział geo/walutowy.
Eksport: S3/SFTP z podpisanymi manifestami i hashami plików (SHA256).
Strefa czasowa sprawozdawczości: UTC (chyba że w umowie określono inaczej).

13) Obserwowalność i SLO

SLI: sukces API ≥ 99. 95% (28d), opóźnienie p95 dla metod krytycznych, sukces dostawy haków internetowych.
Alerty oparzeniowe (szybkie/powolne) na błędny budżet.
Korelacja śladu: 'trace _ id' w odpowiedziach/dziennikach, wiercenie do śladów.
Strona stanu: Krawędź, Portfel, Zakłady, Haki internetowe, PSP, komponenty KYC.

14) Bezpieczeństwo i zgodność

minimalizacja PII; PAN/tajemnice są zabronione w dziennikach/hakach internetowych.
Tajne zarządzanie i rotacja kluczy.
RG (Responsible Gambling): flagi samodzielnego wykluczenia/limitu powinny skutkować automatycznym zaprzeczeniem zakładów/płatności.
AML/KYC: wydarzenia "kyc'. zaktualizowane ',' aml. alert "jest dostępny przez subskrypcję; podejmować decyzje w systemie lub za pośrednictwem naszego modułu.
RODO/DSAR: punkty końcowe do przesyłania/usuwania danych osobowych gracza w przypadku wniosków prawnych.
mTLS i HSTS są domyślnie włączone w środowisku produkcyjnym.

15) Wyniki i kwoty

• RPS: 50 (wybuch 100)
• Równoległe haki: 10
• Wielkość ciała: ≤ 256 KB (gry), ≤ 64 KB (portfel)

Zażądaj uaktualnienia planu za pośrednictwem menedżera konta, określając prognozę/woluminy RPS.

16) Zarządzanie zmianą i uwolnieniem

Zmiana okien: zaplanowana praca - w harmonogramie, powiadomienie ≥ 5 dni roboczych.
Migracje w wersji: podwójne zapisy/podwójne odczyty w okresie przejściowym.
CI testy kontraktowe: schemat JSON, wymagane pola, stabilny 'error _ code'.
Kanaryjskie: stopniowe włączanie ruchu dla nowych funkcji.

17) Certyfikat integracji (lista kontrolna)

• Oferta/płatna rejestracja/nieważność
• Idempotencja we wszystkich punktach końcowych zapisu
• Poprawne przetwarzanie 429/5xx + backoff
• Webhook Signature Verification, X-GH-Event-Id Deduplication
• Uzgodnienie równowagi po serii wydarzeń (wygrana/przegrana)
• Raporty pojednawcze zgadzają się z danymi użytkownika

• Wycofania z haka są realizowane
• Czasy klienta ≤ 10c, próba całkowita ≤ 30c
• Wyłącznik od zależności

• Przechowywanie tajemnic w Secret Manager
• Wydanie PII w dziennikach
• Flagi RG/AML są brane pod uwagę w czasie rzeczywistym

18) Często stosowane scenariusze

18. 1 Stawka rejestracji z idempotencją

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 webhook a następnie sukces

1. Twój serwer jest niedostępny → 5xx → backoff retro.
2. Po odzyskaniu - wziąć te same 'X-GH-Event-Id' → są zobowiązane do ignorowania duplikatów.

18. 3 Częściowa degradacja usługodawcy

Zwrócimy 503; powtórzyć backoff.
Przy długiej degradacji - zaprzestać znakowania dostawcy i w tym inteligentnych tras (jeśli w umowie).

19) DevEx i wsparcie

Portal: klucze, wykorzystanie, haki internetowe, dzienniki dostawy, deski rozdzielcze SLO, raporty eksportowe.
Webhooks replay: redelivery by date range/ID.
Incydenty: auto-tworzenie biletu, pokój wojenny, postmortem ≤ 48 godzin na SEV-1.
Komunikacja: # partners-status channel/mail-call 24 × 7 (Enterprise).

20) Plan pokładowy (2-4 tygodnie)

1. Tydzień 1: emisja kluczy, połączenie piaskownicy, scenariusze bazowe (zakład/płatność/portfel).
2. Tydzień 2: haki i pojednania, flagi RG/KYC, testy obciążenia, zachowanie 429/5xx.
3. Tydzień 3: raportowanie (pojednanie, przesyłanie), bezpieczeństwo (podpisy, sekrety), testy kontraktowe.
4. Tydzień 4: certyfikacja, włączenie kanaryjskie do sprzedaży, monitorowanie, matryca kontaktowa.

21) Mini-FAQ

Mogę dostać gRPC?
Tak, na życzenie; W specyfikacji podano mapowanie kodu błędu HTTP.

Jak uzyskać dane retro?
Za pomocą raportów „pojednania” (od/do dat) lub S3/SFTP przesyłania.

Jak usunąć swoje limity?
Za pośrednictwem portalu/menedżera rachunku wskazującego prognozę RPS/konkurencyjność.

Co jest uważane za źródło prawdy równowagi?
Dziennik transakcji portfela Gamz + dzienne pojednanie.

Razem

Integracja z Gamz Hub opiera się na jasnej umowie: stabilnych interfejsów API i systemów, podpisanych haków internetowych, idempotencji i przekwalifikowań, przejrzystych limitów i sprawozdawczości, a także wymogów bezpieczeństwa i zgodności. Wykonując ten przewodnik i listy kontrolne certyfikacji, szybko trafisz na rynek, zapewniając niezawodne przepływy pieniężne i spójne raporty bez rozbieżności.