Як підключати провайдерів через API: хендшейк, сертифікація, sandbox

Повний текст статті

💡 18+. Матеріал - інженерно-прикладний, не заклик до гри. Під «провайдером» розуміємо RGS/live-студію/джекпот/сервіс; під «платформою» - PAM/гаманець/каса/бонуси/RG.

1) Карта інтеграції: від заявки до продакшену

Етапи:

1. Пресейл і Due Diligence: юрпроверки, гео/ліцензії, сумісність контенту і RG-політик.

2. Хендшейк і безпека: видача sandbox-доступів, обмін ключами (mTLS/HMAC), реєстрація в Schema Registry.

3. Техдизайн: підтверджуємо доменну модель (sessions/bets/settlements/events), ідемпотентність, коди помилок.

4. Sandbox-інтеграція: емулятори гаманця/PSP/RG, тестові гравці, сценарії «дощу» і дублів.

5. Сертифікація: прогін обов'язкових тестів, підпис протоколів, навантаження і хаос-кейси.

6. Staging/UAT: бойові конфіги без реальних грошей, канарний трафік.

7. Go-Live: рота ключів, включення фіч-прапорів, моніторинг SLO, пост-інцидентна готовність.

2) Хендшейк: автентикація, авторизація, трасування

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 Health-перевірка (до коду)


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

3) Sandbox: що там є і як ним користуватися

Склад оточення:

Емулятор гаманця ('/wallet/debit	credit	rollback') з ідемпотентністю і затримками.
RG-хуки ('/rg/check','rg. limit. hit') і тестові профілі (самовиключення/ліміти).
Фальш-агрегатор/джекпот для внесків/тригерів.
Fake KYC/AML відповіді (allow/deny/pending).
Шина подій (Kafka/Pulsar) з тестовими топиками і Schema Registry.

Гармонія з реальністю:

Аналогічні версії схем і rate limits, що і в проді.
Тайм-ск'ю, дублі доставки, 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 Авторизація ставки (hold)


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 Сеттлмент (результат раунду)


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-стопи: самовиключення/ліміт втрат/часу → заборонити ставку.

Бонус/вейджер: внесок за типом гри, max bet, дедлайни.

6. 2 Навантажувальні

p95'bet/settle'в бюджетах (напр.'< 200-300 мс'), відсутність «штормів» ретраїв.

Потоки подій доходять до BI ≤ 5 хв.

6. 3 Хаос-кейси

Дублі доставки, затримки outbox/CDC, «відвал» регіону, частковий сеттлмент.

6. 4 Документи за підсумками

Протокол тестів з таймкодами/trace-id.

Звіт SLO (latency/error/lag).

Зведення безпеки (ключі, ротації, доступи, Vault/HSM).

7) Версіяція та міграції

HTTP: '/v1/...'в дорозі, події: 'schema _ version'в тілі.

SemVer: minor - додавання опціональних полів; major - тільки через новий префікс '/v2/'.

Deprecation headers: 'Deprecation','Sunset', дзеркало використання в дашборді.

Фіч-прапори: «подвійний лист» подій ('v1'і'v2') на перехідному періоді.

8) Безпека та відповідність

mTLS + підписи S2S, короткоживучі токени, обмежені скоупи.

Zero-trust: мережеві політики, per-brand/region ключі.

Data residency & PII: зберігання та логи в регіоні; RLS/маскування.

WORM-аудит: зміни лімітів, RTP-профілів, джекпот-конфігів.

RG/AML: синхронні стоп-сигнали на ставці/виплаті; SAR/STR звітність.

9) Вихід у прод: контрольний список запуску

До включення трафіку

Ротація sandbox-секретів → prod-ключі.

Включені дашборди p95/p99, error-rate, queue-lag, settle-lag.

Алерти SLO: breach по latency/error/lag, сплеск'DUPLICATE/IDEMPOTENCY _ MISMATCH'.

DR-план: RPO ≤ 5 хв, RTO ≤ 30 хв; «червона кнопка» - стоп нових сесій.

Канарка

1-5% аудиторії/ігор/гео; автоматичний rollback при порушенні SLO.

Пост-моніторинг 24-72 години, звірки леджера/звітів.

10) Анти-патерни (червоні прапори)

Публікація подій в обхід outbox/CDC.

Відсутність'X-Idempotency-Key'на write-операціях.

Ручні правки балансів/сеттлментів в БД.

Єдині ключі на кілька брендів/регіонів.

BI і регуляторні звіти поверх OLTP-бойової БД.

Нульові деградації: падіння провайдера валить гаманець/платформу.

11) Чек-листи

Для провайдера

Відправляю'X-Trace-Id'і'X-Idempotency-Key'завжди.
Підтримую повтор з тим же ключем без побічних ефектів.
Публікую події за схемами з Registry; зберігаю'schema _ version'.
Реалізовані ретраї з backoff і дедуплікація.
RG-стопи і бонусні обмеження дотримуються в real-time.
Доступи та секрети - per brand/region, ротація налаштована.

Для платформи

Outbox/CDC на всіх грошових шляхах; трасування end-to-end.
SLO-дашборди: p95/99, error-rate, queue-lag, settle-lag.
Deprecation/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. Здати протокол сертифікації: логи, trace-id, звіт SLO.

6. Перемкнути ключі на прод, включити канарку, спостерігати SLO.

7. Зафіксувати пост-релізні метрики і «уроки» в changelog.

Успішне підключення провайдера - це не тільки API, а керований процес: безпечний хендшейк, реалістичний sandbox, сувора сертифікація, спостережуваність і чіткі правила сумісності. Слідуючи описаним інваріантам (ідемпотентність, outbox/CDC, RG/AML-стопи, SLO і DR), ви прискорюєте інтеграції, уникаєте грошових інцидентів і отримуєте передбачувані релізи - без сюрпризів для гравців, регуляторів і Бізнес.