API-и ягона барои провайдерҳо: тарроҳӣ, версия, мутобиқат

Мақолаи пурра

💡 18+. Маводи техникӣ барои ҳамгироӣ ва гурӯҳҳои платформа. На даъват ба бозӣ.

1) Чаро "API ягона" ва он чӣ аст

API-и ягона мушаххасот ва маҷмӯи нуқтаҳо/чорабиниҳоест, ки тавассути он ҳама провайдерҳои мундариҷа (RGS, студияи зинда, jackpot, KYC/AML, шарикон) бо платформа тибқи ҳамон қоидаҳо тамос мегиранд:

модели ягонаи захираҳо (бозингарон, ҷаласаҳо, гаравҳо, ҳисоббаробаркунӣ, бонусҳо, jackpots, пардохтҳо), шартномаҳои умумӣ ва идентификаторҳо, стандартҳои амният ва мутобиқати қафо, SDK/воситаҳо барои суръат бахшидани ҳамгироӣ.

Ҳадаф: кам кардани вақт барои ҳамгироӣ, кам кардани хатогиҳо дар "роҳҳои пулӣ" ва такмилдиҳии пешгӯишаванда.

2) Принсипҳои тарроҳӣ

1. Домен-аввал. Аввалан, луғат ва инвариантҳо (суръат, танзим, маҳдудиятҳои RG), баъд нуқтаҳои ниҳоӣ.

2. Мутобиқат бо нобаёнӣ. Ҳама гуна тағирот бо нобаёнӣ мувофиқ аст; шикастани тағирот ба таври қатъӣ аз рӯи раванд.

3. Idempotency дар ҳама ҷо. Ҳама фармонҳои пулӣ бе таъсири тараф такрор карда мешаванд.

4. Ҳодисаҳо манбаи ҳақиқат мебошанд. Амалиёт → чорабиниҳо ба автобус; таҳлилҳо автобусро гӯш мекунанд, на OLTP.

5. Имтиёзи камтарин ва эътимод ба сифр. Токенҳо, имзоҳо, тақсимот аз рӯи бренд/минтақа.

6. Мушоҳида. 'Trace _ id', модели хатогии фаҳмо, ченакҳои p95/p99.

3) Модели захираҳо (соддакардашуда)

Бозингар: Плеери паҳлӯии платформаи псевдо-ID, гео/асъор/RG.

Сессия: канал байни провайдер ва платформа ('session _ id', TTL, geo/маҳдудиятҳо).

Бет: авторизатсия/дебет.

Ҳисоббаробаркунӣ: Натиҷаи давр ва гирифтани қарз.

Bonus/Wager: Вазъи тавозуни бонус/vager.

Jackpot: саҳмияҳо/триггерҳо/пардохтҳо.

Ҳодиса: рӯйдодҳои домени тағирёбанда (Кафка/аналогҳо).

Идентификаторҳо: 'иҷорагир _ ид', 'brand _ id', 'минтақа', 'player _ id', 'session _ id', 'round _ id', 'bet _ id', 'solution _ id'. Ҳама - сатр, дар миқёси ҷаҳонӣ беназир (UUID/KSUID/Snowflake) ба гузоришҳо ва рӯйдодҳо дохил карда мешаванд.

4) Шартномаҳои API: дархостҳо, ҷавобҳо, хатогиҳо

4. 1 Иҷозат ва амният

OAuth2 эътимодномаи муштарӣ ё MTLS + Имзои баданро дархост кунед (HMAC/EDDSA).

Скупы вида: 'гарав: навиштан', 'ҳисоббаробаркунӣ: навиштан', 'ҷаласаҳо: хондан', 'чорабиниҳо: нашр кардан'.

Сарлавҳаҳо дар ҳар як дархост талаб карда мешаванд:

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

4. 2 Намунаҳои нуқтаҳои ниҳоӣ

Эҷоди сеанс


POST/v1/ҷаласаҳо
{
"player_id":"p_19f3," "game_id":"studio:slot_forge_02," асъор ":" EUR "," locale ":" de-DE "," маҳдудиятҳо ": {" max _ bet ": 5," rg _ flags ": [" self _ explosion ": дурӯғ]}
}
→ 201
{
"session_id":"s_456," "expires_at":"2025-10-23T19:10:00Z"
}

Иҷозати нарх (нигоҳ доштан)


POST/v1/гарав/ваколатдор
Сарлавҳаҳо: Калиди X-Idempotency: bet_r_8c12_1
{
"session_id":"s_456," "bet_id":"b_001," "round_id":"r_8c12," "маблағ ": {" маблағ": 2. 00, "асъор":" EUR"}
}
→ 200 {"статус ": "ваколатдор"," hold _ id":" h _ zz1"}

Ҳисоббаробаркунӣ


POST/v1/гарав/ҳал
Сарлавҳаҳо: Калиди X-Idempotency: settle_r_8c12_1
{
"bet_id":"b_001," "round_id":"r_8c12," бурд ": {" маблағ ": 14. 60, "асъор":" EUR"}, "bonus_state":{"in_bonus":true,"freespins_left":7}
}
→ 200 {"статус ": "ҳисоб карда шудааст ", "ҳисоббаробаркунӣ _ ид":" st _ 77"}

4. 3 Хатогӣ (модели ягона)

'code': mashinnoe imya ('RG _ BLOCK', 'LIMIT _ EXCESTED', 'DUPLICATE', 'IDEMPOTENCY _ MISMATCH', 'INVALID _ STATE ATE', ',' AAUTH H _ FAAAAFAILEVED ED.

'message': мухтасар барои шахс.

'retryable': 'дуруст/дурӯғ'.

'trace _ id': ҷустуҷӯи журналҳо.

Намуна:


409 НИЗОЪ
{
"рамз ": "DUPLICATE", "паём":" Бет аллакай бо миқдори дигар ваколатдор шудааст", "бознишаста": дурӯғ, "trace_id":"tr_a1b2c3"
}

5) Автобус ва схемаҳои ҳодиса

5. 1 Мавзӯъҳои асосӣ

'плеер. ба қайд гирифта ',' сессия. оғоз ёфт	ба охир расид '
'бет. ваколатдор	маскуншуда
'bonus. дода шудааст	истеъмол карда мешавад
'wager. пешрафт. навсозӣ '
'jackpot. саҳм	triggered
'rg. лимит. зад ',' rg. reality_check'
'wallet. дебет. ',' ҳамён. кредит. '

5. 2 Схемаи чорабинӣ (Avro/JSON Schema)

json
{
"event_id":"uuid," "event_type":"bet. ҳал," "occurred_at":"2025-10-23T16:21:05Z," "tenant_id":"brand-7," "минтақа":" ИА", "player_id":"p_19f3," "trace_id":"tr_a1b2c3," "сарборӣ": {
"round_id":"r_8c12," "Бет ": {"маблағ": 1. 00, "асъор":" EUR"}, "win ": {"маблағ": 14. 60, "асъор":" EUR"} ", in_bonus":true
}, "idempotency_key":"bet_r_8c12_1," "schema_version":"1. 2. 0"
}

Қоидаҳо: эволютсияи схемаҳои ба қафо мувофиқ, сабти ном + санҷишҳои шартнома.

6) Нусхаи API: стратегияҳо ва қоидаҳо

6. 1 Версияро дар куҷо нигоҳ доштан мумкин аст

Нусхаи роҳ: '/v1/... '(танҳо кэш/масир).

Нусхаи сарлавҳа: 'Қабул кунед: барнома/внд. платформа. api + json; версия = 1. 2`.

Ҳодисаҳо: 'schema _ version' дар соҳаи ҳодиса + сабти ном.

Амал: роҳ барои HTTP, schema_version барои чорабиниҳо, парчамҳо барои қобилияти нуқта.

6. 2 Semver ва тағир додани намудҳо

PATCH (minor) - ҷойгиркунии баръакс: майдонҳои нави ихтиёрӣ, нуқтаҳои нав, намудҳои нави чорабиниҳо.

MAJOR - шикастан: тағир додани майдонҳо, тағир додани семантика, нест кардан. Иҷозат дода мешавад, танҳо тавассути '/vn/' -и нав ва фарсудашавии кӯҳна.

6. 3 Шартномаҳои устувор (ки вайрон карда намешаванд)

Номҳо ва намудҳои майдонҳои мушаххаскунии калидҳо ('_ id', 'idempotency _ key').

Модели пулӣ ('маблағ/асъор', дақиқ).

Семантикаи вазъ ('ваколатдор', 'ҳисобшуда', 'гумшуда' ва ғайра).

Идемпотенсия: рафтори такрорӣ ба таври қатъӣ муайян карда мешавад.

7) Мутобиқат ва таҳаввулот

7. 1 Илова (бехатар)

Майдонҳои нави ихтиёрӣ бо пешфарз.

Рӯйдодҳои нав/нуқтаҳои ниҳоӣ бе тағир додани ҷойҳои мавҷуда.

Тамдиди enum бо таназзул дар 'номаълум'.

7. 2 Тағйирот (хатарнок)

Намуди майдонро тағйир диҳед (рақам → хат).

ихтиёрӣ → лозим аст.

Тағир додани мантиқи тиҷорат ('пеш аз' иҷозат додан 'ҳал кунед').

→ ба версияи нави асосӣ ва роҳнамои муҳоҷират ниёз дорад.

7. 3 Фарсудашавӣ

Майдон/нуқтаи ниҳоӣ бо 'deprecated _ аз: 1 қайд карда шудааст. 7 ',' хориҷ карда шуд _ дар: 2. 0`.

Иртибот: қайдҳои нашр, бюллетен, сарлавҳаҳои амортизатсия ('Ғуруби офтоб', 'Амортизатсия').

Пайгирии истифодаи роҳҳои "кӯҳна" барои огоҳиномаҳои шарики фаъол.

8) Номутобиқатӣ ва пайдарҳамӣ

Сарлавҳаи 'X-Idempotency-Key' барои ҳамаи амалиётҳои сабт лозим аст.

Семантика: такрор бо ҳамон калид → ҳамон натиҷа (200 бо ҳамон бадан).

Калидҳо ба таркиби параметрҳо пайвастанд (масалан, 'bet _ id + миқдор').

Sagas оид ба равандҳои дароз: 'иҷозат диҳед → ӯҳдадор/қулф → ҳал кардан → қарз'; ҷуброн - рӯйдодҳои "бозгашт".

9) Пагинатсия, филтрҳо, навъбандӣ

Пагинатсияи курсор (ба таври қатъӣ 'саҳифа/лимит' барои риштаҳои калон).

Муттаҳидшавӣ: '? курсор =... & лимит = 200 & фармоиш = asc '.

Дар ҷавоб: 'next _ cursor', 'has _ more'.

Филтрҳо: бо мурури замон ('happened _ at _ from/to'), 'иҷорагир _ ид', 'game _ id', 'status'.

10) Маҳалҳо, асъорҳо, будубоши маълумот

Асъор дар ISO-4217; саҳеҳӣ дар нақша ('миқёс'), ҳисобҳо - дар воҳидҳои хурд (сент) нигоҳ дошта мешаванд.

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

Дар ҳар як дархост - 'минтақа'; PII ва амалиёти нақдӣ аз минтақаҳо убур намекунанд.

Ниқобҳои PII ва RLS дар намоишҳои BI.

11) Риоя ва маҳдудиятҳо

Сарлавҳаҳои зарурӣ: 'X-Trace-Id', 'X-Provider-Id', робита бо рӯйдодҳо.

Нишондиҳандаҳо: таъхири p50/p95/p99, сатҳи хатогӣ (аз рӯи кодҳо), гузариш, ақибмонии навбат (барои рӯйдодҳо).

Ҳудуди нарх: барои як провайдер/барои як бренд; ҷавобҳо аз 'Retry-After'.

Аудити WORM аз тағироти интиқодӣ (маҳдудиятҳо, ҳавзҳои RTP, формулаҳои jackpot).

12) Озмоиш ва сифати шартномаҳо

Озмоишҳои шартномавӣ (Pact/дигарон): провайдер ↔ платформа ↔ истеъмолкунандагони чорабиниҳо.

Сарборӣ: "тӯфон" -и нархҳо/нуқтаҳои аҳолинишин; ҳадафҳои p95.

Ҳолатҳои бетартибӣ: таҳвили дукарата, фармоишӣ, таъхири ҳамён.

Sandbox '/sandbox 'бо пулҳои бардурӯғ ва озмоиши' player _ id '.

13) SDK, генераторҳо ва ҳуҷҷатҳо

Насли Open

Намунаҳои рамзӣ барои 'иҷозат додан/ҳал кардан/баргардонидан', бознигарӣ ва коркарди хатогиҳо.

Нуқтаи зинда бо намунаҳои дархост/посух (curl + JSON), коллексияи Postman/Insomnia.

Changelog бо намудҳои тағирот ва тамғакоғазҳои мутобиқат.

14) Харитаи роҳи муҳоҷират (мисол)

1. v1. 6 → v1 нест. 7 (ноболиғ) майдони 'bonus _ state' -ро барои 'ҳал кардан' (ихтиёрӣ) илова кард.

2. v1. Эълони x EOL: барои 6 моҳ - ҳарф + 'Deprecation' сарлавҳа + панели истифода.

3. v2 нест. 0 (major): инфиродӣ 'wallet. ӯҳдадор шавед '(қаблан номуайян), майдони нави' ҳисоббаробаркунӣ 'лозим аст.

4. Дастури муҳоҷират: харитасозии саҳроӣ, ҷадвал, фихфлаги "навиштани дукарата" (нашри параллелии рӯйдодҳои 'v1 '/' v2').

5. Ғуруби офтоб v1: бастани ҳамгироии нав, танҳо барои истисноҳои SLA.

15) Рӯйхати санҷишҳо

Барои меъморони платформа

Луғати ягонаи субъектҳои домейн ва инвариантҳо мавҷуд аст.
Кушодани API/Async .API + Феҳристи схема, семвер, раванди коҳишҳо.
Номутобиқатӣ дар ҳама амалиётҳои навиштан; калидҳо ҳуҷҷатгузорӣ карда мешаванд.
Модели хатогӣ ва рамзҳои ягона.
Sagas ва outbox/CDC оид ба роҳҳои пулӣ.
Меъёри маҳдудиятҳо, мушоҳида, аудити WORM.
Санҷишҳои сандбокс ва шартномавӣ барои шарикон дастрасанд.
Ҷойгиркунии маълумот ва RLS/ниқоб.

Барои провайдер

Ман ҳамеша 'X-Trace-Id' ва 'X-Idempotency-Key' -ро мефиристам.
Ман такрори дархостро бехатар иҷро мекунам; Ман дучанд эҷод намекунам.
Коркарди 'Амортизатсия/Ғуруби офтоб' ва хондани Changelog.
Ман чорабиниҳоро мувофиқи схемаҳои сабти ном нашр мекунам/мехонам; Ман версияро нигоҳ медорам.
Ман дар канори худ дубора/бозгашт ва такрорӣ дорам.

16) Анти-намунаҳо (парчамҳои сурх)

Таҳрири дастии тавозунҳо/ҳисоббаробаркуниҳо дар пойгоҳи додаҳо.

Интишори рӯйдодҳои "гузашта" outbox/CDC.

Не idempotency → такрори пардохтҳо/дебетҳо.

Омезиши PII/пулҳои минтақаҳои гуногун бидуни аломати 'минтақа'.

"Хомӯшӣ" тағиротро бидуни версияи нав ва декларатсия вайрон мекунад.

Тавлиди дастӣ SDK (бо хусусиятҳои воқеӣ кашед).

Муҳоҷирати таркиши калон бидуни парчамҳои махсус ва навиштани рӯйдодҳои дугона.

API-и ягона на танҳо "ҷамъоварии нуқтаҳои ниҳоӣ", балки шартномаи экосистема мебошад: луғати пайваста, инвариантҳои устувори пулӣ, рӯйдодҳои санҷидашуда, қоидаҳои возеҳи мутобиқат ва коҳишҳои идорашаванда. Бо такя ба версияи семантикӣ, номутобиқатӣ, outbox/CDC, мушоҳида ва амнияти қавӣ, платформа провайдерҳоро зуд ва дарднок мепайвандад ва навсозӣ аз хатар ба реҷа табдил меёбад.