Руководство по интеграциям GambleHub

1) Обзор и модель взаимодействия

• API-провайдер: вы вызываете API GambleHub (кошелек, бонусы, отчеты).
• Экстернальный поставщик: мы вызываем ваши вебхуки/эндпоинты (баланс, транзакции, KYC).

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

2. События (event bus: ставки/выплаты/кошелек/KYC)

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`.

• Ставка→выплата→сверка баланса
• Откат/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 и схемы, подписанные вебхуки, идемпотентность и ретраи, прозрачные лимиты и отчетность, а также требования безопасности и комплаенса. Следуя этому руководству и чек-листам сертификации, вы быстро выйдете в прод, обеспечив надежные денежные потоки и согласованные отчеты без расхождений.