Systemintegration für die Wett- und Couponabrechnung

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.

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:

Parameter	Beschreibung
login	Benutzer-Login
password	Benutzer-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.

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

Beispielantwort:

Erfolgreich:

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

Fehlgeschlagen:

{"d":{}}

Beschreibung der Antwortfelder:

Feld	Beschreibung
UserId	Eindeutige Benutzer-ID
d	Root-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.

import requests
import json

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

payload = json.dumps({
  "login": "demo-login@demosportapi.net",
  "password": "demo-password"
})
headers = {
  'Content-Type': 'application/json'
}

print(response.text)

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://example-domain-calc.com/WebServices/BCService.asmx/LogIn/',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
    "login":"demo-login@demosportapi.net",
    "password":"demo-password"
}',
    CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
    ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");

const raw = JSON.stringify({
    "login": "demo-login@demosportapi.net",
    "password": "demo-password"
});

const requestOptions = {
    method: "POST",
    headers: myHeaders,
    body: raw,
    redirect: "follow"
};

fetch("https://example-domain-calc.com/WebServices/BCService.asmx/LogIn/", requestOptions)
    .then((response) => response.text())
    .then((result) => console.log(result))
    .catch((error) => console.error(error));

OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n    \"login\":\"demo-login@demosportapi.net\",\r\n    \"password\":\"demo-password\"\r\n}");
Request request = new Request.Builder()
.url("https://example-domain-calc.com/WebServices/BCService.asmx/LogIn/")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();

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/

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

Beschreibung der Felder

Parameter	Beschreibung
list_bets	Wettcode und Quoten. Format: "Ereignistyp#Spiel_ID|Wettcode#Quote". Beispiel: "live#579216393|1|1|0#2.1"
realAmount	Wetteinsatz. Wird als String angegeben, z. B. "150".
currency	Coupon-Währung.
lang	Die Sprache, in der die Wette und der Coupon gespeichert werden. Zum Beispiel: "en", "ru" oder "tr".
remote_host	Die URL, an die die Ergebnisse der Couponabrechnung gesendet werden. Bitte ohne abschließenden Schrägstrich angeben.
rate_mode	Option 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

Parameter	Beschreibung
betCode	Eindeutige Wettnummer in unserem System
errorCode	Hauptstatus des Anfrageergebnisses
fullErrorCode	Detaillierung von Fehlern
errorMessage	Textuelle Systemfehlermeldungen
AmountOut	Möglicher Gewinnbetrag
CountEvents	Anzahl der Wetten im Coupon
Coef	Quoten des Ausgänge
IsLive	Wettart: Live oder vor dem Spiel (true/false)
LinesId	Spiel-ID
EventDate	Spieldatum

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.

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
1	error_wrong_bet_data	Ungültige Wettdaten. Überprüfen Sie den Parameter list_bets und andere Pflichtfelder.
1	error_block_bet_data	Die Wette ist vorübergehend gesperrt und kann nicht angenommen werden.
1	error_repeat_bet_data	Das Wiederholen einer Wette auf denselben Ausgang desselben Spiels ist nicht zulässig.
2	label_change_rate	Die Quote hat sich geändert. Der Coupon wurde abgelehnt, da die angegebene und die aktuelle Quote nicht übereinstimmen.
3	error_exist_bet	Dieser Wettausgang existiert nicht mehr. Überprüfen Sie die Aktualität der Daten.
99	Ungültige Zugriffsebene	Der Benutzer hat keine Berechtigung für diese Operation. Wahrscheinlich ist eine erneute Autorisierung erforderlich, Cookies sind abgelaufen oder das Konto ist gesperrt.
99	Error 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.

{
  "errorCode": 1,
  "fullErrorCode": [ERROR_CODE],
  "errorMessage": "[ERROR_DESCRIPTION]"
}

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.

{
    "remote_host": "https://mysite.com",
    "Heads": [{
        "KeyHead": {
            "Id": "344143",
            "BarCode": "x9c52i8411"
        },
        "Status": 2,
        "ExtStatus": 0,
        "AmountOut": 11130,
        "DateReceive": "1597075782"
    }]
}

Beschreibung der Felder

Feld	Beschreibung
remote_host	Die Adresse Ihres Servers, an die die Daten gesendet werden.
Id	Eindeutige Kennung der Wette in unserem System. Wird in den meisten Fällen ignoriert.
BarCode	Eindeutige Nummer des Coupons.
Status	Aktueller Status des Coupons. Mögliche Werte: 2 — Gewinn, 4 — Verlust.
ExtStatus	Zusätzlicher Status bei Rückerstattung: 0 — keine Änderungen, 1 — einer oder mehrere Ausgänge wurden mit einer geänderten Quote abgerechnet.
AmountOut	Gewinnbetrag (wenn der Coupon gewonnen hat).
DateReceive	Zeit 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.

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