API аркылуу провайдерлерди кантип туташтыруу керек: хэндшейк, сертификация, sandbox

Макаланын толук тексти

💡 18+. Материал - инженердик-колдонмо, оюнга чакыруу эмес. "Провайдер" деп биз RGS/live-студиясын/джекпот/кызматын түшүнөбүз; "платформа" астында - PAM/капчык/касса/бонустар/RG.

1) Интеграция картасы: өтүнмөдөн өндүрүшкө чейин

Этаптары:

1. Pressale жана Due Diligence: юрпроверки, гео/лицензиялар, мазмундун шайкештиги жана RG саясаты.

2. Хендшейк жана коопсуздук: sandbox-жетүү берүү, ачкычтарды алмашуу (mTLS/HMAC), Schema реестрине каттоо.

3. Техдизайн: Биз домен моделин (sessions/bets/settlements/events), боштук, ката коддорун тастыктайбыз.

4. Sandbox Integration: капчык эмуляторлор/PSP/RG, тесттик оюнчулар, "жамгыр" жана дубль.

5. Сертификация: милдеттүү тесттердин өтүшү, протоколдордун кол тамгасы, жүктөр жана башаламандык учурлары.

6. Staging/UAT: чыныгы акча, канарейка трафик жок согуш чыр-чатактар.

7. Go-Live: компания ачкычтар, Fich желектерди күйгүзүү, SLO мониторинг, пост-окуя даярдык.

2) Handshake: Autentication, Authorization, Tracking

2. 1 Сырларды жана сатып алууларды алмашуу

mTLS (per brand/region сертификаттары) жана/же OAuth2 Client Credentials.

HMAC/EdDSA (эмес-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 Ден соолук текшерүү (кодго чейин)


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 каттоо.

чындык менен гармония:

Окшош нускасы схемалар жана 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 схемасы (үзүндү '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 Функционалдык сценарийлер (минимум)

Ошол эле 'X-Idempotency-Key' менен 'authorize/settle' өтүнүчүн кайталоо → ошол эле жооп.

Out-of-order: келди 'settle' жок 'authorize' → туура баш тартуу.

Rollback чынжыр капчык/тармак кулагандан кийин.

RG-Stop: өзүн-өзү жоюу/жоготуу/убакыт чеги → ченди тыюу.

Bonus/Waiger: оюн түрү боюнча салым, max bet, мөөнөтү.

6. 2 Жүктөө

p95 'bet/settle' бюджеттерде (мисалы, '<200-300 ms'), "бороон-чапкындардын" жоктугу.

Окуялардын агымы 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/аймак ачкычтары.

Data residency & PII: аймакта сактоо жана каттоо; RLS/маска.

WORM-аудит: лимиттерди, RTP профилдерин, джекпот конфигурацияларын өзгөртүү.

RG/AML: чен/төлөө боюнча синхрондуу токтоо сигналдары; SAR/STR отчеттуулук.

9) Продукт чыгуу: ишке киргизүү контролдук тизмеси

Жол киргенге чейин

Sandbox сырларын айлантуу → прод-ачкычтар.

p95/p99, error-rate, queue-lag, settle-lag дашборддору кирет.

SLO Alerts: 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 согуштук DD үстүнөн жөнгө салуучу отчеттор.

Нөлдүк деградациялар: провайдердин кулашы капчыкты/платформаны талкалайт.

11) Чек-баракчалар

Провайдер үчүн

Мен ар дайым 'X-Trace-Id' жана 'X-Idempotency-Key' жөнөтүү.
Мен терс таасирлери жок эле ачкычы менен кайталоону колдойт.
Registry схемалар боюнча окуяларды жарыялоо; сактайт 'schema _ version'.
backoff жана deduplication менен ишке ашырылган.
RG-бут жана бонустук чектөөлөр реалдуу убакытта сакталат.
Кирүү жана сырлар - per brand/region, айлануу орнотулган.

Платформа үчүн

бардык акча жолдорунда Outbox/CDC; end-to-end.
SLO-дашборддор: p95/99, error-rate, queue-lag, settle-lag.
Deprecation/Sunset жараяны, көчүрүү боюнча окуялардын кош кат.
DR/xaoc-машыгуулар, окуя-менеджмент жана postmortems.
Деградация режимдери: 'no new sessions', промо/джекпот өчүрүү.

12) Мисалы "минималдуу" интеграция playbook (TL; DR)

1. Кол NDA/келишим → sandbox-жетүү жана схемалар берүү.

2. mTLS/HMAC күбөлүк алмашуу; 'provider _ id'.

3. минималдуу EndPoint макулдашуу: 'sessions', 'bets/authorize', 'bets/settle', 'rollback'.

4. Sandbox шинага жана Registry туташуу; иштеп/башаламандык учурларды кууп.

5. Сертификация протоколун тапшыруу: логи, trace-id, SLO отчету.

6. Ачкычтарды прод которуп, канарейканы күйгүзүп, СЛОну байкоо.

7. Пост-релиздик көрсөткүчтөрдү жана "сабактарды" changelog.

Провайдердин ийгиликтүү байланышы - бул бир гана API эмес, башкарылуучу процесс: коопсуз хэндшейк, реалдуу sandbox, катуу сертификация, байкоо жана так шайкештик эрежелери. Сүрөттөлгөн инварианттарды (демпотенттик, outbox/CDC, RG/AML-бут, SLO жана DR) ээрчип, сиз интеграцияны тездетип, акчалай инциденттерден качасыз жана оюнчулар, жөнгө салуучулар жана бизнес үчүн күтүүсүз релиздерди аласыз.