Free round kampanyaları

Kampanya durumu

GET /v1/freerounds/{id} kampanyanın güncel hâlini döndürür. POST ve GET yanıtları, istek gövdesindeki alanlara ek olarak şunları içerir:

Tekrar güvenliği

reference gönderirseniz zaman aşımında aynı isteği güvenle yeniden deneyebilirsiniz. Aynı referans ve aynı içerik ilk kampanyayı 200 ve already_processed: true ile döndürür; kampanya bu arada iptal edilmiş olsa da aynı kampanya gelir; approval_id onay hâlâ bekliyorsa döner. İçerik karşılaştırılırken oyun ve oyuncu sırası, tekrarlanan oyuncu ve tutar yazımı (0.5, 0.50) fark etmez. Aynı referans farklı içerikle gelirse 409 REFERENCE_CONFLICT döner, kampanya açılmaz. Referans Test ve Canlı için ayrıdır. Kampanya yazılmadan önce doğrulama hatası alan istek referansı tüketmez. Tek istisna: hiçbir oyuncuya hak verilemezse (PLAYERS_REQUIRED) kampanya draft olarak kalır (reference verdiyseniz onunla); aynı referansla tekrar o taslağı döndürür, referanssız her deneme yeni taslak bırakır. Taslağı DELETE ile iptal edin. X-Request-Id kaydı süreyle silinir, reference silinmez.

{
  "id": "cmp_mrd_aralik",
  "name": "Aralık Hoş Geldin",
  "site_id": "site_mrd01",
  "template_id": null,
  "games": ["sultans-ember"],
  "spins": 20,
  "bet_value": 0.20,
  "currency": "USD",
  "players": ["u_88213"],
  "starts_at": "2026-12-01T00:00:00Z",
  "valid_days": 7,
  "reference": "crm-dec-welcome-88213",
  "status": "scheduled",
  "spins_used": 0,
  "won_total": 0.00,
  "already_processed": true
}

{
  "code": "REFERENCE_CONFLICT",
  "message": "A campaign with different content was already created with this reference.",
  "request_id": "req_01HF3R1C",
  "details": { "reference": "crm-dec-welcome-88213" }
}

Kampanya iptali

DELETE /v1/freerounds/{id} kampanyayı ve bekleyen veya etkin bütün hakları iptal eder, 204 döndürür, gövde yoktur. Oyuncunun açık turu varsa o turun kazancı yine ödenir. campaign.finished webhook’u status: cancelled ile gider. Kampanya bu sırada başladıysa 409 CAMPAIGN_CHANGED: tekrar deneyin.

Oyuncu hakları

Kampanyadaki her oyuncunun kendi hakkı ve durumu vardır. Yalnız active hak dönüş verir; diğer durumdaki hakla gelen free round bahsi Boss Hub’da reddedilir, cüzdanınıza gelmez.

Oyuncu ekleme

POST /v1/freerounds/{id}/players taslak, planlı veya açık kampanyaya oyuncu ekler; istek başına en çok 100 oyuncu. Yanıt 200 ve oyuncu başına sonuçtur: added yeni hak, exists oyuncunun bu kampanyada zaten hakkı var (hak çoğalmaz, status mevcut hakkın durumu), failed hak verilmedi. failed nedenleri: CURRENCY_NOT_SUPPORTED oyuncunun para birimi kampanyanın hiçbir oyununda yok veya kur yok, BET_INVALID dönüş değeri oyuncunun para birimine çevrilince sıfıra iniyor, BET_NOT_OFFERED çevrilen değer sağlayıcının bahis değerlerinden biri değil, PROVIDER_REJECTED: … sağlayıcı oyuncuyu reddetti. Üst alanlar: added bu istekte yazılan yeni hak, failed bu istekte başarısız olan, total kampanyadaki geçerli hak sayısı (iptal ve başarısızlar hariç). Kaydı olan oyuncunun hakkı kendi para birimindedir; henüz kaydı olmayan oyuncununki kampanya para biriminde. Aynı X-Request-Id ilk yanıtı döndürür.

{
  "added": 1,
  "failed": 1,
  "total": 2,
  "items": [
    { "player_id": "u_90412", "result": "added", "status": "pending", "reason": null },
    { "player_id": "u_88213", "result": "exists", "status": "pending", "reason": null },
    { "player_id": "u_77120", "result": "failed", "status": null, "reason": "CURRENCY_NOT_SUPPORTED" }
  ]
}

Oyuncu listesi

GET /v1/freerounds/{id}/players kampanyanın haklarını döndürür. Sonraki sayfa için yanıttaki next_cursor değerini cursor olarak gönderin; null ise liste bitti.

{
  "items": [
    {
      "player_id": "u_88213",
      "status": "active",
      "currency": "USD",
      "spins_left": 38,
      "won_total": 38.40,
      "expires_at": "2026-11-30T23:59:59.999Z",
      "cancelled_at": null,
      "fail_reason": null
    }
  ],
  "next_cursor": null
}

Tek oyuncu iptali

DELETE /v1/freerounds/{id}/players/{player_id} oyuncunun kullanılmamış dönüşlerini iptal eder ve 204 döndürür. Açık turun kazancı yine ödenir. Yalnız pending ve active hak iptal edilir; diğerleri 409 GRANT_CLOSED alır, details.status hakkın durumudur. Hakkı sağlayıcının yürüttüğü kampanyada iptal sağlayıcıya da iletilir; sağlayıcı tek oyuncu iptalini desteklemiyorsa 409 PROVIDER_CANCEL_UNSUPPORTED döner, kampanyanın tamamını iptal edebilirsiniz.

Cüzdana etkisi

• Free round bahsi bet ile gelir: is_freeround: true, campaign_id dolu, amount: 0. Bakiyeyi düşmeyin. Dönüş değeri freeround_bet_value alanındadır.
• Kazanç normal win ile gelir, bakiyeye ekleyin.
• Sağlayıcının Boss Hub kampanyası dışında kendi yürüttüğü free round’u da gelir: bahiste ve kazançta is_freeround: true, campaign_id: null; freeround_bet_value ve freeround_grant_id gelmeyebilir; kazanç bahissiz bir turda gelebilir ve Boss Hub kampanya kazanç tavanı uygulamaz. Bkz. Bahissiz kazanç.
• Bahis OK olunca dönüş hakkı azalır, rollback OK olunca geri gelir. Rollback nakit iade etmez.
• İptal edilen veya süresi dolan hakla bahis size gelmez: Boss Hub reddeder.

Hata kodları