Как подключать провайдеров через 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/хаос-учения, инцидент-менеджмент и постмортемы.
Режимы деградаций: `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), вы ускоряете интеграции, избегаете денежных инцидентов и получаете предсказуемые релизы — без сюрпризов для игроков, регуляторов и бизнеса.