Sağlayıcılar için tek API: tasarım, sürüm, uyumluluk

Tam makale

💡 18+. Entegrasyon ve platform ekipleri için teknik malzeme. Oynamak için bir çağrı değil.

1) Neden'tek API've ne olduğu

Tek bir API, herhangi bir içerik sağlayıcısının (RGS, canlı stüdyo, jackpot, KYC/AML, bağlı kuruluşlar) aynı kurallara göre platformla iletişim kurduğu bir şartname ve bir dizi uç nokta/etkinliktir:

Birleştirilmiş kaynak modeli (oyuncular, oturumlar, bahisler, yerleşimler, bonuslar, ikramiyeler, ödemeler), ortak olay sözleşmeleri ve tanımlayıcılar, güvenlik ve geriye dönük uyumluluk standartları, entegrasyonları hızlandırmak için SDK/araçlar.

Amaç: entegrasyon süresini azaltmak, "para yollarındaki" hataları azaltmak ve öngörülebilir yükseltmeler sağlamak.

2) Tasarım ilkeleri

1. Etki alanı öncelikli. Önce sözlük ve değişmezler (oran, ayar, RG sınırları), sonra uç noktalar.

2. Varsayılan olarak uyumluluk. Herhangi bir değişiklik varsayılan olarak uyumludur; Değişiklikleri kesinlikle süreçle kırmak.

3. Idempotency her yerde. Tüm para komutları yan etkileri olmadan tekrarlanabilir.

4. Olaylar gerçeğin kaynağıdır. Operasyonlar - otobüse olaylar; Analitik veri yolunu dinler, OLTP'yi yenmez.

5. En az ayrıcalık ve sıfır güven. Belirteçler, imzalar, marka/bölgeye göre segmentasyon.

6. Gözlenebilirlik. Uçtan uca 'trace _ id', anlaşılabilir hata modeli, p95/p99 metrikleri.

3) Kaynak modeli (basitleştirilmiş)

Oyuncu: Platform tarafı oyuncu pseudo-ID, geo/currency/RG durumları.

Oturum: Sağlayıcı ile platform arasında bir kanal ('session _ id', TTL, geo/restrictions).

Bahis: bahis yetkilendirme/borç.

Uzlaşma: Yuvarlak sonuç ve kredi kazanmak.

Bonus/Bahis: Bonus/vager bakiye durumu.

Jackpot: katkılar/tetikleyiciler/ödemeler.

Olay: Değişmeyen etki alanı olayları (Kafka/analoglar).

Tanımlayıcılar: 'tenant _ id', 'brand _ id', 'region', 'player _ id', 'session _ id', 'round _ id', 'bet _ id', 'settlement _ id'. Tüm - dize, küresel olarak benzersiz (UUID/KSUID/Snowflake), günlükleri ve olaylar dahildir.

4) API sözleşmeleri: istekler, yanıtlar, hatalar

4. 1 Yetkilendirme ve güvenlik

OAuth2 İstemci Kimlik Bilgileri veya mTLS + Request Body Signature (HMAC/EdDSA).

Скоупы вида: 'bahisler: yazmak', 'yerleşimler: yazmak', 'oturumlar: okumak', 'olaylar: yayınlamak'.

Her istekte başlıklar gereklidir:

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

4. 2 Uç nokta örnekleri

Oturum oluşturma


POST/v1/oturumları
{
"player_id":"p_19f3," game_id":"studio:slot_forge_02, "para birimi": "EUR", "yerel ayar":'de-DE "," kısıtlamalar ": {" max _ bet ": 5," rg _ flags ": [" self _ exclusion ": false]}
}
→ 201
{
"session_id":"s_456," "expires_at":"2025-10-23T19:10:00Z"
}

Fiyat yetkilendirmesi (bekletme)


POST/v1/bets/authorized
Başlıklar: X-Idempotency-Key: bet_r_8c12_1
{
"session_id":"s_456," "bet_id":"b_001," "round_id":"r_8c12," miktar ": {" miktar ": 2. 00, "para birimi":" EUR"}
}
^ 200 {"durum": "yetkili", "hold _ id":'h _ zz1 "}

Yerleşim


POST/v1/bets/settle
Başlıklar: X-Idempotency-Key: settle_r_8c12_1
{
"bet_id":"b_001," round_id":"r_8c12, "win": {"miktar": 14. 60, "para birimi":" EUR"}, "bonus_state":{"in_bonus":true,"freespins_left":7}
}
^ 200 {"status ": "credited ", "settlement _ id":" st _ 77"}

4. 3 Hatalar (tek model)

'Kod': машинное имя ('RG _ BLOCK', 'LIMIT _ EXCEEDED', 'DUPLICATE', 'IDEMPOTENCY _ MISMATCH', 'INVALID _ STATE', 'AUTH _ FAILED').

'mesaj': kişi için kısa.

'tekrarlanabilir': 'doğru/yanlış'.

'trace _ id': günlükleri aramak için.

Örnek:


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

5) Olay yolu ve devreler

5. 1 Temel konular

'oyuncu. Kayıtlı ',' oturumu. Başladı	sona erdi '
'bet. Yetkili	yerleşmiş
'Bonus. yayınlanan	tüketilen
'bahis. İlerleme. güncellenmiş '
'jackpot. Katkı	tetiklendi
'rg. limit. Hit ',' rg. reality_check'
'wallet. debit. ', cüzdan. Kredi. '

5. 2 Olay Şeması (Avro/JSON Şeması)

Json
{
"event_id":"uuid," "event_type":"bet. Yerleşmiş "," occurred_at":"2025-10-23T16:21:05Z, "tenant_id":"brand-7," bölge ":" AB "," player_id":"p_19f3, "trace_id":"tr_a1b2c3," yük ": {
"round_id":"r_8c12," "bahis ": {"miktar": 1. 00, "currency":" EUR"}, "win ": {"amount": 14. 60, "para birimi":" EUR"}, "in_bonus":true
}, "idempotency_key":"bet_r_8c12_1," "schema_version":"1. 2. 0"
}

Kurallar: Şemaların geriye dönük uyumlu evrimi, kayıt + sözleşme testleri.

6) API sürümü: stratejiler ve kurallar

6. 1 Versiyonun nerede saklanacağı

Yol sürümü:'/v1/... '(sadece önbellek/rota).

Başlık sürümü: 'Accept: application/vnd. Platform. api + json; Sürüm = 1. 2`.

Olaylar: + registry olay alanında 'schema _ version'.

Uygulama: HTTP için yol, etkinlikler için schema_version, nokta yetenekleri için bayraklar içerir.

6. 2 SemVer ve değişim türleri

PATCH (minör) - ters yerleştirme: yeni isteğe bağlı alanlar, yeni uç noktalar, yeni olay türleri.

MAJOR - kırma: alanları yeniden adlandırma, semantiği değiştirme, silme. Sadece yeni'/vN/'ve eskinin tükenmesi yoluyla izin verilir.

6. 3 Kararlı sözleşmeler (bozulamaz)

Anahtar tanımlama alanlarının adları ve türleri ('_ id', 'idempotency _ key').

Parasal model ('miktar/para birimi', doğruluk).

Durum semantiği ('yetkilendirilmiş', 'kredilendirilmiş', 'kaybedilmiş', vb.).

Idempotency: Tekrarlama davranışı kesinlikle tanımlanmıştır.

7) Uyumluluk ve evrim

7. 1 Ekle (güvenli)

Varsayılanlarla yeni isteğe bağlı alanlar.

Mevcut olanları değiştirmeden yeni olaylar/bitiş noktaları.

Enum uzantısı 'bilinmeyen'de fallback ile.

7. 2 Değişiklikler (riskli)

Alan türünü (sayı - çizgi) değiştirin.

Optional gereklidir.

İş mantığının tersine çevrilmesi ('yetkilendirme'den önce' yerleşme ').

Yeni bir ana sürüm ve geçiş kılavuzu gerekir.

7. 3 Değer kaybı

Alan/uç nokta 'deseprecated _ since: 1 ile işaretlenmiştir. 7 ',' kaldırıldı _ in: 2. 0`.

İletişim: yayın notları, bülten, amortisman başlıkları ('Sunset', 'Amortisman').

Proaktif iş ortağı bildirimleri için "güncel olmayan" yolların kullanımını izleme.

8) Idempotency ve tutarlılık

'X-Idempotency-Key' başlığı tüm kayıt işlemleri için gereklidir.

Semantik: aynı anahtarla tekrarlayın - aynı sonuç (aynı gövdeyle 200).

Anahtarlar bir parametre bileşimine bağlıdır (örneğin, 'bet _ id + amount').

Uzun süreçlerde Sagas: 'yetkilendirmek> taahhüt/kilit> yerleşmek> kredi'; Tazminat - 'geri alma' olayları.

9) Sayfalama, filtreler, sıralama

İmleç tabanlı sayfalama (büyük iş parçacıkları için kesinlikle tercih edilen 'sayfa/sınır').

Birleşme: '? imleç =... & limit = 200 & order = asc '.

Yanıtta: 'next _ cursor', 'has _ more'.

Filtreler: zamana göre ('occured _ at _ from/to'), 'tenant _ id', 'game _ id', 'status'.

10) Lokaller, para birimleri, veri ikametgahı

ISO-4217 para birimi; Doğruluk şemada ('ölçek'), hesaplamalarda - küçük birimlerde (sent) saklanır.

Locali - BCP 47 ('en-GB ',' pt-BR ').

Her istekte - 'bölge'; PII ve nakit işlemleri bölgeleri geçmez.

BI vitrinlerinde PII ve RLS maskeleme.

11) Gözlemlenebilirlik ve sınırlar

Gerekli başlıklar: 'X-Trace-Id', 'X-Provider-Id', olaylarla korelasyon.

Metrikler: p50/p95/p99 gecikme, hata oranı (kodlara göre), işlem hacmi, kuyruk gecikmesi (olaylar için).

Oran limitleri: sağlayıcı başına/marka başına; 'Retry-After'dan yanıtlar.

Kritik değişikliklerin WORM denetimi (limitler, RTP havuzları, jackpot formülleri).

12) Sözleşmelerin test edilmesi ve kalitesi

Sözleşme testleri (Pakt/diğerleri): sağlayıcı ↔ platform ↔ etkinlik tüketicileri.

Yük: Oranların/yerleşimlerin "fırtına"; P95'in golleri.

Kaos vakaları: çift teslimat, sıra dışı, cüzdan gecikmeleri.

Hayali para ile sandbox'/sandbox've test 'player _ id'.

13) SDK, jeneratörler ve belgeler

OpenAPI/AsyncAPI - SDK üretimi (TypeScript/Java/Kotlin/Go/Rust).

'Yetkilendirme/yerleşme/geri alma', geri alma ve hata işleme için kod örnekleri.

İstek/yanıt örnekleri ile canlı dock (curl + JSON), Postman/Insomnia koleksiyonu.

Değişiklik türleri ve uyumluluk etiketleri ile Changelog.

14) Göç yol haritası (örnek)

1. v1. 6 - v1. 7 (küçük) 'yerleşmek' için 'bonus _ state' alanını ekledi (isteğe bağlı).

2. v1. X EOL duyurusu: 6 ay boyunca - mektup + 'Kullanımdan kaldırma' başlığı + kullanım panosu.

3. V2. 0 (majör): bireysel 'wallet. commit '(eskiden örtülü), yeni alan' settlement _ id 'gereklidir.

4. Geçiş kılavuzu: alan haritalama, zaman çizelgesi, "çift yazma'nın fichflag'ı ('v1'/' v2' olaylarının paralel yayını).

5. Sunset v1: Yalnızca SLA istisnaları için genişletilen yeni entegrasyonları engelleme.

15) Kontrol listeleri

Platform mimarları için

Alan varlıkları ve değişmezlerin tek bir sözlüğü vardır.
OpenAPI/AsyncAPI + Şema Kayıt Defteri, semver, indirimler süreci.
Tüm yazma işlemlerinde idempotency; Anahtarlar belgelenmiştir.
Tek hata modeli ve kodları.
Sagas ve giden kutusu/Para Yolları üzerinde CDC.
Hız limitleri, gözlemlenebilirlik, WORM denetimi.
Sandbox ve sözleşme testleri ortaklara açıktır.
Veri ikamet ve RLS/maskeleme.

Sağlayıcı için

Her zaman 'X-Trace-Id've' X-Idempotency-Key 'gönderirim.

İstek tekrarlarını güvenli bir şekilde işliyorum; Ben çift yaratmam.
İşleme 'Amortisman/Günbatımı've okuma Changelog.
Kayıt şemalarına göre olayları yayınlıyorum/okuyorum; Bir versiyonunu tutuyorum.
Tarafımda yeniden deneme/geri alma ve veri tekilleştirme var.

16) Anti-desenler (kırmızı bayraklar)

Veritabanındaki bakiyelerin/yerleşimlerin manuel düzenlemeleri.

Yayın olayları "geçmiş" giden kutusu/CDC.

Idempotency yok - yinelenen ödemeler/borçlar.

'Bölge' işareti olmadan farklı bölgelerin PII/paralarının karıştırılması.

"Sessiz" Yeni bir sürüm ve azaltma olmadan değişiklikleri kırma.

Manuel olarak SDK oluşturma (gerçek özelliklerle sürüklenme).

Özellik bayrakları ve çift olay yazımı olmadan büyük patlama göçleri.

Tek bir API sadece bir "uç noktalar topluluğu'değil, bir ekosistem sözleşmesidir: tutarlı bir sözlük, istikrarlı parasal değişmezler, sürümlü olaylar, açık uyumluluk kuralları ve yönetilebilir indirimler. Semantik versiyon, idempotency, outbox/CDC, gözlemlenebilirlik ve güçlü güvenliğe dayanan platform, sağlayıcıları hızlı ve acısız bir şekilde birbirine bağlar ve yükseltmeler riskten rutine dönüşür.