Sağlayıcı API/Oyun başlatma (launch)

Oyun başlatma (launch)

API · Operatör → Boss Hub

POST/v1/game/launch

Oyuncu için gerçek parayla oyun oturumu açar. Dönen launch_url tek kullanımlıktır ve expires_in saniye (varsayılan 60 sn) geçerlidir; oyuncuyu bu adrese yönlendirin. Oyuncu kaydı site ve ortam başına ilk launch’ta otomatik oluşur. game.launch kapsamı gerekir.

Başlıklar

Başlık	Açıklama
X-Operator-Id	Operatör kimliğiniz
X-Timestamp	Unix saniye. ±30 sn dışı reddedilir
X-Signature	hex(HMAC_SHA256(secret, ts + "." + METHOD + "." + path?query + "." + body))
X-Request-Id	Zorunlu, en çok 128 karakter. Aynı kimlik ve gövde ilk yanıtı döndürür (4xx dahil), farklı gövde 409 alır. Bkz. Idempotency
X-Api-Key	İsteğe bağlı. Birden çok anahtarınız varsa doğru secret’ı seçer

Gövde parametreleri

game_idstringzorunlu

Oyun kodu, örn. sultans-ember.

player_idstringzorunlu

Operatör tarafındaki oyuncu kimliği, 1–128 karakter (örn. auth-68db7e011acef9a1df596355_TRY). Daha uzunu 422 VALIDATION_ERROR (details.fields) alır. Callback’lerde aynen döner.

currencyISO 4217zorunlu

Oturum para birimi: USD, EUR, TRY. Sitenin, cüzdan ayarının ve oyunun desteklediği bir para birimi olmalı. Oyuncunun para birimi o sitedeki ilk launch’ta sabitlenir; aynı player_id başka para birimiyle 422 CURRENCY_NOT_SUPPORTED alır.

tokenstringzorunlu

Oyuncu oturum token’ınız. authenticate callback’inde size geri gönderilir. Launch bu token’ı doğrulamaz: authenticate, oyuncu launch_url’i açınca çağrılır. Geçersiz token’la launch 200 döner, oyuncu açılışta hata sayfası görür (403). Token en az expires_in süresi geçerli olmalı.

site_idstring

Site kodu, örn. site_mrd01. Siteye bağlı anahtarda çıkarılır; operatör geneli anahtarda yalnız tek siteniz varsa çıkarılır, yoksa zorunludur.

languagestring

Oyun dili: tr, en. Varsayılan tr. Açılış hata sayfası da bu dildedir. EGT oyunları şu an yalnız Türkçe açılır: en kabul edilir ve oturuma yazılır, ama oyunun ve oyun içi panellerin dili Türkçe kalır.

rtp_variantstring

İstenen RTP varyantı: v96, v94, v92. Oyunun sunduğu bir varyant olmalı (GET /v1/games → rtp_variants); oyunda hiç olmayan varyant 422 RTP_VARIANT_NOT_OFFERED alır (details.offered), oturum açılmaz. Sunulan ama pazar kuralına uymayan varyant aşağıdaki kurala göre değişir. Oturuma ve tura yalnız uygulanan varyant yazılır.

lobby_urluri

Oyundan lobiye dönüş adresi, mutlak URL. Gönderilmezse sitede geçerli cüzdan ayarının Lobi URL’i kullanılır: sitenin kendi cüzdan ayarı varsa onunki (boşsa boş kalır), yoksa operatörünki. Açılış hata sayfasındaki "Lobiye dön" bağlantısı bu adrestir. EGT oyunları bu adresi henüz kullanmıyor: oyunun kapat düğmesi lobinize dönmez (köprü düzeltmesi sürüyor).

deposit_urluri

Para yatırma adresi, mutlak URL. Gönderilmezse sitede geçerli cüzdan ayarının Para yatırma URL’i kullanılır (lobi adresiyle aynı kural). EGT oyunları bu adresi henüz kullanmıyor.

devicestring

Cihaz ipucu: desktop, mobile. Varsayılan desktop. Oturuma yazılır. EGT bu alanı kullanmaz: oyun düzenini oyuncunun tarayıcısından seçer.

player_refstring

Harici oyuncu referansı, en çok 100 karakter, örn. 7731-0042. Portalda harici ID olarak görünür.

player_usernamestring

Oyuncunun kullanıcı adı, en çok 100 karakter. Portalda aramada kullanılır.

device_fpstring

Cihaz parmak izi, en çok 128 karakter. Çoklu hesap kuralının girdisidir; göndermezseniz kural sessiz kalır.

recommendation_idstring

Oyuncu oyunu bir öneriden açtıysa öneri yanıtındaki kimlik, en çok 100 karakter. Oturuma yazılır; imzası tutmazsa 422 VALIDATION_ERROR (details.field).

countrystring

Oyuncunun ülkesi, ISO 3166-1 alfa-2 (TR, DE); küçük harf büyütülür. Oyuncuya ve oturuma yazılır; göndermezseniz oyuncunun bilinen son ülkesi kullanılır. Turnuva ülke süzgeci ve raporların ülke kırılımı bu değeri okur.

player_ipstring

Oyuncunun IP adresi (IPv4 veya IPv6). Oturuma yazılır; göndermezseniz isteğin geldiği adres yazılır.

RTP: Sitenizin pazarı varsa varyant pazar kurallarına göre seçilir. Boss Originals oyunlarında varyant, oyunun canlı sürümü için o pazarda onaylı sertifika ister. Dış sağlayıcıların (örn. EGT) oyunlarında sertifika sağlayıcının sorumluluğundadır; her varyant sertifikalı sayılır. İstenen varyant uygunsa (sertifikalı ve RTP ≥ pazarın asgari RTP’si) kullanılır; değilse en düşük uygun varyanta geçilir (v92 → v94). Uygun varyant yoksa 403 MARKET_RESTRICTED. Pazarı olmayan sitede istenen varyant, yoksa site ve operatör tercihi, yoksa oyunun varsayılanı kullanılır. EGT oyunları tek varyant sunar (v96): EGT oyunun RTP’sini kendi yapılandırmasından uygular, launch başına değiştirmez; başka varyant 422 RTP_VARIANT_NOT_OFFERED alır.

Kredi limiti: Limit aşıldığında yalnız yeni oturum açılamaz. Açık oturumlar oynamaya devam eder.

Ülke yasağı: Sağlayıcı veya oyun bazı ülkeleri yasaklayabilir; liste GET /v1/games yanıtında blocked_countries. Etkin ülke listedeyse 403 COUNTRY_BLOCKED döner. Liste doluyken ülke hiç bilinmiyorsa (ne country geldi ne oyuncunun kaydında var) 403 COUNTRY_REQUIRED döner. Liste boşsa country göndermeseniz de sonuç değişmez.

POST /v1/game/launch HTTP/1.1
Host: staging.example.com
Content-Type: application/json
X-Operator-Id: op_meridyen
X-Timestamp: 1762344000
X-Signature: 9f2c0b…e41a
X-Request-Id: req_01HF3K7A

{
  "game_id": "sultans-ember",
  "site_id": "site_mrd01",
  "player_id": "u_88213",
  "player_ref": "7731-0042",
  "player_username": "kral",
  "token": "tok_8f2a6c41",
  "currency": "USD",
  "language": "tr",
  "rtp_variant": "v96",
  "lobby_url": "https://casino.example/lobby",
  "deposit_url": "https://casino.example/deposit",
  "device": "mobile",
  "country": "TR",
  "player_ip": "203.0.113.24"
}

200Oturum açıldı

{
  "launch_url": "https://api.example.com/s/7Hq…",
  "session_id": "ses_01HF3K7M",
  "expires_in": 60,
  "limits": {
    "currency": "USD",
    "min_bet": 0.20,
    "max_bet": 100.00,
    "default_bet": 1.00,
    "source": { "min_bet": "platform", "max_bet": "site" }
  }
}

402Kredi limiti aşıldı veya operatör askıda

{
  "code": "CREDIT_LIMIT",
  "message": "Credit limit exceeded; no new game can be opened.",
  "request_id": "req_01HF3Q2N",
  "details": { "source": "credit" }
}

403Pazar kuralına uygun RTP varyantı yok

{
  "code": "MARKET_RESTRICTED",
  "message": "A market rule does not allow this game.",
  "request_id": "req_01HF3Q2P",
  "details": { "source": "market_rule" }
}

Yanıt alanları

Alan	Tür	Açıklama
launch_url	uri	Oyuncunun açacağı tek kullanımlık adres.
session_id	string	Oyun oturumu. Callback’lerde session_id olarak gelir.
expires_in	integer	launch_url geçerlilik süresi, saniye.
limits	object	Bu oturumun etkin bahis limitleri. Alanlar: limits.

launch_url açılışı

Oyuncunun tarayıcısı launch_url’i açınca Boss Hub sizin authenticate callback’inizi çağırır, sonra oyuncuyu oyun istemcisine yönlendirir. Adres bir kez açılır; iframe kullanıyorsanız oyun adreslerine izin verin. Adresi önceden açmayın (bağlantı önizlemesi, fetch): ilk GET onu tüketir. HEAD isteği ve tarayıcının ön yükleme isteği (Sec-Purpose: prefetch, Purpose: prefetch) tüketmez; ön yüklemeye 503 döner.

Açılış hata verirse tarayıcı (Accept: text/html) ham JSON değil, launch language’ında kısa bir sayfa görür: ne olduğu, lobby_url biliniyorsa "Lobiye dön" bağlantısı (iframe’de üst pencereyi açar), hata kodu ve request_id. HTTP durumu aşağıdaki tablodakiyle aynıdır. Programla (Accept HTML değilken) çağırana gövde bugünkü gibi JSON döner. Sık durum: oyuncu sayfayı yeniler veya geri tuşuyla aynı launch_url’e döner; adres kullanıldığı için 410 sayfası görür. Oyunu her açışta yeni launch isteyin.

HTTP	Kod	Anlam
302		Oyuna yönlendirme
410	LAUNCH_TOKEN_EXPIRED	Adres daha önce açıldı, süresi doldu veya oturumlar sonlandırıldı. Yeni launch isteyin
404	NOT_FOUND	Adres tanınmıyor
403	INVALID_TOKEN, PLAYER_BLOCKED, INTERNAL_ERROR	authenticate yanıtınız reddetti
503	WALLET_UNAVAILABLE	Cüzdanınız authenticate'e yanıt vermedi, HTTP 200 dışı döndü ya da gövde JSON değildi. details.wallet_call: "authenticate", details.wallet_status (ör. http_400, timeout, network, unparseable); portalda Entegrasyon > Cüzdan sağlığı aynı etiketi gösterir. Oyun sağlayıcısı çağrılmaz
503	PROVIDER_UNAVAILABLE	Cüzdan oyuncuyu doğruladı ama oyun sağlayıcısı oturumu açamadı (details.provider_code)

Demo oturumu

POST /v1/game/demo imza ve X-Request-Id gerektirmez. Demo oyun başınadır: yalnız GET /v1/games yanıtında demo: true olan oyunlarda açılır (sağlayıcı demo sunuyor, oyun herkese açık listede, yayında veya yayına hazır). EGT oyunlarında demo yok (demo: false, 404 DEMO_NOT_AVAILABLE). IP başına dakikada 60 istekle sınırlıdır; oyuncu ve defter kaydı oluşmaz.

game_idstringzorunlu

Oyun kodu, örn. sultans-ember.

currencyISO 4217

USD (varsayılan), EUR, TRY.

languagestring

Oyun dili: tr, en. Varsayılan tr.

countrystring

Oyuncunun ülkesi. Gönderirseniz oyunun yasak listesi uygulanır (403 COUNTRY_BLOCKED); göndermezseniz demo açılır.

POST /v1/game/demo HTTP/1.1
Host: staging.example.com
Content-Type: application/json

{
  "game_id": "sultans-ember",
  "currency": "USD",
  "language": "tr"
}

200Demo adresi

{
  "launch_url": "https://play.example.com/demo/…"
}

Hata kodları

Kod	HTTP	Anlam
INVALID_SIGNATURE	401	İmza başlıkları eksik veya imza doğrulanamadı
TIMESTAMP_SKEW	401	X-Timestamp ±30 sn dışında
CREDIT_LIMIT	402	Kredi limiti aşıldı, yeni oturum açılamaz (details.source: credit)
OPERATOR_SUSPENDED	402	Operatör askıda veya Canlı’da production onayı yok
IP_NOT_ALLOWED	403	IP izin listesinde değil
SCOPE_MISSING	403	game.launch kapsamı yok
SCOPE_DENIED	403	site_id tanınmıyor, sizin değil veya siteye bağlı anahtarınızın sitesi değil
MODULE_DISABLED	403	Dış sağlayıcı oyunu ve providers modülü kapalı
GAME_DISABLED	403	Oyun bu sitede açılamıyor; neden details.source’ta (aşağıda)
SITE_DISABLED	403	Site kapalı veya Canlı’da çağrılan site Canlı durumda değil
MARKET_RESTRICTED	403	Pazar kuralına uygun RTP varyantı yok
PLAYER_BLOCKED	403	Oyuncu kısıtlı, ya da oyuncu kısıtının bahis tavanı oyunun en düşük bahsinin altında (details.source: player_restriction)
COUNTRY_BLOCKED	403	Oyun veya sağlayıcı oyuncunun ülkesini yasaklıyor (launch ve demo)
COUNTRY_REQUIRED	403	Oyunda ülke yasağı var, oyuncunun ülkesi bilinmiyor: country gönderin
NOT_FOUND	404	Bu game_id ile oyun yok; demoda oyun herkese açık listede değil
DEMO_NOT_AVAILABLE	404	Demo: sağlayıcı bu oyun için demo sunmuyor
REQUEST_ID_CONFLICT	409	Aynı X-Request-Id, farklı gövde
REQUEST_IN_PROGRESS	409	Aynı X-Request-Id hâlâ işleniyor
SITE_REQUIRED	422	Operatör geneli anahtar ve birden çok site: site_id gerekli
VALIDATION_ERROR	422	Eksik veya geçersiz alan (details.fields), eksik X-Request-Id ya da geçersiz recommendation_id (details.field)
INVALID_JSON	422	Gövde JSON olarak okunamadı
CURRENCY_NOT_SUPPORTED	422	Para birimi site, cüzdan ayarı veya oyun tarafından desteklenmiyor, ya da oyuncunun para birimi farklı
RTP_VARIANT_NOT_OFFERED	422	rtp_variant oyunda yok; sunulanlar details.offered’da. Oturum açılmaz
RATE_LIMITED	429	Hız limiti aşıldı
PROVIDER_NOT_CONNECTED	503	Sağlayıcı bu ortamda bağlı değil
PROVIDER_UNAVAILABLE	503	Demo: sağlayıcıya ulaşılamadı
MAINTENANCE	503	Platform veya sağlayıcı bakımda (details.source: maintenance)

GAME_DISABLED details.source	Neden
platform	Oyun veya sağlayıcı platformda kapalı
access	Sağlayıcı erişiminiz yok ya da sağlayıcı bu ortamda açık değil (Canlı’da canlıya alınmış olmalı); veya oyun seçili oyun listenizde değil
game	Oyun emekli, ya da yayında sürümü yok ve erken erişimde değil
operator_rule	Operatör geneli kuralınızla kapalı
site_rule	Site kuralınızla kapalı
limits	Bu para biriminde bahis limiti tanımlı değil

Kontrol sırası: JSON ayrıştırma ve gövde doğrulaması, zaman damgası, imza, IP, hız limiti, X-Request-Id, kapsam; sonra oyun, site, bakım, operatör, site durumu, modül, oyun erişimi ve kuralları, pazar, kredi, RTP varyantı, ülke, sağlayıcı bağlantısı, para birimi, limit ve oyuncu. İlk kapalı adımın kodu döner.

EGT oyunlarında oturum

Konu	Davranış
Tek pencere	Oyuncu aynı anda tek EGT oyun penceresinde oynar. Yeni bir launch’la açılan pencere (aynı ya da başka oyun, başka sekme veya cihaz) öncekinin bağlantısını kapatır: eski pencerede "Oyun başka bir pencerede açıldı" paneli çıkar (WebSocket kodu 4001). Bahis ve turlar etkilenmez; oyuncu en son açtığı pencereden devam eder.
Oturum ömrü	launch_url expires_in saniye (varsayılan 60) geçerli ve tek kullanımlık. Açılan oyun oturumunun Boss Hub tarafında boşta kalma süresi yoktur: oyuncu oyundayken sürer, portalda oturumlar sonlandırılınca biter. Oyunu yeniden açmak için her seferinde yeni launch isteyin.
Kilit (4504)	Oyuncunun bu oyunda yarım kalmış bir özelliği (bedava dönüş, bonus) ya da çözüm bekleyen bir tur kaydı varsa oyun yüklenir ama bağlantı 4504 ile kapanır; oyuncu "Tur kaydınız korunuyor" ya da "Tur için destek incelemesi gerekiyor" panelini ve bir kayıt numarası görür. Kilit oyun köprüsünde tutulur; Boss Hub launch anında bilmez, launch 200 döner. Otomatik kontrol kesin sonucu bulursa kilit kendiliğinden kalkar ve oyun kaldığı yerden açılır.
Kilitte destek	Panel "destek incelemesi" diyorsa oyuncunun player_id’si, game_id, paneldeki kayıt numarası ve yaklaşık saatle Boss Hub desteğine yazın; kaydı Boss Hub ekibi çözer, çözülünce oyun normal açılır. Boss Hub cüzdanındaki takılı turlar ayrıca takılı turlar listesinde görünür ve oradan çözülür.
Dil	EGT oyunları şu an yalnız Türkçe açılır.
Demo	EGT demo sunmaz: GET /v1/games → demo: false.
Lobi ve para yatırma	EGT oyunları lobby_url ve deposit_url’i henüz kullanmıyor (köprü düzeltmesi sürüyor). Oyunu kendi sayfanızda açıyorsanız lobiye dönüşü kendi arayüzünüzden verin.

← ÖncekiOyun önerileri Sonraki →Tur sorgulama & replay