GambleHub Entegrasyon Kılavuzu

1) Genel bakış ve etkileşim modeli

• API sağlayıcısı: GambleHub API'sini (cüzdan, bonuslar, raporlar) çağırırsınız.
• Harici sağlayıcı: webhook'larınızı/uç noktalarınızı (bakiye, işlemler, KYC) çağırıyoruz.

1. Edge/API (REST/gRPC, Webhooks)

2. Etkinlikler (etkinlik otobüsü: bahisler/ödemeler/cüzdan/ICC)

3. Raporlama (API + S3/SFTP dışa aktarma)

4. İşlemler (olaylar, SLO, SLA kredileri)

2) Ortamlar, etki alanları ve IP

Sözleşme SLA'sı sözleşmede sabittir. IP güncellemeleri önceden yayınlanır. Allowlist'e izin ver.

3) Kimlik doğrulama ve yetkilendirme

• OAuth2 İstemci Kimlik Bilgileri: sunucudan sunucuya ('scope': 'wallet: read', 'wallet: write', 'bet: write', 'report: read').
• JWT (yayıncı = GambleHub): RS256 imza, JWKS uç noktasındaki anahtarlar.
• mTLS: Giriş düzeyinde karşılıklı TLS kimlik doğrulaması (uyumluluk isteği üzerine).

POST /oauth2/token grant_type=client_credentials&scope=wallet:write bet:write
→ { "access_token": "...", "token_type": "Bearer", "expires_in": 3600 }

Her aramada kapsamlar kontrol edilir. Yüksek riskli işlemler (ödemeler) için, adım atma kullanılır: ayrı bir kapsam ve isteğe bağlı olarak IP/ASN'ye bağlanır.

4) Sürüm oluşturma ve uyumluluk

Yol:'/v1/... ','/v2/...' (ana sürüm geri uyumsuz).
Küçük ve genişleyen değişiklikler - planın genişletilmesi yoluyla (yeni isteğe bağlı alanlar).
Düşüşler - bildirim ile 90 gün.
Webhook'lar 'X-GH-Event-Version: 1' başlığı ile çevrilmiştir.

5) Sınırlar, kotalar ve idempotency

• 'X-RateLimit-Limit', 'X-RateLimit-Kalan', 'X-RateLimit-Sıfırlama'.
• 429, 'Retry-After' (saniye) ile geri döner.
• Tüm güvenli olmayan yöntemler 'Idempotency-Key' (TTL 24-72 h) gerektirir. Aynı sorguyu tekrarlamak orijinal sonucu döndürür (çakışmada '409 IDEMP_REPLAY').

6) Hata standartları

json
{
"type": "https://docs. gamblehub. io/errors/validation_failed",
"title": "Validation failed",
"status": 422,
"error_code": "VAL_001",
"trace_id": "a1b2c3...",
"retriable": false,
"errors": [{"field":"amount","code":"min","message":"Must be >= 1"}]
}

Yeniden başlatılabilir: 5xx/ 503/504/429 (с 'Retry-After'). Yeniden kullanılamaz: 400/401/403/404/409/ 422/410/415/412.

7) Veri şemaları (çekirdek)

7. 1 Oyuncu

json
{
"player_id": "p_123",
"country": "CA",
"currency": "CAD",
"rg_flags": {"self_excluded": false, "limits": {"daily_loss": 100}},
"kyc_status": "verified    pending    failed"
}

7. 2 Oturum

json
{
"session_id": "s_789",
"player_id": "p_123",
"started_at": "2025-11-03T17:55:00Z",
"ip": "203. 0. 113. 5",
"device": {"ua":"...", "os":"Android", "model":"..."}
}

7. 3 Cüzdan/İşlemler

json
{
"txn_id": "t_001",
"player_id": "p_123",
"type": "deposit    withdrawal    bet    win    bonus    adjustment",
"amount": "12. 34",
"currency": "EUR",
"balance_after": "123. 45",
"metadata": {"provider":"psp_x","request_id":"r_456"}
}

7. 4 Oran/ödeme

json
{
"bet_id": "b_456",
"player_id": "p_123",
"game_id": "g_777",
"stake": "1. 50",
"currency": "EUR",
"placed_at": "2025-11-03T17:58:10Z",
"round_id": "rnd_aa1",
"provider": "StudioX"
}

json
{
"settlement_id": "st_456",
"bet_id": "b_456",
"win_amount": "3. 75",
"settled_at": "2025-11-03T17:59:02Z",
"outcome": "win    lose    void"
}

7. 5 Bonus

json
{
"bonus_id": "bo_900",
"player_id": "p_123",
"type": "freespin    cash    wagered",
"state": "issued    active    expired    consumed",
"wagering": {"target": "100. 00","progress":"45. 20","currency":"EUR"}
}

8) REST API (OpenAPI parçaları)

yaml paths:
/v1/wallet/balance/{player_id}:
get:
summary: Get wallet balance security: [{ oauth2: [wallet:read] }]
responses:
'200': { description: OK }
'401': { $ref: '#/components/responses/Problem' }
'404': { $ref: '#/components/responses/Problem' }

/v1/wallet/transactions:
post:
summary: Create wallet transaction security: [{ oauth2: [wallet:write] }]
parameters:
- name: Idempotency-Key in: header required: true schema: { type: string }
responses:
'201': { description: Created }
'409': { $ref: '#/components/responses/Problem' }
'422': { $ref: '#/components/responses/Problem' }

/v1/bets:
post:
summary: Register bet security: [{ oauth2: [bet:write] }]
responses:
'201': { description: Created }
'422': { $ref: '#/components/responses/Problem' }

9) Webhooks (GambleHub'dan İş Ortağına)

• 'X-GH-Event': 'player. created 'session. Start 'bet. placed 'bet. yerleşmiş 'wallet. 'kyc değişti. güncellenmiş'rg. sarkmış '
• 'X-GH-Event-Id': benzersiz UUID
• 'X-GH-Signature': 'sha256 = '
• 'X-GH-Retry': Deneme Hayır
• 'X-GH-Event-Version': '1'

json
{
"event": "bet. settled",
"occurred_at": "2025-11-03T18:00:12Z",
"data": {
"settlement_id": "st_456",
"bet_id": "b_456",
"player_id": "p_123",
"win_amount": "3. 75",
"currency": "EUR",
"outcome": "win"
}
}

Ana bilgisayar yanıtı - sadece 2xx bir başarı olarak kabul edilir. Aksi takdirde - retrai: üstel geri çekilme (1s, 3s, 10s, 30s, 2m, 10m, 30m; Maksimum 24 saat). Veri tekilleştirme için 'X-GH-Event-Id' kullanın.

text expected = base64(hmac_sha256(request_body, SHARED_SECRET))
header  = split(X-GH-Signature, '=')[1]
assert header == expected

10) Nakit akışı emri (Cüzdan akışı)

1. Depozito (PSP - cüzdan. Kredi)

2. Bahis (hold/yetkilendirme или otomatik ödeme)

3. Yerleşim (serbest bırakma bekletmesi; 'win'/' lose'/' void')

4. para çekme (cüzdan. debit PSP)

Tutma bakiyeleri ve çoklu cüzdanlar (gerçek/bonus) desteklenir.

11) Sandbox ve test senaryoları

Test oyuncuları: 'p _ sbx _', para birimleri' EUR 'USD' CAD '.
Oyun sağlayıcıları taklit eder: kazan/kaybet/geçersiz kıl, indirimler, gecikmeler.
KYC sanal alanı: Pasaport şablonlarında 'doğrulanmış' başarısız 'inceleme' yanıtları.
PSP sandbox: статусы 'yetkilendirilmiş' yakalandı 'ifadesi' düzeltildi '.

• Bilanço Stavka ^ vyplata ^ sverka
• Geri çekilme/boşluk yuvarlak
• Yeniden teklifte idempotency
• Webhook'un retrays ve sonraki veri tekilleştirme ile başarısızlığı
• 429 ve doğru 'Retry-After'
• 5xx istemci tarafı üstel yedekleme ile

12) Mutabakatlar ve Raporlama

Mutabakat API'si

yaml
GET /v1/reports/reconciliation? from=...&to=...&scope=wallet    bets
→ CSV/JSON: { player_id, bet_id, stake, win, currency, balance_delta, provider }

Günlük özetler: cirolar, GGR/NGP, sağlayıcılar, jeo/para birimi dökümü.
Dışa aktarma: İmzalı manifestoları ve dosya karmalarını (SHA256) içeren S3/SFTP.
Raporlama saat dilimi: UTC (sözleşmede aksi belirtilmedikçe).

13) Gözlemlenebilirlik ve SLO

SLI: API ≥ 99'un başarısı. %95 (28d), kritik yöntemler için p95 gecikme süresi, webhook teslim başarısı.
Hatalı bir bütçede yanma uyarıları (hızlı/yavaş).
Trace korelasyonu: Yanıtlarda/günlüklerde 'trace _ id', izlere drilldown.
Durum sayfası: Kenar, Cüzdan, Bahisler, Web Kitapları, PSP, KYC bileşenleri.

14) Güvenlik ve uyumluluk

PII minimizasyonu; PAN/sırlar günlüklerde/webhook'larda yasaktır.
Gizli yönetim ve anahtar rotasyonu.
RG (Sorumlu Kumar): Kendi kendini dışlama/limit bayrakları, bahislerin/ödemelerin otomatik olarak reddedilmesine neden olmalıdır.
AML/KYC: 'kyc' etkinlikleri. Güncelleme ',' aml. Uyarı 'abonelikle kullanılabilir; Sisteminizde veya modülümüz aracılığıyla kararlar verin.
GDPR/DSAR: Yasal talepler için oyuncunun kişisel verilerini yüklemek/silmek için son noktalar.
mTLS ve HSTS varsayılan olarak üretim ortamında etkinleştirilir.

15) Performans ve kotalar

• RPS: 50 (burst 100)
• Eşzamanlı webhook'lar: 10
• Gövde boyutu: ≤ 256 KB (oyun etkinlikleri), ≤ 64 KB (cüzdan)

RPS tahminini/hacimlerini belirten hesap yöneticisi aracılığıyla planın yükseltilmesini isteyin.

16) Değişim ve Sürüm Yönetimi

Pencereleri değiştirin: zamanlanmış çalışma - zamanında, bildirim ≥ 5 iş günü.
Sürüm geçişleri: Geçiş döneminde çift yazma/çift okuma.
CI sözleşme testleri: JSON şeması, gerekli alanlar, kararlı 'error _ code'.
Kanarya: yeni özellikler için trafiğin kademeli olarak dahil edilmesi.

17) Entegrasyon sertifikası (Check-list)

• Teklif/Ödeme Kaydı/geçersiz
• Tüm yazma bitiş noktalarında idempotency
• Doğru 429/5xx + geri alma işlemi
• Webhook İmza Doğrulama, X-GH-Event-Id Veri Tekilleştirme
• Bir dizi olaydan sonra denge uzlaşması (kazan/kaybet)
• Mutabakat raporları verilerinizle aynı fikirde

• Webhook geri çekilmeleri uygulanmaktadır
• İstemci zaman aşımları ≤ 10c, toplam deneme ≤ 30c
• Bağımlılıklarda devre kesici

• Sırları Gizli Yöneticide Saklamak
• Günlüklerde PII Sürümü
• RG/AML bayrakları gerçek zamanlı olarak kabul edilir

18) Sık kullanılan senaryolar

18. 1 Idempotency ile kayıt oranı

POST /v1/bets
Idempotency-Key: bet-p_123-rnd_aa1-1

{ "player_id":"p_123","game_id":"g_777","stake":"1. 50","currency":"EUR","round_id":"rnd_aa1" }
→ 201 Created { "bet_id":"b_456" }

18. 2 Başarısız webhook ve ardından başarı

1. Sunucunuz kullanılamıyor - 5xx - backoff retro.
2. Kurtarmadan sonra - aynı 'X-GH-Event-Id' almak - kopyaları görmezden gelmek zorundadır.

18. 3 Sağlayıcının kısmi bozulması

503'ü iade edeceğiz; backoff ile tekrarlayın.
Uzun bozulma ile - sağlayıcının işaretlenmesini durdurun ve dahil. akıllı yönlendirme (sözleşmedeyse).

19) DevEx ve destek

Portal: anahtarlar, kullanım, webhook'lar, teslimat günlükleri, SLO panoları, dışa aktarma raporları.
Webhooks replay: tarih aralığı/ID göre yeniden teslim.
Olaylar: Bir biletin otomatik olarak oluşturulması, savaş odası, ölüm sonrası ≤ SEV-1 48 saat.
İletişim: # partners-status channel/mail on-call 24 × 7 (Enterprise).

20) Onboarding planı (2-4 hafta)

1. 1. Hafta: anahtar verme, sandbox bağlantısı, temel senaryolar (bahis/ödeme/cüzdan).
2. 2. Hafta: Web Kitapları ve Mutabakatlar, RG/KYC Bayrakları, Yük Testleri, 429/5xx Davranış.
3. 3. Hafta: Raporlama (mutabakat, yüklemeler), güvenlik (imzalar, sırlar), sözleşme testleri.
4. 4. Hafta: sertifikasyon, satışlara kanarya dahil etme, izleme, temas matrisi.

21) Mini-SSS

GRPC alabilir miyim?
Evet, istek üzerine; Belirtimde HTTP hata kodu eşlemesi sağlanır.

Retro veriler nasıl elde edilir?
'Mutabakat' raporları aracılığıyla (tarihlerden/tarihlerden) veya S3/SFTP yükleyin.

Sınırlarımı nasıl kaldırırım?
Tahmini RPS/rekabetçiliği gösteren portal/hesap yöneticisi aracılığıyla.

Denge gerçeğinin kaynağı olarak ne kabul edilir?
GambleHub cüzdan işlem günlüğü + günlük mutabakat.

Toplam

GambleHub ile entegrasyon net bir sözleşme üzerine inşa edilmiştir: istikrarlı API'ler ve şemalar, imzalı webhook'lar, idempotency ve retray'ler, şeffaf limitler ve raporlamanın yanı sıra güvenlik ve uyumluluk gereksinimleri. Bu kılavuzu ve sertifika kontrol listelerini takip ederek, güvenilir nakit akışları ve tutarsızlıklar olmadan tutarlı raporlar sağlayarak pazara hızlı bir şekilde ulaşacaksınız.