Провайдерлерге арналған бірыңғай API: дизайн, нұсқасы, үйлесімділігі

Мақаланың толық мәтіні

💡 18+. Интеграциялық және платформалық командаларға арналған техникалық материал. Ойынға шақыру емес.

1) «Бірыңғай API» не үшін және ол не

Бірыңғай API - бұл кез келген контент провайдері (RGS, live-студия, джекпот, KYC/AML, аффилиаттар) бір ереже бойынша платформамен сөйлесетін эндпоинттардың/оқиғалардың ерекшелігі мен жиынтығы:

бірыңғай ресурстық модель (players, sessions, bets, settlements, bonuses, jackpots, payments), оқиғалардың жалпы келісімшарттары және сәйкестендіргіштер, қауіпсіздік және кері үйлесімділік стандарттары, SDK/интеграцияны жеделдетуге арналған құралдар.

Мақсаты: time-to-integrate қысқарту, «ақша жолдарындағы» қателерді азайту және болжамды жаңартуларды қамтамасыз ету.

2) Дизайн қағидаттары

1. Domain-first. Алдымен сөздік және инварианттар (ставка, сеттлмент, RG лимиттері), содан кейін эндпоинттер.

2. Compatibility by default. Кез келген өзгеріс әдепкі бойынша үйлесімді; breaking-өзгерістер қатаң процесс бойынша.

3. Idempotency everywhere. Барлық ақшалай командалар кері әсерсіз қайталанады.

4. Events are source of truth (дистрибуцияда). Шина операциялары → оқиғалар; аналитика OLTP соқпайды, шина тыңдайды.

5. Least privilege & zero-trust. Маркалар, қолтаңбалар, бренд/өңір бойынша сегменттеу.

6. Observability. Өтпелі 'trace _ id', түсінікті қате моделі, p95/p99 метрикасы.

3) Ресурстық модель (жеңілдетілген)

Player: платформа жағындағы ойыншының псевдо-ID, гео/валюта/RG мәртебесі.

Session: провайдер мен платформа арасындағы арна ('session _ id', TTL, гео/шектеулер).

Bet: авторизация/мөлшерлеме дебеті.

Settlement: раундтың нәтижесі және ұтыс кредиті.

Bonus/Wager: вейджер бонусының/қалдығының жай-күйі.

Jackpot: жарналар/триггерлер/төлемдер.

Event: өзгермейтін домендік оқиғалар (Kafka/аналогтар).

Идентификаторлар: 'tenant _ id', 'brand _ id', 'region', 'player _ id', 'session _ id', 'round _ id', 'bet _ id', 'settlement _ id'. Барлығы - саптық, жаһандық бірегей (UUID/KSUID/Snowflake), логтар мен оқиғаларға қосылады.

4) API келісімшарттары: сұрау салулар, жауаптар, қателер

4. 1 Авторизация және қауіпсіздік

OAuth2 Client Credentials немесе mTLS + сұрау салу денесінің қолы (HMAC/EdDSA).

Скоупы вида: `bets:write`, `settlements:write`, `sessions:read`, `events:publish`.

Әрбір сұрау салуда мынадай тақырыптар міндетті:

`X-Trace-Id`, `X-Brand-Id`, `X-Region`, `X-Idempotency-Key`.

4. 2 Эндпоинттердің мысалдары

Сессияны жасау


POST /v1/sessions
{
"player_id":"p_19f3",  "game_id":"studio:slot_forge_02",  "currency":"EUR",  "locale":"de-DE",  "constraints":{"max_bet":5,"rg_flags":["self_exclusion":false]}
}
→ 201
{
"session_id":"s_456",  "expires_at":"2025-10-23T19:10:00Z"
}

Мөлшерлемені авторизациялау (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" }

Сеттлмент


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. 3 Қателер (бірыңғай модель)

`code`: машинное имя (`RG_BLOCK`, `LIMIT_EXCEEDED`, `DUPLICATE`, `IDEMPOTENCY_MISMATCH`, `INVALID_STATE`, `AUTH_FAILED`).

'message': адам үшін қысқаша.

`retryable`: `true/false`.

'trace _ id': логдарда іздеу үшін.

Мысал:


409 CONFLICT
{
"code":"DUPLICATE",  "message":"Bet already authorized with a different amount",  "retryable":false,  "trace_id":"tr_a1b2c3"
}

5) Оқиғалық шина және схемалар

5. 1 Негізгі топиктер

`player. registered`, `session. started	ended`
`bet. authorized	settled
`bonus. issued	consumed
`wager. progress. updated`
`jackpot. contribution	triggered
`rg. limit. hit`, `rg. reality_check`
`wallet. debit.`, `wallet. credit.`

5. 2 Оқиға схемасы (Euro/JSON Schema)

json
{
"event_id":"uuid",  "event_type":"bet. settled",  "occurred_at":"2025-10-23T16:21:05Z",  "tenant_id":"brand-7",  "region":"EU",  "player_id":"p_19f3",  "trace_id":"tr_a1b2c3",  "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",  "schema_version":"1. 2. 0"
}

Ережелер: backward-compatible схема эволюциясы, registry + келісімшарттық тестілер.

6) API нұсқасы: стратегиялар мен ережелер

6. 1 Нұсқаны қайда сақтау керек

Path-нұсқасы: '/v1/... '(жай кешімдеу/бағыттау).

Header нұсқасы: 'Accept: application/vnd. platform. api+json; version=1. 2`.

Оқиғалар: 'schema _ version' оқиға өрісінде + registry.

Тәжірибе: HTTP үшін path, оқиғалар үшін schema_version, нүктелік мүмкіндіктер үшін фичфлагтар.

6. 2 SemVer және өзгерістер түрлері

PATCH (minor) - кері түйісетін: жаңа міндетті емес өрістер, жаңа эндпоинттер, оқиғалардың жаңа түрлері.

MAJOR - breaking: өрістерді қайта атау, семантиканы өзгерту, жою. Тек жаңа '/vN/' және ескісін депрекациялау арқылы рұқсат етіледі.

6. 3 Тұрақты келісімшарттар (оны бұзуға болмайды)

Сәйкестендірудің негізгі өрістерінің атаулары мен түрлері ('_ id', 'idempotency _ key').

Ақша моделі ('amount/currency', дәлдік).

Мәртебелер семантикасы ('authorized', 'credited', 'forfeited' және т.б.).

Теңсіздік: қайталау кезіндегі мінез-құлық қатаң айқындалған.

7) Үйлесімділік және эволюция

7. 1 Қосымшалар (safe)

Дефолттары бар жаңа міндетті емес өрістер.

Бар оқиғаларды өзгертпей жаңа оқиғалар/эндпоинттер.

'unknown' дегендегі fallback enum кеңейтімі.

7. 2 Өзгерістер (risky)

Өріс түрін өзгерту (сан → жол).

Міндеттілікті өзгерту (optional → required).

Бизнес-логиканы бұру ('settle' бұрын 'authorize').

→ жаңа мажорлық нұсқа мен көші-қон нұсқасы қажет.

7. 3 Депрекация

Өріс/эндпоинт 'deprecated _ since: 1 деп белгіленеді. 7`, `removed_in: 2. 0`.

Коммуникация: release notes, тарату, deprecation-headers («Sunset», «Deprecation»).

Белсенді серіктес хабарламалары үшін «ескірген» жолдарды пайдалану.

8) Үйлесімділік және келісімділік

'X-Idempotency-Key' тақырыбы барлық жазатын операциялар үшін міндетті.

Семантика: сол кілтпен қайталау → сол нәтиже (бұрынғы body-мен 200).

Кілттер параметрлер композициясына байланыстырылған (мысалы, 'bet _ id + amount').

Ұзақ үдерістегі сағалар: 'authorize → commit/lock → settle → credit'; өтемақылар - 'rollback' оқиғаларымен.

9) Пагинация, сүзгілер, сұрыптау

Cursor-based пагинациясы (үлкен ағындар үшін 'page/limit' дегенді қатаң таңдайды).

Біріздендіру: '? cursor =... & limit = 200 & order = asc'.

Жауап: 'next _ cursor', 'has _ more'.

Сүзгілер: уақыт бойынша ('occurred _ at _ from/to'), 'tenant _ id', 'game _ id', 'status'.

10) Валюталардың локальдары, деректердің резиденттігі

ISO-4217 валюта; дәлдік схемада сақталады ('scale'), есептеулер - minor-units (cents).

Локальдар - BCP 47 ('en-GB', 'pt-BR').

Әрбір сұрауда - 'region'; PII және ақша операциялары өңірлерден өтпейді.

BI витриналарында PII және RLS бүркемелеу.

11) Бақылау және лимиттер

Міндетті тақырыптар: 'X-Trace-Id', 'X-Provider-Id', оқиғалармен корреляция.

Метриктер: p50/p95/p99 latency, error rate (кодтар бойынша), throughput, queue lag (оқиғалар үшін).

Rate limits: per provider / per brand; жауаптар 'Retry-After'.

Сындарлы өзгерістердің WORM-аудиті (лимиттер, RTP-пулдар, джекпот формулалары).

12) Тестілеу және келісімшарттардың сапасы

Келісімшарттық тесттер (Pact/басқалар): провайдер, платформа, оқиғалар консьюмерлері.

Жүктемелік: ставкалар/сеттлменттер «дауылы»; p95 мақсаттары.

Хаос-кейстер: дубль-жеткізу, out-of-order, әмиян кідірісі.

Жалған ақша және тестілік 'player _ id' бар '/sandbox 'құмсалғышы.

13) SDK, генераторлар және құжаттама

OpenAPI/AsyncAPI → SDK генерациясы (TypeScript/Java/Kotlin/Go/Rust).

'authorize/settle/rollback', ретрайлер мен қателерді өңдеуге арналған код мысалдары.

Сұрау/жауап мысалдары бар Live-док (curl + JSON), Postman/Insomnia жинағы.

Changelog өзгерістері мен үйлесімділік белгілері бар.

14) Көші-қонның жол картасы (мысал)

1. v1. 6 → v1. 7 (minor): 'bonus _ state' өрісін 'settle' (optional) деп қосты.

2. v1. x EOL анонс: 6 ай үшін - + 'Deprecation' header + дашборд пайдалану.

3. v2. 0 (major): жеке 'wallet. commit '(бұрын implicit), жаңа' settlement _ id 'өрісі міндетті.

4. Көші-қон гайды: өрістердің маппингі, timeline, «қос хат» фичфлагы ('v1 '/' v2' оқиғаларын қатар жариялау).

5. Sunset v1: жаңа интеграцияларды бұғаттау, тек SLA ерекшеліктері бойынша ұзарту.

15) Чек парақтары

Платформа сәулетшілері үшін

Домендік мәндер мен инварианттардың бірыңғай сөздігі бар.
OpenAPI/AsyncAPI + Schema Registry, semver, депрекация процесі.
Барлық write-операциялардағы теңсіздік; кілттер құжатталған.
Бірыңғай қате-модель және кодтар.
Ақша жолдарындағы сағаттар мен outbox/CDC.
Rate-limits, observability, WORM-аудит.
Құмсалғыш және келісімшарттық тесттер серіктестерге қолжетімді.
Data residency және RLS/бүркемелеу.

Провайдер үшін

Әрдайым 'X-Trace-Id' және 'X-Idempotency-Key' жіберемін.
Сұрау қайталауларын қауіпсіз өңдеймін; дубли жасамаймын.
«Deprecation/Sunset» дегенді өңдеймін және Changelog дегенді оқимын.
registry схемалары бойынша оқиғаларды жариялаймын/оқимын; нұсқасын сақтаймын.
Менің тарапымда retry/backoff және дедупликация бар.

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

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

outbox/CDC «өткен» оқиғаларын жариялау.

idempotency → төлем/дебет дублінің болмауы.

Әр түрлі аймақтардың PII/ақшаларын 'region' таңбасыз араластыру.

«Тыныш» breaking-өзгерістері жаңа нұсқасыз және депрекациясыз.

Қолмен SDK генерациялау (нақты дәнекерден дрейф).

Big-bang фичфлагсыз және оқиғаларды қосарлы жазусыз көші-қон.

Бірыңғай API - бұл тек «эндпоинттердің коллекциясы» ғана емес, экожүйенің келісімшарты: келісілген сөздік, тұрақты ақша инварианттары, нұсқалау оқиғалары, үйлесімділіктің түсінікті ережелері және басқарылатын депрекациялар. Семантикалық нұсқаға, теңсіздікке, outbox/CDC, бақылауға және қатаң қауіпсіздікке сүйене отырып, платформа провайдерлерді жылдам және ауыртпалықсыз қосады, ал апгрейдтер тәуекелден дағдыға айналады.