Провайдерлерді 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`.

Мысалы Euro/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 алерты: latency/error/lag бойынша breach, «DUPLICATE/IDEMPOTENCY _ MISMATCH».

DR-жоспар: RPO ≤ 5 мин, RTO ≤ 30 мин; «қызыл түймешік» - жаңа сессияларды тоқтату.

Канарейка

1-5% аудитория/ойындар/гео; SLO бұзылғанда автоматты rollback.

Пост-мониторинг 24-72 сағат, леджер/есептерді салыстыру.

10) Қарсы үлгілер (қызыл жалаулар)

Оқиғаларды outbox/CDC тексеріп шығу арқылы жариялау.

write-операцияларында 'X-Idempotency-Key' болмауы.

Баланстарды/сеттлменттерді ДБ-да қолмен түзету.

Бірнеше брендке/өңірлерге арналған бірыңғай кілттер.

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) арқылы сіз интеграцияны жеделдетесіз, ақшалай оқыс оқиғаларды болдырмайсыз және ойыншыларға, реттеушілерге және бизнеске тосын сый жасамайсыз.