SportApi
API-Dokumentation

Systemintegration für die Wett- und Couponabrechnung

Dieses System ist für Sportwettenanbieter, Buchmacher und Plattform-Entwickler konzipiert, die den Prozess der Wettabrechnung und des Coupon-Managements automatisieren möchten. Es ermöglicht eine schnelle Integration der Ergebnisabrechnung, bietet präzise Daten über Coupon-Status (Gewinn, Verlust oder Rückerstattung) und vereinfacht die Interaktion zwischen dem Server des Betreibers und dem Abrechnungssystem.

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"
}

Wie funktioniert das System?

Wie funktioniert das Abrechnungssystem für Quoten und Ausgänge?

Die Integration mit unserem Wett- und Couponabrechnungssystem erfolgt in drei wesentlichen Phasen:

Phase 1: Autorisierung

In der ersten Phase müssen Sie sich im System autorisieren. Dies geschieht über einen POST-Request mit den Benutzerdaten (Login und Passwort). Eine erfolgreiche Autorisierung gibt eine Session in Form eines Cookies zurück, das gespeichert werden muss. Diese Cookies sind für alle nachfolgenden Anfragen erforderlich, da sie zur Identifizierung der Benutzersitzung im System dienen.

Phase 2: Wettabgabe

In dieser Phase wird ein Wettcode an unser System gesendet, der Folgendes enthält:

  • Spiel-ID, die dem Ereignis entspricht.
  • Wettcode, der den ausgewählten Ausgang beschreibt (z. B. Teamsieg, Handicap oder Total).
  • Wettquote, die zum Zeitpunkt der Abgabe aktuell ist.

Bei der Übertragung der Daten müssen die bei der Autorisierung erhaltenen Cookies mitgesendet werden. Dies stellt die korrekte Identifizierung des Benutzers und die Verarbeitung der Wette sicher.

Phase 3: Ergebniserhalt

Nach der Abrechnung der Ausgänge oder Coupons sendet unser System POST-Requests an den angegebenen remote_host. Diese Anfrage enthält:

  • Coupon-Status (Gewinn, Verlust oder Rückerstattung).
  • Status aller im Coupon enthaltenen Ausgänge.

Die Übermittlung der Ergebnisse erfolgt in dem Moment, in dem der Ausgang bestimmt wird. Zum Beispiel:

  • Wenn die Wette auf ein Zwischenergebnis platziert wurde (z. B. Handicap 2.5 und das dritte Tor wurde erzielt), kann die Abrechnung direkt während des Spiels erfolgen.
  • Wenn die Wette auf das Endergebnis platziert wurde (z. B. Teamsieg), wird die Statusinformation unmittelbar nach Spielende gesendet.

Sehen Sie sich nun jeden Schritt einzeln an. Wir haben die Anfragen, Parameter und Antworten der REST-API im Detail beschrieben.

Benutzerautorisierung

Login, Passwort und Host zum Senden von Anfragen erhalten Sie von Ihrem Manager.

Request-URL:

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

Datentransfer-Typ: POST

Übertragene Daten:

ParameterBeschreibung
loginBenutzer-Login
passwordBenutzer-Passwort

Wichtig!

  • Während der Autorisierung enthält die Antwort Cookies. Diese Cookies müssen gespeichert und bei nachfolgenden Anfragen mitgesendet werden.

Empfehlungen for eine einfache Integration:

  • Stellen Sie sicher, dass das Feld login als String übertragen wird.
  • Überprüfen Sie das korrekte Speichern und Senden der Cookies, da die Ausführung nachfolgender Anfragen davon abhängt.
  • Im Fehlerfall gibt die Anfrage ein leeres Objekt zurück. Stellen Sie sicher, dass Sie dieses Szenario abfangen.

Cookies sind 3 Monate lang gültig. Sie können jedoch bei einem Server-Neustart zurückgesetzt werden. Daher müssen Sie sich erneut autorisieren, wenn beim Speichern eines Coupons ein Fehler auftritt.

Fehlerantwort json
"errorCode":1,
"fullErrorCode":99,
"errorMessage":"Invalid access level"

Beispiel für das Senden einer Anfrage (verwenden Sie die vom Manager bereitgestellten Daten):

Beispielantwort:

Erfolgreich:

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

Fehlgeschlagen:

{"d":{}}

Beschreibung der Antwortfelder:

FeldBeschreibung
UserIdEindeutige Benutzer-ID
dRoot-Objekt der Antwort

Allgemeine Empfehlungen:

  • Stellen Sie vor der ersten Anfrage sicher, dass der Benutzer die korrekten Zugangsdaten eingegeben hat.
  • Richten Sie eine Fehlerbehandlung ein, um dem Benutzer die Gründe für das Fehlschlagen der Autorisierung anzuzeigen (z. B. falscher Login oder Passwort).
  • Protokollieren Sie erfolgreiche und fehlgeschlagene Versuche zur Analyse und Überwachung.

Cookies müssen gespeichert und bei nachfolgenden Anfragen mitgesendet werden.

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)

Methode zur Wett- oder Couponabgabe

Um eine Wette zu senden, müssen Sie die in der Autorisierungsphase erhaltenen Cookies verwenden. Diese Daten sind erforderlich, um Ihre Sitzung zu identifizieren und Anfragen zu verarbeiten.

Request-URL:

{HOST_API}/bet/place/
Beispiel für den Request-Body 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"
    }
}

Parameter remote_host und rate_mode

Beschreibung der Felder

ParameterBeschreibung
list_betsWettcode und Quoten. Format: "Ereignistyp#Spiel_ID|Wettcode#Quote". Beispiel: "live#579216393|1|1|0#2.1"
realAmountWetteinsatz. Wird als String angegeben, z. B. "150".
currencyCoupon-Währung.
langDie Sprache, in der die Wette und der Coupon gespeichert werden. Zum Beispiel: "en", "ru" oder "tr".
remote_hostDie URL, an die die Ergebnisse der Couponabrechnung gesendet werden. Bitte ohne abschließenden Schrägstrich angeben.
rate_modeOption zur Annahme des Coupons bei Quotenänderungen: "reject" (bei Änderungen ablehnen) oder "accept" (bei allen Änderungen annehmen). Standardmäßig: "accept".

Hinweis: Stellen Sie sicher, dass Parameter im korrekten Format übergeben werden. Beispielsweise muss list_bets ein Array sein, selbst wenn nur eine Wette platziert wird.

Wir überprüfen den Wetteinsatz nicht. Sie können sowohl den realen Wetteinsatz als auch jeden beliebigen Wert übermitteln. Dies dient der Gewährleistung der Vertraulichkeit Ihrer Finanzdaten. Unsere Aufgabe ist es, die Abrechnungsergebnisse bereitzustellen. Die Auszahlung der Gewinne an Ihre Spieler führen Sie selbst durch.

Erforderliche Parameter zum Senden einer Wette:

  • list_bets — enthält Informationen über die Wette und das entsprechende Spiel.
  • remote_host — die URL, an die wir die Ergebnisse der Coupon- oder Ausgangsabrechnung senden.
  • rate_mode — bestimmt, wie das System mit Quotenänderungen verfährt.

Die übrigen Parameter sollten ebenfalls gesendet werden, sind jedoch optional und können nach eigenem Ermessen genutzt werden.

Beschreibung des Parameters remote_host

remote_host is die Adresse Ihres Servers, an die wir Anfragen mit den Ergebnissen der Wettabrechnung senden. Dieser Host muss so konfiguriert sein, dass er Anfragen von unserem Server akzeptiert. Nachfolgend finden Sie Beispiele für mögliche Werte und Besonderheiten bei der Arbeit mit diesem Parameter.

Sie können verschiedene Optionen für remote_host angeben:

  • Einfacher Host: https://meineseite.de
  • Host mit Port: https://meineseite.de:78665
  • Host mit zusätzlichen Pfaden: https://meineseite.de/request/sportapi/sender
  • Host mit Parametern: https://meineseite.de/request.php?action=webhook

Wichtig: Beim Senden einer Anfrage fügt unser System dem angegebenen remote_host automatisch den String /api/bet/result hinzu. Somit bildet sich die endgültige Adresse für den Empfang von Anfragen als remote_host + "/api/bet/result". Stellen Sie sicher, dass Ihr Server so konfiguriert ist, dass er Daten unter diesem Pfad empfängt.

Beispiele:
  • Sie übergeben remote_host = https://meineseite.de. Wir senden Anfragen an: https://meineseite.de/api/bet/result.
  • Sie übergeben remote_host = https://meineseite.de/request.php?action=webhook. Wir senden Anfragen an: https://meineseite.de/request.php?action=webhook/api/bet/result.

Technische Details:

  • Anfragen werden per POST-Methode gesendet.
  • Ihr Server muss bereit sein, JSON-Daten zu empfangen, die wir senden.
  • Ihr Server muss bei erfolgreichem Datenempfang den Statuscode 200 zurückgeben.

Stellen Sie sicher, dass Ihr Server den angegebenen Pfad und die Anfragen korrekt verarbeitet. Der folgende Abschnitt zeigt ein Beispiel für die Datenstruktur, die von unserem Server gesendet wird.

Beschreibung des Parameters rate_mode

Der Parameter rate_mode legt das Verhalten des Systems bei Quotenänderungen fest. Er kann zwei Werte annehmen:

  • accept: In diesem Modus wird der Coupon mit der aktuellen Quote angenommen, selbst wenn sie sich geändert hat. Beispiel: Ein Spieler fügt dem Coupon eine Wette „Manchester gewinnt“ mit einer Quote von 2.02 hinzu. Während er den Button „Wette platzieren“ drückt, ändert sich die Quote auf 1.37 oder 2.78. Im Modus accept speichert das System den Coupon mit die neuen Quote, ohne Ihr System zu benachrichtigen.
  • reject: In diesem Modus lehnt das System den Coupon ab, wenn sich die Quote geändert hat. Die Antwort enthält einen Fehler mit dem Hinweis, dass sich die Quote geändert hat.

Wählen Sie den Modus, der am besten zu Ihren Geschäftsprozessen passt und für Ihre Benutzer am komfortabelsten ist.

Wichtige Empfehlungen

  1. JSON-Formatierung: Stellen Sie sicher, dass die Daten vor dem Senden korrekt in das JSON-Format serialisiert werden.
  2. Cookies: Übergeben Sie die bei der Autorisierung erhaltenen Cookies zur erfolgreichen Identifizierung der Benutzersitzung.
  3. Fehlerbehandlung: Verarbeiten Sie Serverantworten, insbesondere Fälle, in denen errorCode = 1 zurückgegeben wird.
  4. Testen: Führen Sie Tests in allen Phasen der Integration durch, einschließlich des Sendens einzelner und mehrerer Wetten.

Antwortfelder und Fehlerbeschreibung

Antwortfelder

ParameterBeschreibung
betCodeEindeutige Wettnummer in unserem System
errorCodeHauptstatus des Anfrageergebnisses
fullErrorCodeDetaillierung von Fehlern
errorMessageTextuelle Systemfehlermeldungen
AmountOutMöglicher Gewinnbetrag
CountEventsAnzahl der Wetten im Coupon
CoefQuoten des Ausgänge
IsLiveWettart: Live oder vor dem Spiel (true/false)
LinesIdSpiel-ID
EventDateSpieldatum

Beschreibung von Fehlern bei der Wettabgabe

Bei der Wettabgabe können verschiedene Fehler auftreten. Die Serverantwort enthält drei Schlüsselfelder:

  • errorCode: Hauptstatus der Anfrage.
  • fullErrorCode: Detaillierung des Fehlers.
  • errorMessage: Textbeschreibung des Fehlers.

Erfolgreicher Vorgang

Erfolgreicher Vorgang json
{
  "errorCode": 0,
  "fullErrorCode": 0,
  "errorMessage": ""
}

Fehlercodes

Wenn die Wette erfolgreich angenommen wurde, gibt der Server eine Erfolgsantwort zurück (siehe oben). Der Coupon wurde angenommen, es liegen keine Fehler vor.

Wenn ein Fehler aufgetreten ist, gibt der Server eine allgemeine Fehlerantwort zurück (siehe oben). Einer der möglichen Fehler ist aufgetreten. Nachfolgend finden Sie die Fehlercodes und -meldungen.

Mögliche Fehlercodes und -beschreibungen

Fehlercode (fullErrorCode)Fehlermeldung (errorMessage)Beschreibung
1error_wrong_bet_dataUngültige Wettdaten. Überprüfen Sie den Parameter list_bets und andere Pflichtfelder.
1error_block_bet_dataDie Wette ist vorübergehend gesperrt und kann nicht angenommen werden.
1error_repeat_bet_dataDas Wiederholen einer Wette auf denselben Ausgang desselben Spiels ist nicht zulässig.
2label_change_rateDie Quote hat sich geändert. Der Coupon wurde abgelehnt, da die angegebene und die aktuelle Quote nicht übereinstimmen.
3error_exist_betDieser Wettausgang existiert nicht mehr. Überprüfen Sie die Aktualität der Daten.
99Ungültige ZugriffsebeneDer Benutzer hat keine Berechtigung für diese Operation. Wahrscheinlich ist eine erneute Autorisierung erforderlich, Cookies sind abgelaufen oder das Konto ist gesperrt.
99Error exist remote host!Ungültiger oder fehlender Parameter remote_host. Überprüfen Sie Ihre Serverkonfiguration.

Empfehlungen zur Fehlerbehandlung

  • Eingabedaten validieren: Stellen Sie sicher, dass alle erforderlichen Parameter korrekt übergeben werden. Überprüfen Sie das Format von list_bets und das Vorhandensein aller Pflichtfelder.
  • Arbeit mit Quoten: Wenn Sie rate_mode = reject verwenden, behandeln Sie Fehler im Zusammenhang mit Quotenänderungen (label_change_rate).
  • Serverkonfiguration: Stellen Sie sicher, dass Ihr Server im Parameter remote_host korrekt angegeben ist.
  • Fehlerprotokollierung: Protokollieren Sie alle Fehler (errorCode, fullErrorCode, errorMessage), um das Debugging und die Interaktion mit dem Support zu vereinfachen.
  • Maßnahmen bei kritischen Fehlern: Überprüfen Sie bei Fehlern des Levels 99 die Zugriffsrechte und die API-Einstellungen auf Ihrer Seite.
Allgemeiner Fehler json
{
  "errorCode": 1,
  "fullErrorCode": [ERROR_CODE],
  "errorMessage": "[ERROR_DESCRIPTION]"
}

Empfehlungen zur Fehlerbehandlung bei geänderten Quoten

Empfehlungen zur Fehlerbehandlung bei geänderten Quoten 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
        }
    ]
}

Übermittlung der Abrechnungsergebnisse

Wenn eine Wette in unser System aufgenommen und abgerechnet wurde, senden wir die Ergebnisse des Coupons an Ihren Server. Dies können sein:

  • Ergebnisse des Coupons (vollständige Abrechnung).
  • Status des Coupons (Gewinn, Verlust, Rückerstattung).

Anfragen werden an die von Ihnen im Parameter remote_host angegebene Adresse gesendet. An diese Adresse wird automatisch der String /api/bet/result angehängt. Stellen Sie sicher, dass Ihr Server so konfiguriert ist, dass er Daten unter diesem Pfad empfängt.

Beispiel für die endgültige Adresse:

Wenn Sie übergeben haben: remote_host = https://meineseite.de, senden wir die Daten an: https://meineseite.de/api/bet/result.

Beispielhafte Daten für einen einzelnen Coupon json
{
    "remote_host": "https://mysite.com",
    "Heads": [{
        "KeyHead": {
            "Id": "344143",
            "BarCode": "x9c52i8411"
        },
        "Status": 2,
        "ExtStatus": 0,
        "AmountOut": 11130,
        "DateReceive": "1597075782"
    }]
}

Beispielhafte Daten für mehrere Coupons

Beschreibung der Felder

FeldBeschreibung
remote_hostDie Adresse Ihres Servers, an die die Daten gesendet werden.
IdEindeutige Kennung der Wette in unserem System. Wird in den meisten Fällen ignoriert.
BarCodeEindeutige Nummer des Coupons.
StatusAktueller Status des Coupons. Mögliche Werte: 2 — Gewinn, 4 — Verlust.
ExtStatusZusätzlicher Status bei Rückerstattung: 0 — keine Änderungen, 1 — einer oder mehrere Ausgänge wurden mit einer geänderten Quote abgerechnet.
AmountOutGewinnbetrag (wenn der Coupon gewonnen hat).
DateReceiveZeit und Datum der Couponabrechnung.

Wie man Status und ExtStatus interpretiert

  • Status = 2 und ExtStatus = 0: Der Coupon hat gewonnen.
  • Status = 4 und ExtStatus = 0: Der Coupon hat verloren.
  • Status = 2 und ExtStatus = 1: Rückerstattung. Der Coupon wurde mit der Quote 1 abgerechnet.

Wichtige Aspekte für die Integration

  • Behandlung von ExtStatus = 1: Dies kann vorkommen, wenn ein Spiel abgesagt oder vorzeitig beendet wurde. In solchen Fällen werden alle Wetten mit der Quote 1 abgerechnet.
  • Technische Anforderungen: Anfragen werden mit der Methode POST gesendet. Ihr Server muss bereit sein, JSON-Daten unter dem Pfad remote_host + /api/bet/result zu empfangen.
Beispielhafte Daten für mehrere Coupons 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"
    }]
}