S P O R T A P I
Support

Technical Documentation: System Integration for Bet and Coupon Calculation.

This system is designed for sports betting operators, bookmakers, and platform developers who aim to automate the process of bet calculation and coupon management. It allows for quick integration of result calculations, providing accurate data on coupon statuses (win, loss, or refund), and simplifies the interaction between the operator's server and the calculation system.

How Does the Odds and Outcomes Calculation System Work?

Integration with our bet and coupon calculation system consists of three key stages:

Step 1: Authorization

In the first stage, you need to authorize in the system. This is done by performing a POST request with user credentials (login and password). Successful authorization returns a session represented as a cookie, which must be saved. These cookies are required for all subsequent requests as they are used to identify the user's session in the system.

Step 2: Sending a Bet

At this stage, a bet code is sent to our system containing:

  • Match ID, corresponding to the event.
  • Bet code, describing the selected outcome (e.g., team win, handicap, or total).
  • Bet odds, valid at the time of submission.

When submitting data, the cookies obtained during authorization must be included. This ensures proper user identification and bet processing.

Step 3: Receiving Results

After the outcomes or coupons are calculated, our system sends POST requests to the specified remote_host. This request includes:

  • Coupon status (win, loss, or refund).
  • Statuses of all outcomes included in the coupon.

Results are sent as soon as the outcome is determined. For example:

  • If the bet was placed on an intermediate outcome (e.g., handicap 2.5, and the third goal is scored), the calculation may be performed during the match.
  • If the bet is on the final result (e.g., team win), the status information will be sent immediately after the match ends.

Now review each step individually. We have described the requests, parameters, and API responses in detail.

User Authorization

Login, password, and the host for sending requests can be obtained from the manager.

Request URL:

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

Data Submission Type: POST

Submitted Data:

Parameter Description
login User login
password User password

Important!

  • During authorization, the response includes cookies. These cookies must be saved and sent with subsequent requests.

Recommendations for easier integration:

  • Ensure the login field is passed as a string.
  • Verify the correct saving and sending of cookies, as this affects the execution of subsequent requests.
  • In case of an error, the request will return an empty object. Make sure to handle this scenario appropriately.

Cookies are valid for 3 months. However, they may be reset if the server is restarted. Therefore, you need to reauthorize if you encounter an error while saving a coupon.


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

Example of Sending a Request:

Use the data provided to you by the manager:


    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'
    }
    
    response = requests.request("POST", url, headers=headers, data=payload)
    
    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();

Example Response:

Successful:

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

Unsuccessful:

{"d":{}}

Response Fields Description:

Field Description
UserId Unique user identifier
d Root object of the response

General Recommendations:

  • Before the first request, ensure the user has entered the correct credentials.
  • Set up error handling to display the reasons for failed authorization to the user (e.g., incorrect login or password).
  • Log both successful and unsuccessful attempts for analysis and monitoring.

Cookies must be saved and sent with subsequent requests.

Bet or Coupon Submission Method

To submit a bet, you must use the cookies obtained during the authorization stage. These data are required to identify your session and process requests.

Request URL:

{HOST_API}/bet/place/
Example Body Payload:

{
    "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"
    }
}
Field Descriptions
Parameter Description
list_bets Bet code and odds.
Format: "event_type#match_ID|bet_code#odds".
Example: "live#579216393|1|1|0#2.1"
realAmount Bet amount. Must be passed as a string, e.g., "150".
currency Coupon currency.
lang The language in which the bet and coupon are saved. For example: "en", "ru", or "tr".
remote_host The URL to send the coupon calculation results to. Do not include a trailing slash.
rate_mode Option for handling coupon acceptance when odds change: "reject" (reject on changes) or "accept" (accept regardless of changes). Default: "accept".

Note: Ensure that parameters are passed in the correct format. For example, list_bets must be an array, even if there is only one bet.

We do not validate the bet amount. You can submit either the actual bet amount or any arbitrary value. This is to ensure the confidentiality of your financial data. Our task is to provide calculation results. You are responsible for crediting winnings to your players.

Required Parameters for Submitting a Bet:

  • list_bets — contains information about the bet and the corresponding match.
  • remote_host — the URL to which we will send the calculation results for the coupon or outcome.
  • rate_mode — determines how the system handles odds changes.

Other parameters should also be sent, but they are optional and can be used for your convenience.

Description of the remote_host Parameter

remote_host is the address of your server where we send requests with the results of bet calculations. This host must be configured to accept requests from our server. Below are examples of possible values and specific details about working with this parameter.

You can specify various options for remote_host:

  • Simple host: https://mysites.com
  • Host with port: https://mysites.com:78665
  • Host with additional paths: https://mysites.com/request/sportapi/sender
  • Host with parameters: https://mysites.com/request.php?action=webhook

Important: When sending a request, our system automatically appends the string /api/bet/result to the specified remote_host.
Thus, the final address for receiving requests is formed as remote_host + "/api/bet/result". Ensure that your server is configured to receive data at this path.

Examples:
  • You specify remote_host = https://mysites.com. We send requests to: https://mysites.com/api/bet/result.
  • You specify remote_host = https://mysites.com/request.php?action=webhook. We send requests to: https://mysites.com/request.php?action=webhook/api/bet/result.

Technical Details:

  • Requests are sent using the POST method.
  • Your server must be ready to accept JSON data that we send.
  • Your server must return a 200 status code upon successful data receipt.

Ensure that your server correctly processes the specified path and requests. The next section provides an example of the data structure sent by our server.

Description of the rate_mode Parameter

The rate_mode parameter defines the system's behavior when odds change. It can take two values:

  • accept: In this mode, the coupon will be accepted with the current odds, even if they have changed. For example, a player adds a bet "Manchester Wins" with odds of 2.02. While they press the "Place Bet" button, the odds change to 1.37 or 2.78. In the accept mode, the system saves the coupon with the new odds without notifying your system.
  • reject: In this mode, the system rejects the coupon if the odds have changed. The response will include an error notifying that the odds have changed.

Choose the mode that best suits your business processes and provides convenience for your users.

Important Recommendations

  1. JSON Formatting: Ensure that the data is properly serialized into JSON format before sending.
  2. Cookies: Include the cookies obtained during authorization to successfully identify the user's session.
  3. Error Handling: Handle server responses, especially cases where errorCode = 1 is returned.
  4. Testing: Conduct tests at all stages of integration, including sending single and multiple bets.
Response Fields
Parameter Description
betCode Unique bet number in our system
errorCode Main status of the request result
fullErrorCode Error details
errorMessage System error text messages
AmountOut Potential win amount
CountEvents Number of bets in the coupon
Coef Outcome coefficients
IsLive Bet type: live or pre-match (true/false)
LinesId Match ID
EventDate Match date

Error Description for Bet Submission

Various errors may occur when submitting a bet. The server response contains three key fields:

  • errorCode: Main request status.
  • fullErrorCode: Error details.
  • errorMessage: Text description of the error.
Successful Operation

If the bet is successfully accepted, the server returns:

{
  "errorCode": 0,
  "fullErrorCode": 0,
  "errorMessage": ""
}

Description: The coupon has been accepted, and there are no errors.

General Error

If an error occurs, the server returns:

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

Description: One of the possible errors occurred. Below are the error codes and messages.

Possible Error Codes and Descriptions
Error Code (fullErrorCode) Error Message (errorMessage) Description
1 error_wrong_bet_data Incorrect bet data. Check the list_bets parameter and other required fields.
1 error_block_bet_data The bet is temporarily blocked and cannot be accepted.
1 error_repeat_bet_data Duplicate bets on the same outcome from one match are not allowed.
2 label_change_rate The odds have changed. The coupon was rejected due to a mismatch between the specified and current odds.
3 error_exist_bet The specified bet outcome no longer exists. Check the data for accuracy.
99 Invalid access level The user does not have the rights to perform this operation. Most likely, reauthorization is required, cookies are missing, or the account is blocked.
99 Error exist remote host! The remote_host parameter is incorrect or missing. Check your server settings.
Recommendations for Handling Errors When Odds Have Changed
 
{
    "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
        }
    ]
}

Recommendations for Error Handling

  • Input Data Validation:
    • Ensure that all required parameters are provided correctly.
    • Check the format of list_bets and the presence of all mandatory fields.
  • Working with Odds: If rate_mode = reject is used, handle errors related to odds changes (label_change_rate).
  • Server Configuration: Ensure that your server is correctly specified in the remote_host parameter.
  • Error Logging: Log all errors (errorCode, fullErrorCode, errorMessage) to simplify debugging and interaction with support.
  • Actions for Critical Errors:
    • In case of level 99 errors, check access rights and API configurations on your side.

Sending Calculation Results and Coupon Statuses from Our Server to Your Server

When a bet is added to our system and calculated, we send the coupon results to your server. These can include:

  • Coupon results (full calculation).
  • Coupon statuses (win, loss, refund).

Requests are sent to the address you specified in the remote_host parameter. The string /api/bet/result is automatically appended to this address. Ensure that your server is configured to receive data at this path.

Example of the Final Address:

If you specified: remote_host = https://mysite.com, we will send data to: https://mysite.com/api/bet/result.

Example Data for a Single Coupon
{
    "remote_host": "https://mysite.com",
    "Heads": [{
        "KeyHead": {
            "Id": "344143",
            "BarCode": "x9c52i8411"
        },
        "Status": 2,
        "ExtStatus": 0,
        "AmountOut": 11130,
        "DateReceive": "1597075782"
    }]
}
Example Data for Multiple Coupons
{
    "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"
    }]
}

Field Descriptions

Field Description
remote_host The address of your server where data is sent.
Id Unique identifier of the bet in our system. Ignored in most cases.
BarCode Unique coupon number.
Status Current status of the coupon. Possible values:
2 — win,
4 — loss.
ExtStatus Additional status in case of a refund:
0 — no changes,
1 — one or more outcomes were calculated with a changed coefficient.
AmountOut Win amount (if the coupon won).
DateReceive The time and date when the coupon was calculated.
How to Interpret Status and ExtStatus
  • Status = 2 and ExtStatus = 0: The coupon won.
  • Status = 4 and ExtStatus = 0: The coupon lost.
  • Status = 2 and ExtStatus = 1: Refund. The coupon was calculated with a coefficient of 1.

Important Points for Integration

  • Handling ExtStatus = 1: This may occur if a match was canceled or ended prematurely. In such cases, all bets are calculated with a coefficient of 1.
  • Technical Requirements:
    • Requests are sent using the POST method.
    • Your server must be ready to accept JSON data at the path remote_host + /api/bet/result.