API arkaly üpjün edijileri nädip birikdirmeli: hendshake, sertifikat, sandbox

Makalanyň doly teksti

💡 18+. Material - in engineeringenerçilik-amaly, oýnamaga çagyryş däl. "Üpjün ediji" diýmek RGS/live-studiýa/jekpot/service; "platforma" astynda - PAM/gapjyk/kassa/bonuslar/RG.

1) Integrasiýa kartasy: arzadan önümçilige çenli

Tapgyrlar:

1. Pressail we Due Diligence: hukuk barlaglary, geo/ygtyýarnamalar, mazmunyň laýyklygy we RG-syýasatçysy.

2. Hendşeýk we howpsuzlyk: sandbox-girelgeleri bermek, açarlary alyş-çalyş etmek (mTLS/HMAC), Schema Registry-de hasaba alynmak.

3. Tehniki dizaýn: domen modelini (sessions/bets/settlements/events), idempotentligi, ýalňyşlyk kodlaryny tassyklaýarys.

4. Sandbox integrasiýasy: gapjyk/PSP/RG emulýatorlary, synag oýunçylary, "ýagyş" we goşa ssenariler.

5. Sertifikatlaşdyrmak: hökmany synaglaryň geçmegi, teswirnamalaryň, ýükleriň we bulam-bujarlygyň goly.

6. Staging/UAT: hakyky pulsyz söweş gapma-garşylyklary, kanarya traffigi.

7. Go-Live: açarlar kompaniýasy, fiç baýdaklaryň goşulmagy, SLO gözegçiligi, wakadan soňky taýýarlyk.

2) Hendşeýk: tassyklamak, ygtyýarlandyrmak, yzarlamak

2. 1 Syrlary we satyn alyşlary alyşmak

mTLS (per brand/region şahadatnamalary) we/ýa-da OAuth2 Client Credentials.

HMAC/EdDSA (non-repudiation goşýar) haýyşnamanyň bedeniniň goly.

Скоупы: `sessions:write`, `bets:write`, `settlements:write`, `events:publish`.

2. 2 Hökmany sözbaşylar

'X-Trace-Id' - geçip barýan ýol.

`X-Brand-Id`, `X-Region`, `X-Provider-Id`.

'X-Idempotency-Key' - ähli write-amallar üçin.

2. 3 Saglyk barlagy (koda çenli)


GET /health
→ 200 {"status":"ok","version":"1. 7. 2","time":"2025-10-23T10:00:00Z"}

3) Sandbox: ol ýerde näme bar we ony nädip ulanmaly

Gurşawyň düzümi:

Gapjyk emulýatory ('/wallet/debit	credit	rollback ').
RG-huki ('/rg/check ',' rg. limit. hit ') we synag profilleri (öz-özüni aýyrmak/çäklendirmeler).
Galp agregator/goşantlar/triggerler üçin jekpot.
Galp KYC/AML jogaplary (allow/deny/pending).
Synag topikleri we Schema registry bilen wakalaryň tekeri (Kafka/Pulsar).

Hakykat bilen sazlaşyk:

Şemalaryň we rate limits-iň şuňa meňzeş wersiýalary.
Taým-skyu, eltip bermek jübüti, out-of-order - emulýasiýa düwmeleri bilen gurlan.

Synag oýunçylarynyň/walýutalaryň toplumy:


p_demo_1 (EUR), p_demo_2 (USD), p_blocked_rg (denied), p_low_balance

4) Çeşme modeli we iň az şertnama

4. 1 Sessiýany döretmek


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 Stawkany ygtyýarlandyrmak (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 Settlment (tapgyryň netijesi)


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 Ýalňyşlyklar (ýekeje shema)


409
{"code":"DUPLICATE","message":"Bet already authorized","retryable":false,"trace_id":"tr_a1b2"}

5) Wakalar we shemalar: onsuz sertifikatdan geçip bilmersiňiz

Esasy topikler:

`session. started	ended`, `bet. authorized	settled	rolled_back`, `bonus. issued	consumed`, `wager. progress. updated`, `wallet. debit.`, `wallet. credit.`, `rg. limit. hit`, `rg. reality_check`.

Mysal üçin Euro/JSON Shema (bölek '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"
}

Düzgünler: backward-compatible ewolýusiýa, "dublikatlar we giç wakalar" synagy, partiýa 'tenant _ id/player _ id'.

6) Integrasiýa şahadatnamasy: nämäni barlaýarlar

6. 1 Funksional ssenariýalar (iň az)

Soragyň gaýtalanmagy 'authorize/settle' şol bir 'X-Idempotency-Key' → şol bir jogap.

Out-of-order: 'authorize' → dogry ret edildi.

Gapjyk/tor ýykylanda Rollback zynjyrlary.

RG-aýaklary: öz-özüni aýyrmak/ýitgiler/wagt çäkleri → stawkany gadagan etmek.

Bonus/töleýji: oýun görnüşi boýunça goýum, max bet, möhletler.

6. 2 Ýük

p95 'bet/settle' býudjetlerde (mysal üçin '<200-300 ms'), retraýlaryň "tupanlarynyň" ýoklugy.

Wakalaryň akymlary BI ≤ 5 minuda ýetýär.

6. 3 Bulam-bujarlyk

Eltip bermek, outbox/CDC gijikdirmek, sebitiň "zibili", bölekleýin düzüliş.

6. 4 Netijeler boýunça resminamalar

Taýmkodlar bilen synaglaryň teswirnamasy/trace-id.

SLO hasabaty (latency/error/lag).

Howpsuzlyk hasabaty (açarlar, aýlawlar, elýeterlilik, Vault/HSM).

7) Wersiýa we migrasiýa

HTTP: '/v1/... 'ýolda, wakalar:' schema _ version 'bedende.

SemVer: minor - goşmaça meýdanlary goşmak; major - diňe täze prefiks '/v2/' arkaly.

Deprecation headers: 'Deprecation', 'Sunset', dashbordda ulanmak aýnasy.

Fiç-baýdaklar: geçiş döwründe wakalaryň "goşa haty" ('v1' we 'v2').

8) Howpsuzlyk we laýyklyk

mTLS + S2S gollary, gysga ömürli bellikler, çäkli satyn alyşlar.

Zero-trust: tor syýasatlary, per-brand/region açarlary.

Data residency & PII: sebitde saklamak we ýazmak; RLS/gizlemek.

WORM-audit: çäklendirmeleri, RTP profillerini, jekpot konfigurasiýalaryny üýtgetmek.

RG/AML: stawkada/tölegde sinhron duralga signallary; SAR/STR hasabat.

9) Önüme çykmak: işe girizmegiň gözegçilik sanawy

Traffigi açmazdan öň

Sandbox syrlaryny aýlamak → prod-açarlar.

p95/p99, error-rate, queue-lag, settle-lag dashbordlary girizildi.

SLO alertleri: breach by latency/error/lag, flow 'DUPLICATE/IDEMPOTENCY _ MISMATCH'.

DR-meýilnama: RPO ≤ 5 minut, RTO ≤ 30 minut; "gyzyl düwme" - täze sessiýalary duruzmak.

Kanareýka

1-5% tomaşaçylar/oýunlar/geo; SLO bozulanda awtomatiki rollback.

Post-gözegçilik 24-72 sagat, ledjeriň/hasabatlaryň barlagy.

10) Anti-pattern (gyzyl baýdaklar)

Outbox/CDC-den aýlanyp, wakalary çap etmek.

Write-amallarda 'X-Idempotency-Key' -iň ýoklugy.

DB-daky balanslaryň/settlementleriň el bilen düzedilmegi.

Birnäçe markalara/sebitlere birmeňzeş açarlar.

BI we OLTP söweş maglumatlarynyň üstünden kadalaşdyryjy hasabatlar.

Nol pese gaçmak: üpjün edijiniň ýykylmagy gapjygy/platformany ýykýar.

11) Çek-listler

Üpjün ediji üçin

Iberýärin 'X-Trace-Id' we 'X-Idempotency-Key' hemişe.
Şol bir açar bilen gaýtalanmagy saklaýaryn.
Registry-den shemalar boýunça wakalary çap edýärin; saklaýaryn 'schema _ version'.
Backoff we de-duplikasiýa bilen retralar amala aşyryldy.
RG-aýaklary we bonus çäklendirmeleri hakyky wagtda berjaý edilýär.
Elýeterliligi we syrlary - per brand/region, aýlanyş sazlandy.

Platforma üçin

Ähli pul ýollarynda Outbox/CDC; end-to-end.
SLO-daşbordlar: p95/99, error-rate, queue-lag, settle-lag.
Deprecation/Sunset-prosesi, migrasiýadaky wakalaryň goşa haty.
DR/xaoc-maşklar, hadysalary dolandyrmak we postmortemler.
Zaýalanma usullary: 'no new sessions', mahabaty/jekpoty öçürmek.

12) "Iň az" integrasiýa pleýbukynyň mysaly (TL; DR)

1. NDA/şertnama gol çekiň → sandbox-elýeterliligi we shemalary bermek.

2. mTLS/HMAC şahadatnamalaryny alyş-çalyş etmek; 'provider _ id' başla.

3. Iň kiçi endpointleri utgaşdyrmak: 'sessions', 'bets/authorize', 'bets/settle', 'rollback'.

4. "Sandbox" we "Registry" -e birikdiriň; funksional/bulam-bujarlygy ýok etmek.

5. Sertifikat protokolyny tabşyryň: logi, trace-id, SLO hasabaty.

6. Açarlary proba geçiriň, kanareýkany açyň, SLO-ny synlaň.

7. Neşirden soňky metrikleri we "sapaklary" changelog-da ýazga alyň.

Üpjün edijiniň üstünlikli birikdirilmegi diňe bir API däl, eýsem dolandyrylýan prosesdir: howpsuz hendşeýk, hakyky sandbox, berk sertifikat, gözegçilik we anyk laýyklyk düzgünleri. Beýan edilen üýtgeşikliklere (idempotentlik, outbox/CDC, RG/AML-aýaklar, SLO we DR) eýerip, integrasiýany çaltlaşdyrýarsyňyz, pul hadysalaryndan gaça durýarsyňyz we oýunçylar, düzgünleşdirijiler we işewürler üçin garaşylmadyk ýagdaýda öňünden aýdylýan neşirleri alarsyňyz.