Backend səviyyəsində promo və bonusların idarə edilməsi

Məqalənin tam mətni

💡 18+. Platformalar/operatorlar və provayderlər üçün mühəndis-praktik material. Oyuna çağırış deyil. «Cüzdan» dedikdə ACID zəmanətləri olan Ledger/Wallet, «bonuslar» dedikdə isə oyunun balansına və şərtlərinə təsir edən promosyonlar nəzərdə tutulur.

1) Niyə promo ayrı backend

Pul invariantları. Bonus ≠ «əlavə balans»: şərtləri olan bir müqavilədir (Veycer, oyun əmanəti, maksimum bahis/uduş).

Dəyişmə sürəti. Marketinq komandaları hər gün kampaniyalar buraxırlar - bəyannamə qaydaları və geri dönüş lazımdır.

Anti-sui-istifadə/komplayens. KYC/RG/AML, velocity, seqmentasiya, bahalı offerlərə «dörd göz» daşları.

Müşahidə və hesabat. SLO, promo dəyəri, GGR/NGR/LTV təsir.

Prinsip: promo nüvəsi öz status maşınları ilə ayrı bir xidmətdir və pul yalnız cüzdan vasitəsilə, idempotent vasitəsilə hərəkət edir.

2) Bonusların tipologiyası və invariantları

Deposit match (100% - X): depozit capture sonra hesablanır, X × veycer.

Cashback (Lost-back): Vaxt/oyun pəncərəsi ilə hesablanır, sticky/non-sticky ola bilər.

Free Spins/Free Bets: spin/bahis qiyməti ilə kuponlar/tokenlər, sabit RTP hovuzu.

Kvestlər/missiyalar: tapşırıq → tərəqqi → mükafat.

Turnirlər/uçuş tədbirləri: hadisələrin töhfəsi, reytinq, mükafat.

İnvariantlar:

Sticky: şərtlər yerinə yetirilməzdən əvvəl çıxarıla bilməz.
Max bet/Max win: bonus vəsaitlərindən bahis/ödəniş limitləri.
Contribution: oyunlara töhfə (məsələn, slots = 100%, live = 10%).
Expiry: bonus müddəti və vajer pəncərələri.

3) Bonus xidmətinin arxitekturası


Admin (kampaniyalar/qaydalar) ─ Promo API ─ Rules Engine/Eligibility
│
─ Bonus Ledger (offerlərin vəziyyəti)
─ Wagering Engine (tərəqqi)
─ Anti-Abuse (limitlər/frod/velocity)
└─Outbox (events) ─Kafka/Pulsar ─BI/DWH/CRM

Wallet/Ledger── Idempotent Commands ───┘

Rules Engine - deklarativ şərtlər (seqmentlər, geo/lisenziya, kanallar, KYC/RG).

Wagering Engine - 'bet. settled`/`wallet. debit	credit`.
Bonus Ledger - bonus/missiyaların vəziyyətinə görə həqiqət mənbəyidir.
Outbox/CDC - etibarlı nəşr 'bonus. issued	progress. updated

4) Məlumat modeli (sadələşdirilmiş)

`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) Status maşınlar və dastanlar

5. 1 Veriliş (issue) - dastan

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

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

3. wallet. credit [bonus] (idempotent; sticky - bonus alt balansına)

4. activate (status=`active`)

5. emit `bonus. issued`

Rollback: 3 addım düşdükdə → 'grant. cancel '+ hadisə' bonus. revoked`.

5. 2 Veycer Tərəqqi

Na 'bet. settled 'əmanət =' stake _ minor contribution_pct' hesablamaq (və ya win/loss qaydaları).

'wager _ progress' atom yeniləmək; 100% -ə çatdıqda - 'complete'.

5. 3 Tamamlama (consume)

complete → `wallet. convert_bonus_to_cash' (qeyri-sticky) və ya çıxarılması məhdudiyyətləri aradan qaldırılması.

emit `bonus. consumed`.

5. 4 Sona çatması/geri çağırılması

'expires _ at' və ya frod qaydasına görə → 'revoke' (idempotent), siyasətə görə kompensasiya mümkündür.

6) Cüzdan müqavilələri (yalnız API vasitəsilə, həmişə idempotent)

Bonus hesabla


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"}

Şərtlər yerinə yetirildikdən sonra cache çevirmək


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"}

Yoxlama max bet/max win - RGS/Wallet Guard tərəfində:

'bets. authorize 'kodu ilə rədd edilir' BONUS _ MAX _ BET _ EXCEEDED '.

7) API promo xidməti (etalonlar)

Yeni offer (admin)


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 (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"}

Veycer Tərəqqi (read)


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

Ləğv et/ləğv et


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

Bütün write-zənglər 'X-Idempotency-Key' və 'X-Trace-Id' ilə.

8) Anti-sui-istifadə və uyğunluq

Velocity limitləri: ekstradisiyalar/konversiyalar/depozit cəhdləri (Redis counters + TTL + Lua).

Dedup trigger: bir depozit → qaydasına görə bir qrant.

Seqmentasiya və RG: self-excluded/limit istisna; per brand/region lisenziyaları.

Offer münaqişə bloku: eyni zamanda yalnız bir welcome bonusu aktivdir; prioritetlər.

Anomaliya detektoru: çoxsaylı hesablar/cihazlar/ASN, veycerin sürətli «sıfırlanması».

Böyük qrantlar və əl düzəlişləri üçün «Dörd göz».

WORM-audit qaydaları/qrantlar/dönüşüm bütün dəyişikliklər.

9) Müşahidə, metrika və SLO

SLO (göstəricilər):

`grant. issue p95` (issue→credited) ≤ 300–500 мс.
Yeniləmə 'wager _ progress p95' ≤ andan etibarən 200 ms 'bet. settled`.
Hadisələr 'bonus.' baş verənlərdən p95 ≤ 2 dəq şində.
«İtirilmiş/dublyaj edilmiş qrantlar/konversiyalar» = 0.

Metriklər:

Rate/latency по `issue/convert/revoke`, error-rate (business/4xx/5xx), `IDEMPOTENCY_MISMATCH`.
Veycer dönüşümü, orta 'time-to-complete', vaxtı keçmiş paydır.
Promo qiyməti: 'promo _ cost' (minor) və 'promo _ roi' kohortlarda.
Anti-sui-istifadə: velocity işə salınması, max bet/win.

Trace: OpenTelemetry 'trigger → grant → wallet. credit → progress. update → convert`.

10) RGS/oyunlar ilə inteqrasiya

Free Spins/Free Bets kuponları - 'entitlements' API vasitəsilə: tokenlərin verilməsi, rentaymda silinməsi, istifadə üçün telemetriya.

Max bet/win - 'bets qaydaları. authorize` и `bets. settle`; 'BONUS _ RULE _ VIOLATION' kodlarını qaytarın.

Contribution - 'bet' səviyyəsində sxem. settled '(' game _ type/provider _ id '), sxemlərin versiyası.

11) DWH/BI və hesabatlar

Outbox hadisələr → Lake (bronze) → Silver (dedup, SCD2) → Gold vitrinlər:

`fact_bonus_grants`, `fact_wager_progress`, `fact_bonus_cost`, `fact_promo_roi`.
SLA təravət: Silver ≤ 15 dəq, Gold ≤ 30-60 dəq.
Panellər: offerlər/seqmentlər üzrə konvertasiya, time-to-complete, oyunlara töhfə, sui-istifadə hadisələri.

12) Təhlükəsizlik və rezidentlik

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

Açarlar/tokenlər - per brand/region, qısamüddətli; Vault/HSM sirləri.

PII-izolyasiya: 'player _ id' - təxəllüs; RLS по `brand/region`.

Rate limits və emissiya kvotaları; fırtına retrai qorunması.

13) Çek vərəqləri

Platforma/operator

Bütün pul əməliyyatları 'Idempotency-Key' ilə Wallet vasitəsilə gedir.
Rules/Eligibility versiyası; miqrasiya hadisələrinin «ikiqat məktubu».
Contribution sxemləri mərkəzləşdirilmiş, testlərlə örtülmüşdür.
Velocity və anti-frod daxildir; böyük məbləğdə «dörd göz».
Outbox/CDC, DLQ və idarə replay üçün 'bonus.'.
SLO-daşbordları, OpenTelemetry, WORM-audit.
ROI və Complayance (RG/AML) üçün DWH-vitrinlər.

İnteqrasiya (RGS/cüzdan/CRM)

max bet/win yoxlamaq; biznes səhv kodunu qaytarıram.
'trace _ id' və 'idempotency _ key' atıram.
Tetikleyici dedup və çatdırılma zəmanəti (webhooks imzalanmışdır).

14) Qırmızı bayraqlar (anti-nümunələr)

Bonusun «əl ilə» birbaşa balansa hesablanması, Wallet-ı keçmədən.

İdempotentliyin olmaması → ikiqat qrantlar/dönüşümlər.

Wedger 'bet sayılır. placed ', bet nəticələrinə görə deyil. settled`.

Heç bir contribution sxemləri və ya provayder kodunda «tikilmiş».

Ziddiyyətli offerlər eyni vaxtda aktivləşdirilir.

Heç bir velocity/anti-frod və WORM audit.

'bonus.' hadisələri outbox/CDC-dən yan keçərək dərc olunur.

Promo göstəriciləri Ledger/BI ilə üst-üstə düşmür (ROI vitrinləri yoxdur).

15) Yekun

Etibarlı backend promo müqavilələr və invariantlardır, «balans əlavə etmək» deyil. Qaydaları puldan ayırır, faktiki nəticələr üzrə irəliləyiş hesab edir, idempotentliyə və müşahidə olunmağa zəmanət verir, sui-qəsddən qoruyur və uyğunluq təmin edir. Belə bir nüvə ilə marketinq sürətlə hərəkət edir, oyunçu dürüst şərtləri görür və maliyyə və tənzimləyicilər hər bir offerin dəyərinin və təsirinin dəqiq mənzərəsini əldə edirlər.