Promo va bonuslarni backend darajasida boshqarish

Maqolaning to’liq matni

💡 18+. Platformalar/operatorlar va provaydyerlar uchun muhandislik-amaliy material. O’yinga chaqirish emas. «Hamyon» deganda ACID kafolatli Ledger/Wallet, «bonuslar» deganda esa oʻyin balansi va sharoitlariga taʼsir etuvchi promoferlar tushuniladi.

1) Nega promolarni alohida backend-ga olib chiqish kerak

Pul invariantlari. Bonus ≠ «qo’shilgan balans»: bu shartlari bo’lgan kontrakt (veyjer, o’yinlar bo’yicha omonat, maksimal stavka/yutuq).

Oʻzgarish tezligi. Marketing jamoalari har kuni kampaniyalar chiqaradi - deklarativ qoidalar va orqaga qaytish kerak.

Anti-abyuz/komplayens. KYC/RG/AML, velocity, segmentatsiya, qimmatbaho offerlarga to’rt ko’z toshlari.

Kuzatuv va hisobot. SLO, promo qiymati, GGR/NGR/LTV ga ta’siri.

Printsip: promo-yadro - o’z maqomiga ega mashinalarga ega alohida xizmat, pul esa faqat hamyon orqali, idempotent orqali harakatlanadi.

2) Bonuslar tipologiyasi va invariantlar

Deposit match (100% to X gacha): depozitning capture, veyjer X × keyin hisoblanadi.

Cashback (yo’qotish-bek): vaqt/o’yin oynasi bo’yicha hisoblanadi, sticky/non-sticky bo’lishi mumkin.

Free Spins/Free Bets: spin/stavka uchun praysli kuponlar/tokenlar, qat’iy belgilangan RTP-pool.

Kvestlar/missiyalar: vazifa → taraqqiyot → mukofot.

Turnirlar/reys-iventlar: voqealar hissasi, reyting, mukofot puli.

Invariantlar:

Sticky: shartlar bajarilgunga qadar chiqarib boʻlmaydi.
Max bet/Max win: bonus mablag’lardan stavka/to’lov limitlari.
Contribution: oʻyinlar boʻyicha hissa (masalan, slots = 100%, live = 10%).
Expiry: bonus muddati va veyjer oynasi.

3) Bonuslar xizmati arxitekturasi


Admin (kampaniyalar/qoidalar) ─ Promo API ─ Rules Engine/Eligibility
│
─ Bonus Ledger (offerlarning holati)
─ Wagering Engine (taraqqiyot)
─ Anti-Abuse (limitlar/frod/velocity)
└─Outbox (events) ─Kafka/Pulsar ─BI/DWH/CRM

Wallet/Ledger── Idempotent Commands ───┘

Rules Engine - deklarativ shartlar (segmentlar, geo/litsenziya, kanallar, KYC/RG).

Wagering Engine -’bet’dan omonatni hisoblaydi. settled`/`wallet. debit	credit`.
Bonus Ledger - bonuslar/missiyalar holati bo’yicha haqiqat manbai.
Outbox/CDC - ishonchli nashr’bonus. issued	progress. updated

4) Ma’lumotlar modeli (soddalashtirilgan holda)

`bonus_grant`

`grant_id, player_id, offer_id, type, currency, amount_minor, sticky, wager_x, max_bet_minor, max_win_minor, contribution_schema_id, status (issued	active	paused	completed	expired	revoked), issued_at, expires_at, brand_id, region, idempotency_key`

`wager_progress`

`grant_id, required_minor, contributed_minor, remaining_minor, last_update_at`

`contribution_schema`

`schema_id, rules: [{game_type:"slot", pct:100},{game_type:"live", pct:10}]`

’bonus _ ledger _ entry’ (audit)

`entry_id, grant_id, action (issue	consume	revoke	expire	adjust), amount_minor, reason, occurred_at, trace_id`

5) Maqom mashinalari va dostonlari

5. 1 Berish (issue) - saga

1. eligibility. check (segment, RG/KYC, velocity)

2. grant. create (status=`issued`)

3. wallet. credit [bonus] (idempotent; sticky - bonus sub-balansiga)

4. activate (status=`active`)

5. emit `bonus. issued`

Rollback: 3 qadamda yiqilganda →’grant. cancel’+ voqea’bonus. revoked`.

5. 2 Veyjer taraqqiyoti

Na’bet. settled’omonatni =’stake _ minor contribution_pct' deb hisoblash (yoki win/loss qoidalari bo’yicha).

’wager _ progress’ ni atom shaklida yangilash; 100% ga yetganda -’complete’.

5. 3 Yakunlash (consume)

complete → `wallet. convert_bonus_to_cash' (agar non-sticky) yoki cheklovlarni olib tashlash.

emit `bonus. consumed`.

5. 4 Tugashi/chaqirib olinishi

’expires _ at’ yoki frod qoidasi bo’yicha →’revoke’(idempotent), siyosatga muvofiq kompensatsiya qilish mumkin.

6) Hamyon bilan kontraktlar (faqat API orqali, har doim idempotent)

Bonusni hisoblash


POST /v1/wallet/credit
Headers: X-Idempotency-Key: bonus_grant_123
{
"player_id":"p_001",  "amount":{"minor_units":100000,"currency":"EUR"},  "balance_type":"bonus",  "reference":{"grant_id":"gr_123","offer_id":"of_777"}
}
→ 200 {"status":"credited","entry_id":"e_9001"}

Shartlar bajarilgandan keyin keshga konvertatsiya qilish


POST /v1/wallet/convert
Headers: X-Idempotency-Key: bonus_convert_gr_123
{
"player_id":"p_001",  "from_balance":"bonus",  "to_balance":"cash",  "amount_minor":100000,  "reference":{"grant_id":"gr_123"}
}
→ 200 {"status":"converted","entry_id":"e_9010"}

Tekshirish max bet/max win - RGS/Wallet Guard tomonida:

’bets. authorize’BONUS _ MAX _ BET _ EXCEEDED’kodi bilan rad etiladi.

7) promo servisi API (etalonlar)

Offer yaratish


POST /v1/offers
{
"name":"Welcome 100% up to 100€",  "type":"deposit_match",  "params":{"match_pct":100,"cap_minor":10000,"wager_x":20,"sticky":true,       "max_bet_minor":200,"max_win_minor":50000,"contribution_schema_id":"c_slot100_live10"},  "eligibility":{"brands":["A"],"regions":["EU"],"segment":"new_depositors"},  "schedule":{"start":"2025-10-20T00:00:00Z","end":"2025-11-30T23:59:59Z"}
}
→ 201 {"offer_id":"of_777"}

Bonus berish (runtime)


POST /v1/bonus/grants
Headers: X-Idempotency-Key: grant_p001_of777
{
"player_id":"p_001","offer_id":"of_777","trigger":"deposit_captured","amount_minor":10000
}
→ 200 {"grant_id":"gr_123","status":"active"}

Veyjer taraqqiyoti (o’qish)


GET /v1/bonus/grants/gr_123/progress
→ 200 {"required_minor":200000,"contributed_minor":45000,"remaining_minor":155000,"pct":0. 225}

Bekor qilish/qaytarib olish


POST /v1/bonus/grants/gr_123/revoke
Headers: X-Idempotency-Key: revoke_gr_123
{ "reason":"fraud_velocity" }
→ 200 {"status":"revoked"}

Barcha write-qo’ng’iroqlar’X-Idempotency-Key’va’X-Trace-Id’.

8) Anti-abyuz va komplayens

Velocity limitlari: depozit berish/konversiyalar/urinishlar (Redis counters + TTL + Lua).

Dedup triggerlar: bitta depozit → qoidaga ko’ra bitta grant.

Segmentatsiya va RG: self-excluded/limitli; per brand/region litsenziyasi.

Offerlar toʻqnashuvi bloki: bir vaqtning oʻzida faqat bitta welcome bonus aktiv; ustuvorliklar.

Anomaliyalar detektori: bir nechta akkauntlar/qurilmalar/ASN, tezkor «nollash».

Yirik grantlar va qo’lda tuzatishlar kiritish bo’yicha «To’rt ko’z».

WORM-audit barcha o’zgarishlar qoidalari/grantlar/konversiyalar.

9) Kuzatish, metrika va SLO

SLO (taxminlar):

`grant. issue p95` (issue→credited) ≤ 300–500 мс.
Yangilash’wager _ progress p95’≤ 200 ms vaqtdan boshlab’bet. settled`.
Hodisalar’bonus.’ro’y bergan voqeadan p95 ≤ 2 min.
«Yo’qotilgan/takrorlangan grantlar/konversiyalar» = 0.

Metriklar:

Rate/latency по `issue/convert/revoke`, error-rate (business/4xx/5xx), `IDEMPOTENCY_MISMATCH`.
Veyjer konvertatsiyasi, o’rtacha’time-to-complete’, muddati o’tgan ulushi.
Promo qiymati:’promo _ cost’(minor) va’promo _ roi’kogortlarda.
Anti-abyuz: ishga tushirish velocity, chetlatilgan max bet/win.

Treysing: OpenTelemetry’trigger → grant → wallet. credit → progress. update → convert`.

10) RGS/o’yinlar bilan integratsiya

Free Spins/Free Bets kuponlari -’entitlements’API orqali: tokenlarni berish, rantaymda hisobdan chiqarish, foydalanish bo’yicha telemetriya.

Max bet/win - qoidalar v’bets. authorize` и `bets. settle`; ’BONUS _ RULE _ VIOLATION’ kodlarini qaytarish.

Contribution -’bet’darajasidagi sxema. settled’(’game _ type/provider _ id’), sxemalar versiyasi.

11) DWH/BI va hisobotlar

Outbox voqealar → Lake (bronze) → Silver (dedup, SCD2) → Gold vitrinalar:

`fact_bonus_grants`, `fact_wager_progress`, `fact_bonus_cost`, `fact_promo_roi`.
SLA yangiligi: Silver ≤ 15 min, Gold ≤ 30-60 min.
Panellar: offerlar/segmentlar bo’yicha konvertatsiya, time-to-complete, o’yinlar bo’yicha hissa qo’shish, buzuq hodisalar.

12) Xavfsizlik va rezidentlik

mTLS + OAuth2 CC; scope’ы `promo:issue`, `promo:convert`, `promo:revoke`.

Kalit/tokenlar - per brand/region, qisqacha; Vault/HSM sirlari.

PII-izolyatsiya:’player _ id’- taxallusi; RLS по `brand/region`.

Rate limits va berish kvotalari; retray bo’ronlaridan himoya qilish.

13) Chek-varaqlar

Platforma/operator

Barcha pul operatsiyalari’Idempotency-Key’bilan Wallet orqali amalga oshiriladi.
Rules/Eligibility versiyalari; migratsiya voqealarini «ikki marta yozish».
Contribution sxemalari markazlashtirilgan, testlar bilan qoplangan.
Velocity va anti-frod kiritilgan; katta miqdordagi «to’rt ko’z».
Outbox/CDC, DLQ va boshqariladigan replay uchun’bonus.’.
SLO-dashbordlar, OpenTelemetry, WORM-audit.
ROI va komplayens (RG/AML) uchun DWH-vitrinalar.

Integratsiyalar (RGS/hamyon/CRM)

Tekshiraman max bet/win; xato kodini qaytaryapman.
’trace _ id’va’idempotency _ key’.
Trigger dedupi va yetkazib berish kafolatlari (webhooks imzolangan).

14) Qizil bayroqlar (anti-patternlar)

Bonusni to’g «ridan to’g» ri balansga «qo’lda» hisoblash.

Idempotentlik yo’qligi → ikki tomonlama grantlar/konversiyalar.

Veyjer’bet’deb hisoblanadi. placed’,’bet’yakunlari bo’yicha emas. settled`.

Hech qanday contribution sxemalari mavjud emas yoki ular provayder kodida «tikilgan».

Ziddiyatli offerlar bir vaqtning oʻzida faollashadi.

Velocity/anti-frod va WORM auditi yo’q.

’bonus’ hodisalari outbox/CDC’ni chetlab oʻtish orqali eʼlon qilinadi.

Promo koʻrsatkichlari Ledger/BI bilan mos kelmaydi (ROI vitrinasi yoʻq).

15) Jami

Ishonchli backend promo - bu «balansni qo’shish» emas, balki shartnomalar va invariantlar. U qoidalarni puldan ajratadi, haqiqiy natijalar bo’yicha taraqqiyotni hisobga oladi, idempotentlik va kuzatiluvchanlikni kafolatlaydi, buzilishdan himoya qiladi va komplayensni ta’minlaydi. Bunday yadro bilan marketing tez harakat qiladi, o’yinchi halol sharoitlarni ko’radi, moliya va regulyatorlar esa har bir offerning qiymati va ta’sirini aniq tasvirlaydi.