SportApi
API Dokümantasyonu

Bahis ve Kupon Hesaplama için Sistem Entegrasyonu

Bu sistem; bahis hesaplama ve kupon yönetimi sürecini otomatikleştirmeyi amaçlayan spor bahsi operatörleri, bahis şirketleri ve platform geliştiricileri için tasarlanmıştır. Sonuç hesaplamalarının hızlı bir şekilde entegre edilmesini sağlar, kupon durumları (kazanma, kaybetme veya iade) hakkında doğru veriler sunar ve operatörün sunucusu ile hesaplama sistemi arasındaki etkileşimi basitleştirir.

POST /v1/coupon json
{
  "coupon_id": "A7F3K9",
  "type": "express",
  "events": [
    { "id": 88213, "pick": "1", "odds": 2.10, "result": "win" },
    { "id": 88150, "pick": "over_2_5", "odds": 1.80, "result": "win" }
  ],
  "total_odds": 3.78, "status": "won"
}

Sistem nasıl çalışır?

Oran ve Sonuç Hesaplama Sistemi Nasıl Çalışır?

Bahis ve kupon hesaplama sistemimizle entegrasyon üç temel aşamadan oluşur:

Aşama 1: Yetkilendirme

İlk aşamada sistemde yetkilendirme yapmanız gerekir. Bu, kullanıcı kimlik bilgileriyle (kullanıcı adı ve şifre) bir POST isteği gerçekleştirilerek yapılır. Başarılı yetkilendirme, kaydedilmesi gereken bir tanımlama bilgisi (cookie) olarak temsil edilen bir oturum döndürür. Bu çerezler, sistemdeki kullanıcının oturumunu tanımlamak için kullanıldığından sonraki tüm istekler için gereklidir.

Aşama 2: Bahis Gönderme

Bu aşamada sistemimize şunları içeren bir bahis kodu gönderilir:

  • Etkinliğe karşılık gelen Maç Kimliği.
  • Seçilen sonucu tanımlayan Bahis kodu (örneğin, takım galibiyeti, handikap veya toplam).
  • Gönderim anında geçerli olan Bahis oranları.

Verileri gönderirken, yetkilendirme sırasında elde edilen çerezler eklenmelidir. Bu, doğru kullanıcı tanımlamasını ve bahis işlemini sağlar.

Aşama 3: Sonuçları Alma

Sonuçlar veya kuponlar hesaplandıktan sonra sistemimiz belirtilen remote_host adresine POST istekleri gönderir. Bu istek şunları içerir:

  • Kupon durumu (kazanma, kaybetme veya iade).
  • Kuponda yer alan tüm sonuçların durumları.

Sonuçlar, sonuç belirlenir belirlenmez gönderilir. Örneğin:

  • Bahis bir ara sonuca oynandıysa (örneğin, handikap 2.5 ve üçüncü gol atıldıysa), hesaplama maç sırasında yapılabilir.
  • Bahis nihai sonuca (örneğin, takım galibiyeti) yönelikse, durum bilgisi maç bittikten hemen sonra gönderilecektir.

Şimdi her adımı ayrı ayrı inceleyin. İstekleri, parametreleri ve API yanıtlarını ayrıntılı olarak açıkladık.

Kullanıcı yetkilendirme

İstekleri göndermek için kullanıcı adı, şifre ve ana sunucu yöneticiden alınabilir.

İstek URL'si:

{APIHOST}/WebServices/BCService.asmx/LogIn/

Veri Gönderim Türü: POST

Gönderilen Veriler:

ParametreAçıklama
loginKullanıcı adı
passwordKullanıcı şifresi

Önemli!

  • Yetkilendirme sırasında yanıt çerezler içerir. Bu çerezler kaydedilmeli ve sonraki isteklerle birlikte gönderilmelidir.

Daha kolay entegrasyon için öneriler:

  • login alanının dize olarak geçirildiğinden emin olun.
  • Sonraki isteklerin yürütülmesini etkilediğinden, çerezlerin doğru şekilde kaydedildiğini ve gönderildiğini doğrulayın.
  • Hata durumunda istek boş bir nesne döndürür. Bu senaryoyu uygun şekilde ele aldığınızdan emin olun.

Çerezler 3 ay boyunca geçerlidir. Ancak sunucu yeniden başlatılırsa sıfırlanabilirler. Bu nedenle, kupon kaydederken hata ile karşılaşırsanız yeniden yetkilendirmeniz gerekir.

Hata yanıtı json
"errorCode":1,
"fullErrorCode":99,
"errorMessage":"Invalid access level"

İstek gönderme örneği (yönetici tarafından sağlanan verileri kullanın):

Örnek Yanıt:

Başarılı:

{"d":{"UserId":"36557"}}

Başarısız:

{"d":{}}

Yanıt Alanları Açıklaması:

AlanAçıklama
UserIdBenzersiz kullanıcı kimliği
dYanıtın kök nesnesi

Genel Öneriler:

  • İlk istekten önce kullanıcının doğru kimlik bilgilerini girdiğinden emin olun.
  • Kullanıcıya başarısız yetkilendirme nedenlerini (örneğin, yanlış kullanıcı adı veya şifre) göstermek için hata işlemeyi ayarlayın.
  • Analiz ve izleme için hem başarılı hem de başarısız denemeleri günlüğe kaydedin.

Çerezler kaydedilmeli ve sonraki isteklerle birlikte gönderilmelidir.

POST {APIHOST}/WebServices/BCService.asmx/LogIn/ python
import requests
import json

url = "https://example-domain-calc.com/WebServices/BCService.asmx/LogIn/"

payload = json.dumps({
  "login": "[email protected]",
  "password": "demo-password"
})
headers = {
  'Content-Type': 'application/json'
}

print(response.text)

Bahis veya kupon gönderme yöntemi

Bahis göndermek için yetkilendirme aşamasında elde edilen çerezleri kullanmalısınız. Bu veriler oturumunuzu tanımlamak ve istekleri işlemek için gereklidir.

İstek URL'si:

{HOST_API}/bet/place/
Örnek gövde yükü json
{
    "data":{
        "list_bets":[
            "line#586464528|17|954|2.5#4.27",  "live#586464528|87|4|0#1.12"
        ],
        "realAmount":"2",
        "currency":"USD",
        "lang":"en",
        "remote_host":"https://mysites.com",
        "rate_mode":"reject"
    }
}

remote_host ve rate_mode parametreleri

Alan Açıklamaları

ParametreAçıklama
list_betsBahis kodu ve oranları. Format: "event_type#match_ID|bet_code#odds". Örnek: "live#579216393|1|1|0#2.1"
realAmountBahis miktarı. Dize olarak geçirilmelidir, örn. "150".
currencyKupon para birimi.
langBahis ve kuponun kaydedildiği dil. Örneğin: "en", "ru" veya "tr".
remote_hostKupon hesaplama sonuçlarının gönderileceği URL. Eğik çizgiyle bitirmeyin.
rate_modeOranlar değiştiğinde kupon kabulünü işleme seçeneği: "reject" (değişikliklerde reddet) veya "accept" (değişikliklere bakılmaksızın kabul et). Varsayılan: "accept".

Not: Parametrelerin doğru formatta geçirildiğinden emin olun. Örneğin, tek bir bahis olsa bile list_bets bir dizi olmalıdır.

Bahis miktarını doğrulamıyoruz. Gerçek bahis miktarını veya herhangi bir rastgele değeri gönderebilirsiniz. Bu, finansal verilerinizin gizliliğini sağlamak içindir. Görevimiz hesaplama sonuçlarını sağlamaktır. Oyuncularınıza kazançları yatırmaktan siz sorumlusunuz.

Bahis Göndermek İçin Gerekli Parametreler:

  • list_bets — bahis ve ilgili maç hakkındaki bilgileri içerir.
  • remote_host — kupon veya sonuç için hesaplama sonuçlarını göndereceğimiz URL.
  • rate_mode — sistemin oran değişikliklerini nasıl işleyeceğini belirler.

Diğer parametreler de gönderilmelidir, ancak bunlar isteğe bağlıdır ve kolaylık sağlamak amacıyla kullanılabilir.

remote_host Parametresinin Açıklaması

remote_host, bahis hesaplamalarının sonuçlarını içeren istekleri gönderdiğimiz sunucunuzun adresidir. Bu ana sunucu, sunucumuzdan gelen istekleri kabul edecek şekilde yapılandırılmalıdır. Aşağıda olası değerlerin örnekleri ve bu parametreyle çalışmaya ilişkin ayrıntılar yer almaktadır.

remote_host için çeşitli seçenekler belirtebilirsiniz:

  • Basit ana sunucu: https://mysites.com
  • Bağlantı noktalı ana sunucu: https://mysites.com:78665
  • Ek yolları olan ana sunucu: https://mysites.com/request/sportapi/sender
  • Parametreleri olan ana sunucu: https://mysites.com/request.php?action=webhook

Önemli: İstek gönderirken sistemimiz belirtilen remote_host adresinin sonuna otomatik olarak /api/bet/result dizesini ekler. Böylece istekleri almak için nihai adres remote_host + "/api/bet/result" olarak oluşturulur. Sunucunuzun bu yolda veri alacak şekilde yapılandırıldığından emin olun.

Örnekler:
  • remote_host = https://mysites.com belirtirseniz istekleri şuraya göndeririz: https://mysites.com/api/bet/result.
  • remote_host = https://mysites.com/request.php?action=webhook belirtirseniz istekleri şuraya göndeririz: https://mysites.com/request.php?action=webhook/api/bet/result.

Teknik Detaylar:

  • İstekler POST yöntemi kullanılarak gönderilir.
  • Sunucunuz gönderdiğimiz JSON verilerini kabul etmeye hazır olmalıdır.
  • Sunucunuz başarılı veri alımından sonra 200 durum kodu döndürmelidir.

Sunucunuzun belirtilen yolu ve istekleri doğru şekilde işlediğinden emin olun. Sonraki bölümde sunucumuz tarafından gönderilen veri yapısının bir örneği verilmiştir.

rate_mode Parametresinin Açıklaması

rate_mode parametresi oranlar değiştiğinde sistemin davranışını tanımlar. İki değer alabilir:

  • accept: Bu modda kupon, değişmiş olsalar bile mevcut oranlarla kabul edilecektir. Örneğin, bir oyuncu 2.02 oranlı "Manchester Kazanır" bahsi ekler. "Bahis Yap" butonuna basana kadar oranlar 1.37 veya 2.78 olarak değişir. accept modunda sistem, sisteminize bildirmeden kuponu yeni oranlarla kaydeder.
  • reject: Bu modda oranlar değiştiyse sistem kuponu reddeder. Yanıt, oranların değiştiğini bildiren bir hata içerecektir.

İş süreçlerinize en uygun ve kullanıcılarınıza kolaylık sağlayan modu seçin.

Önemli Öneriler

  1. JSON Biçimlendirme: Göndermeden önce verilerin JSON biçiminde düzgün şekilde serileştirildiğinden emin olun.
  2. Çerezler (Cookies): Kullanıcı oturumunu başarıyla tanımlamak için yetkilendirme sırasında elde edilen çerezleri ekleyin.
  3. Hata İşleme: Sunucu yanıtlarını, özellikle errorCode = 1 döndürülen durumları ele alın.
  4. Test Etme: Tekli ve çoklu bahis gönderme dahil olmak üzere entegrasyonun tüm aşamalarında testler gerçekleştirin.

Yanıt alanları ve hata açıklaması

Yanıt Alanları

ParametreAçıklama
betCodeSistemimizdeki benzersiz bahis numarası
errorCodeİstek sonucunun ana durumu
fullErrorCodeHata detayları
errorMessageSistem hatası metin mesajları
AmountOutPotansiyel kazanç miktarı
CountEventsKuponda yer alan bahislerin sayısı
CoefSonuç katsayıları
IsLiveBahis türü: canlı veya maç öncesi (true/false)
LinesIdMaç kimliği
EventDateMaç tarihi

Bahis Gönderimi İçin Hata Açıklaması

Bahis gönderilirken çeşitli hatalar oluşabilir. Sunucu yanıtı üç temel alan içerir:

  • errorCode: Ana istek durumu.
  • fullErrorCode: Hata detayları.
  • errorMessage: Hatanın metinsel açıklaması.

Başarılı işlem

Başarılı işlem json
{
  "errorCode": 0,
  "fullErrorCode": 0,
  "errorMessage": ""
}

Hata kodları

Bahis başarıyla kabul edilirse sunucu başarılı yanıtı döndürür (yukarıya bakın). Kupon kabul edilmiştir ve herhangi bir hata yoktur.

Bir hata oluşursa sunucu genel bir hata yanıtı döndürür (yukarıya bakın). Olası hatalardan biri meydana gelmiştir. Hata kodları ve mesajları aşağıda listelenmiştir.

Olası Hata Kodları ve Açıklamaları

Hata Kodu (fullErrorCode)Hata Mesajı (errorMessage)Açıklama
1error_wrong_bet_dataYanlış bahis verileri. list_bets parametresini ve diğer gerekli alanları kontrol edin.
1error_block_bet_dataBahis geçici olarak engellenmiştir ve kabul edilemez.
1error_repeat_bet_dataTek bir maçtan aynı sonuca mükerrer bahis yapılmasına izin verilmez.
2label_change_rateOranlar değişti. Belirtilen ve güncel oranlar arasındaki uyumsuzluk nedeniyle kupon reddedildi.
3error_exist_betBelirtilen bahis sonucu artık mevcut değil. Verilerin doğruluğunu kontrol edin.
99Invalid access levelKullanıcı bu işlemi gerçekleştirmek için gerekli yetkilere sahip değil. Büyük olasılıkla yeniden yetkilendirme gerekiyor, çerezler eksik veya hesap engellenmiş.
99Error exist remote host!remote_host parametresi yanlış veya eksik. Sunucu ayarlarınızı kontrol edin.

Hata İşleme İçin Öneriler

  • Giriş Verisi Doğrulaması: Tüm gerekli parametrelerin doğru şekilde sağlandığından emin olun. list_bets biçimini ve tüm zorunlu alanların varlığını kontrol edin.
  • Oranlarla Çalışma: rate_mode = reject kullanılıyorsa, oran değişiklikleriyle ilgili hataları (label_change_rate) ele alın.
  • Sunucu Yapılandırması: Sunucunuzun remote_host parametresinde doğru şekilde belirtildiğinden emin olun.
  • Hata Günlüğü: Hata ayıklamayı ve destek ekibiyle etkileşimi kolaylaştırmak için tüm hataları (errorCode, fullErrorCode, errorMessage) günlüğe kaydedin.
  • Kritik Hatalar İçin Eylemler: Seviye 99 hataları durumunda kendi tarafınızdaki erişim yetkilerini ve API yapılandırmalarını kontrol edin.
Genel hata json
{
  "errorCode": 1,
  "fullErrorCode": [ERROR_CODE],
  "errorMessage": "[ERROR_DESCRIPTION]"
}

Oranlar değiştiğinde hataları işlemek için öneriler

Oranlar değiştiğinde hataları işlemek için öneriler json
{
    "errorCode":1,
    "fullErrorCode":2,
    "errorMessage":"Odds have changed",
    "rate_mode":"reject",
    "changed":[
        {
            "gid":"586464528", // match ID
            "rb":2.15, // odds in your coupon
            "rg":"2.27", // current real odds
            "rt":0 // status of change. 0 - decreased, 1 - increased
        }
    ]
}

Hesaplama sonuçlarını gönderme

Sistemimize bir bahis eklendiğinde ve hesaplandığında, kupon sonuçlarını sunucunuza göndeririz. Bunlar şunları içerebilir:

  • Kupon sonuçları (tam hesaplama).
  • Kupon durumları (kazanma, kaybetme, iade).

İstekler, remote_host parametresinde belirttiğiniz adrese gönderilir. Bu adrese otomatik olarak /api/bet/result dizesi eklenir. Sunucunuzun bu yolda veri alacak şekilde yapılandırıldığından emin olun.

Nihai Adres Örneği:

remote_host = https://mysite.com belirttiyseniz verileri şuraya göndeririz: https://mysite.com/api/bet/result.

Tek bir kupon için örnek veri json
{
    "remote_host": "https://mysite.com",
    "Heads": [{
        "KeyHead": {
            "Id": "344143",
            "BarCode": "x9c52i8411"
        },
        "Status": 2,
        "ExtStatus": 0,
        "AmountOut": 11130,
        "DateReceive": "1597075782"
    }]
}

Birden fazla kupon için örnek veri

Alan Açıklamaları

AlanAçıklama
remote_hostVerilerin gönderildiği sunucunuzun adresi.
IdSistemimizdeki bahsin benzersiz kimliği. Çoğu durumda yoksayılır.
BarCodeBenzersiz kupon numarası.
StatusKuponun mevcut durumu. Olası değerler: 2 — kazanma, 4 — kaybetme.
ExtStatusİade durumunda ek durum: 0 — değişiklik yok, 1 — bir veya daha fazla sonuç değişen katsayı ile hesaplandı.
AmountOutKazanç miktarı (kupon kazandıysa).
DateReceiveKuponun hesaplandığı saat ve tarih.

Status ve ExtStatus Nasıl Yorumlanır

  • Status = 2 and ExtStatus = 0: Kupon kazandı.
  • Status = 4 and ExtStatus = 0: Kupon kaybetti.
  • Status = 2 and ExtStatus = 1: İade. Kupon 1 katsayısıyla hesaplandı.

Entegrasyon İçin Önemli Noktalar

  • ExtStatus = 1 İşleme: Bu, bir maç iptal edildiğinde veya erken sona erdiğinde meydana gelebilir. Bu gibi durumlarda tüm bahisler 1 katsayısı ile hesaplanır.
  • Teknik Gereksinimler: İstekler POST yöntemi kullanılarak gönderilir. Sunucunuz remote_host + /api/bet/result yolunda JSON verilerini kabul etmeye hazır olmalıdır.
Birden fazla kupon için örnek veri json
{
    "remote_host": "https://mysite.com",
    "Heads": [{
        "KeyHead": {
            "Id": "313",
            "BarCode": "75vz48t935"
        },
        "Status": 2,
        "ExtStatus": 0,
        "AmountOut": 19.85,
        "DateReceive": "1592937968"
    }, {
        "KeyHead": {
            "Id": "312",
            "BarCode": "77i0r6e15t"
        },
        "Status": 2,
        "ExtStatus": 0,
        "AmountOut": 12.51,
        "DateReceive": "1592937280"
    }]
}