Підручник з інтеграції GambleHub

1) Огляд і модель взаємодії

• API-провайдер: ви викликаєте API GambleHub (гаманець, бонуси, звіти).
• Екстернальний постачальник: ми викликаємо ваші вебхуки/ендпоінти (баланс, транзакції, KYC).

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

2. Події (event bus: ставки/виплати/гаманець/КУС)

3. Звітність (API + експорт S3/SFTP)

4. Операції (інциденти, SLO, SLA-кредити)

2) Середовища, домени та IP

Контрактний SLA фіксується в договорі. Оновлення IP публікуються завчасно. Дозвольте Allowlist.

3) Автентифікація та авторизація

• OAuth2 Client Credentials: сервер-к-серверу ('scope'-и: `wallet:read`, `wallet:write`, `bet:write`, `report:read`).
• JWT (issuer = GambleHub): підпис RS256, ключі в JWKS-ендпоінті.
• mTLS: взаємна TLS-аутентифікація на рівні ingress (за запитом комплаєнсу).

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

Scopes перевіряються на кожному виклику. Для високоризикових операцій (виплати) використовується step-up: окремий scope і, опціонально, прив'язка до IP/ASN.

4) Версіонування та сумісність

Шлях: '/v1/...', '/v2/...'( major-версія несумісна назад).
Мінорні і розширюючі зміни - через розширення схеми (нові опціональні поля).
Депрекації - за 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`: спроба №
• `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 вважається успіхом. Інакше - ретраї: експоненціальний backoff (1s, 3s, 10s, 30s, 2m, 10m, 30m; максимум 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: відповіді'verified'failed'review'за шаблонами паспортів.
PSP sandbox: статуси'authorized'captured'declined'reversed'.

• Stavka→vyplata→sverka балансу
• Відкат/void раунду
• Idempotency при повторній ставці
• Збій вебхука з ретраями і подальшою дедуплікацією
• 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, провайдери, розріз по гео/валютах.
Експорт: S3/SFTP з підписаними маніфестами і хешами файлів (SHA256).
Таймзона звітів: UTC (якщо не обумовлено інше в контракті).

13) Спостережуваність і SLO

SLI: успішність API ≥ 99. 95% (28d), p95 latency для критичних методів, успішність доставки вебхуків.
Burn-alerts (fast/slow) за помилковим бюджетом.
Trace-кореляція: 'trace _ id'у відповідях/логах, drilldown до трас.
Статус-сторінка: компоненти Edge, Wallet, Bets, Webhooks, PSP, KYC.

14) Безпека та комплаєнс

PII-мінімізація; заборонені PAN/секрети в логах/вебхуках.
Secret-management і ротація ключів.
RG (Responsible Gambling): прапори самовиключення/лімітів повинні призводити до автоматичної відмови в ставках/виплатах.
AML/KYC: події'kyc. updated`, `aml. alert'доступні за передплатою; рішення приймаєте у своїй системі або через наш модуль.
GDPR/DSAR: ендпоінти для вивантаження/видалення персональних даних гравця за юридичними запитами.
mTLS і HSTS включені за замовчуванням в прод-середовищі.

15) Продуктивність і квоти

• RPS: 50 (burst 100)
• Concurrent webhooks: 10
• Розмір тіла: ≤ 256 KB (ігрові події), ≤ 64 KB (гаманець)

Запитайте апгрейд плану через аккаунт-менеджера, вказавши прогноз RPS/обсяги.

16) Управління змінами та релізами

Change windows: планові роботи - за розкладом, повідомлення ≥ 5 робочих днів.
Версійні міграції: dual-write/dual-read в перехідний період.
Contract-тести в CI: схема JSON, обов'язкові поля, стабільні'error _ code'.
Canary: поступове включення трафіку для нових фіч.

17) Сертифікація інтеграції (Check-list)

• Реєстрація ставки/виплати/void
• Ідемпотентність на всіх write-ендпоінтах
• Коректна обробка 429/5xx + backoff
• Верифікація підпису вебхуків, дедуплікація по'X-GH-Event-Id '
• Звірка балансу після серії подій (win/lose)
• Звіти reconciliation сходяться з вашими даними

• Ретраї вебхуків реалізовані
• Таймаути клієнтів ≤ 10с, загальна спроба ≤ 30с
• Circuit-breaker на залежності

• Зберігання секретів в менеджері секретів
• PII-редакція в логах
• RG/AML прапори враховуються в реальному часі

18) Часто використовувані сценарії

18. 1 Реєстрація ставки з ідемпотентністю

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 Фейл вебхука з подальшим успіхом

1. Ваш сервер недоступний → 5xx → ретраї по backoff.
2. Після відновлення - приймаєте той же'X-GH-Event-Id'→ зобов'язані ігнорувати дублікати.

18. 3 Часткова деградація провайдера

Ми повернемо 503; повторіть з backoff.
При довгій деградації - стоп-маркування провайдера і вкл. smart-routing (якщо в контракті).

19) DevEx і підтримка

Portal: ключі, usage, вебхуки, логи доставки, дашборди SLO, експорт звітів.
Webhooks replay: повторна доставка по діапазону дат/ID.
Інциденти: auto-створення тікету, war-room, постмортем ≤ 48 год по SEV-1.
Комунікації: #partners -status канал/пошта on-call 24 × 7 (Enterprise).

20) План онбордингу (2-4 тижні)

1. Тиждень 1: видача ключів, підключення sandbox, базові сценарії (ставка/виплата/гаманець).
2. Тиждень 2: вебхуки і звірки, RG/KYC прапори, навантажувальні тести, 429/5xx поведінка.
3. Тиждень 3: звітність (reconciliation, вивантаження), безпека (підписи, секрети), контракт-тести.
4. Тиждень 4: сертифікація, canary-включення в проді, моніторинг, контактна матриця.

21) Міні-FAQ

Чи можна gRPC?
Так, за запитом; мапінг кодів помилок на HTTP надається в специфікації.

Як отримати ретро-дані?
Через звіти'reconciliation'( дати'from/to') або S3/SFTP вивантаження.

Як збільшити ліміти?
Через портал/аккаунт-менеджера із зазначенням прогнозних RPS/конкурентності.

Що вважати джерелом істини балансу?
Транзакційний журнал гаманця GambleHub + щоденна звірка (reconciliation).

Підсумок

Інтеграція з GambleHub будується на чіткому контракті: стабільні API і схеми, підписані вебхуки, ідемпотентність і ретраї, прозорі ліміти і звітність, а також вимоги безпеки і комплаєнсу. Дотримуючись цього керівництва і чек-листів сертифікації, ви швидко вийдете в прод, забезпечивши надійні грошові потоки і узгоджені звіти без розбіжностей.