Интеграция системы для расчёта ставок и купонов

Как работает система расчёта шансов и исходов?

Интеграция с нашей системой расчёта ставок и купонов проходит в три ключевых этапа:

Этап 1: Авторизация

На первом этапе необходимо авторизоваться в системе. Для этого выполняется POST-запрос с данными пользователя (логин и пароль). Успешная авторизация возвращает сессию, представленную в виде cookie, которая должна быть сохранена. Эти cookie обязательны для отправки всех последующих запросов, так как они используются для идентификации сессии пользователя в системе.

Этап 2: Отправка ставки

На этом этапе в нашу систему отправляется код ставки, содержащий:

• ID матча, соответствующий событию.
• Код ставки, описывающий выбранный исход (например, победа команды, фора или тотал).
• Коэффициент ставки, актуальный на момент отправки.

При отправке данных обязательно передаются cookie, полученные на этапе авторизации. Это позволяет корректно идентифицировать пользователя и обработать ставку.

Этап 3: Получение результатов

После завершения расчёта исходов или купонов наша система отправляет POST-запросы на указанный remote_host. Этот запрос содержит:

• Статус купона (выигрыш, проигрыш или возврат).
• Статусы всех исходов, входящих в купон.

Отправка результатов происходит в момент определения исхода. Например:

• Если ставка была сделана на промежуточный исход (например, фора 2.5, и был забит третий гол), расчёт может быть выполнен прямо во время матча.
• Если ставка сделана на финальный результат (например, победа команды), информация о статусе будет отправлена сразу после окончания матча.

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

Логин, пароль и хост для отправки запросов можно получить у менеджера.

URL для запроса:

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

Тип отправки данных: POST

Передаваемые данные:

Параметр	Описание
login	Логин пользователя
password	Пароль пользователя

Важно!

• Во время авторизации ответ включает cookie. Эти cookie необходимо сохранить и отправлять с последующими запросами.

Рекомендации для удобства интеграции:

• Убедитесь, что поле login передаётся в формате строки.
• Проверьте корректность сохранения и отправки cookie, так как от этого зависит выполнение последующих запросов.
• В случае ошибки запрос вернёт пустой объект. Убедитесь, что вы обрабатываете такой сценарий.

cookie живут 3 месяца. Но они могут обновиться при перезапуске сервера. Поэтому вам нужно сделать повторную авторизацию, если вы получите ошибку при сохранении купона.

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

Пример ответа:

Успешный:

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

Неуспешный:

{"d":{}}

Описание полей ответа:

Поле	Описание
UserId	Уникальный идентификатор пользователя
d	Корневой объект ответа

Общие рекомендации:

• Перед первым запросом убедитесь, что пользователь ввёл корректные данные.
• Настройте обработку ошибок для отображения пользователю причин неудачи авторизации (например, неверный логин или пароль).
• Логируйте успешные и неуспешные попытки для анализа и мониторинга.

Cookie необходимо сохранять и отправлять с последующими запросами.

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();

Для отправки ставки необходимо использовать cookie, полученные на этапе авторизации. Эти данные обязательны для идентификации вашей сессии и обработки запросов.

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

Описание полей

Параметр	Описание
list_bets	Код ставки и коэффициенты. Формат: "тип_события#ID_матча|Код_ставки#коэффициент". Например: "live#579216393|1|1|0#2.1"
realAmount	Сумма ставки. Указывается в виде строки, например: "150".
currency	Валюта купона.
lang	Язык, на котором сохраняются ставка и купон. Например: "en" или "ru" или "tr".
remote_host	URL для отправки результатов расчёта купона. Указывайте без конечного слэша.
rate_mode	Опция принятия купона при изменении коэффициентов: "reject" (отклонить при изменении) или "accept" (принять при любых изменениях). По умолчанию: "accept".

Примечание: Убедитесь, что параметры передаются в корректном формате. Например, list_bets должен быть массивом, даже если ставка одна.

Мы не проверяем сумму ставки. Вы можете передавать как реальную сумму ставки, так и любое значение. Это сделано для обеспечения конфиденциальности ваших финансовых данных. Наша задача — предоставить результаты расчёта. Вы сами выполняете начисления выигрышей своим игрокам.

Обязательные параметры для отправки ставки:

• list_bets — содержит информацию о ставке и соответствующем матче.
• remote_host — URL, на который мы отправим результаты расчёта купона или исхода.
• rate_mode — определяет, как система обрабатывает изменения коэффициентов.

Остальные параметры также нужно отправлять, но они являются необязательными и могут быть использованы для вашего удобства.

Описание параметра remote_host

remote_host — это адрес вашего сервера, на который мы отправляем запросы с результатами расчёта ставок. На этом хосте должен быть настроен приём запросов от нашего сервера. Ниже описаны примеры возможных значений и особенности работы с этим параметром.

Вы можете указать различные варианты remote_host:

• Простой хост: https://mysites.com
• Хост с портом: https://mysites.com:78665
• Хост с дополнительными путями: https://mysites.com/request/sportapi/sender
• Хост с параметрами: https://mysites.com/request.php?action=webhook

Важно: При отправке запроса наша система автоматически добавляет к указанному remote_host строку /api/bet/result. Таким образом, конечный адрес для получения запросов формируется как remote_host + "/api/bet/result". Убедитесь, что ваш сервер настроен на приём данных по этому пути.

Примеры:

• Вы передаёте remote_host = https://mysites.com. Мы отправляем запросы на: https://mysites.com/api/bet/result.
• Вы передаёте remote_host = https://mysites.com/request.php?action=webhook. Мы отправляем запросы на: https://mysites.com/request.php?action=webhook/api/bet/result.

Технические детали:

• Запросы отправляются методом POST.
• Ваш сервер должен быть готов принимать JSON-данные, которые мы отправляем.
• Ваш сервер должен отдать код 200 в случае успешного приёма данных.

Убедитесь, что ваш сервер корректно обрабатывает указанный путь и запросы. В следующем разделе приведён пример структуры данных, которые отправляются нашим сервером.

Описание параметра rate_mode

Параметр rate_mode задаёт поведение системы при изменении коэффициентов. Он может принимать два значения:

• accept: В этом режиме купон будет принят с текущим коэффициентом, даже если он изменился. Например, игрок добавил в купон ставку «Победа Манчестера» с коэффициентом 2.02. Пока он нажимал кнопку «Сделать ставку», коэффициент изменился на 1.37 или 2.78. В режиме accept система сохранит купон с новым коэффициентом без уведомления вашей системы.
• reject: В этом режиме система отклонит купон, если коэффициент изменился. В ответе будет ошибка с уведомлением о том, что коэффициент изменился.

Выбирайте режим, который лучше всего соответствует вашим бизнес-процессам и обеспечивает удобство для ваших пользователей.

Важные рекомендации

1. Форматирование JSON: Убедитесь, что данные корректно сериализуются в JSON-формат перед отправкой.
2. Cookie: Передавайте cookie, полученные на этапе авторизации, для успешной идентификации сессии пользователя.
3. Обработка ошибок: Обрабатывайте ответы сервера, особенно случаи, когда возвращается errorCode = 1.
4. Тестирование: Проведите тесты на всех этапах интеграции, включая отправку одиночных и нескольких ставок.

Поля ответа

Параметр	Описание
betCode	Уникальный номер ставки в нашей системе
errorCode	Основной статус результата запроса
fullErrorCode	Детализация ошибок.
errorMessage	Текстовые сообщения об ошибках системы
AmountOut	Возможная сумма выигрыша
CountEvents	Количество ставок в купоне
Coef	Коэффициенты исходов
IsLive	Тип ставки: онлайн или до начала матча (true/false)
LinesId	ID матча
EventDate	Дата матча

Описание ошибок при отправке ставки

При отправке ставки могут возникнуть различные ошибки. Ответ сервера содержит три ключевых поля:

• errorCode: Основной статус запроса.
• fullErrorCode: Детализация ошибки.
• errorMessage: Текстовое описание ошибки.

Если ставка успешно принята, сервер возвращает успешный ответ (см. выше). Купон принят, ошибок нет.

Если произошла ошибка, сервер возвращает общий ответ об ошибке (см. выше). Произошла одна из возможных ошибок. Ниже приведены коды и сообщения ошибок.

Возможные коды и описания ошибок

Код ошибки (fullErrorCode)	Сообщение ошибки (errorMessage)	Описание
1	error_wrong_bet_data	Неверные данные ставки. Проверьте параметры list_bets и другие обязательные поля.
1	error_block_bet_data	Ставка временно заблокирована и не может быть принята.
1	error_repeat_bet_data	Повтор ставки на один и тот же исход из одного матча не допускается.
2	label_change_rate	Коэффициент изменился. Купон отклонён из-за несовпадения указанного и актуального коэффициентов.
3	error_exist_bet	Данный исход ставки уже не существует. Проверьте актуальность данных.
99	Неверный уровень доступа	Пользователь не имеет прав для выполнения данной операции. Скорее всего, нужно заново авторизироваться, пропали куки, или аккаунт заблокирован.
99	Error exist remote host!	Некорректный или отсутствующий параметр remote_host. Проверьте настройку вашего сервера.

Рекомендации для обработки ошибок

• Проверка входных данных: Убедитесь, что все обязательные параметры переданы корректно. Проверьте формат list_bets и наличие всех обязательных полей.
• Работа с коэффициентами: Если используется rate_mode = reject, обработайте ошибки, связанные с изменением коэффициентов (label_change_rate).
• Настройка сервера: Убедитесь, что ваш сервер корректно указан в параметре remote_host.
• Журналирование ошибок: Ведите логирование всех ошибок (errorCode, fullErrorCode, errorMessage) для упрощения отладки и взаимодействия с поддержкой.
• Действия при критических ошибках: В случае ошибок уровня 99 проверьте права доступа и настройки API на вашей стороне.

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

Когда ставка добавлена в нашу систему и рассчитана, мы отправляем результаты купона на ваш сервер. Это могут быть:

• Результаты купона (полный расчёт).
• Статусы купона (выигрыш, проигрыш, возврат).

Запросы отправляются на адрес, указанный вами в параметре remote_host. К этому адресу автоматически добавляется строка /api/bet/result. Убедитесь, что ваш сервер настроен на приём данных по этому пути.

Пример конечного адреса:

Если вы передали: remote_host = https://mysite.com, мы отправим данные на: https://mysite.com/api/bet/result.

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

Описание полей

Поле	Описание
remote_host	Адрес вашего сервера, на который отправляются данные.
Id	Уникальный идентификатор ставки в нашей системе. Игнорируется в большинстве случаев.
BarCode	Уникальный номер купона.
Status	Текущий статус купона. Возможные значения: 2 — выигрыш, 4 — проигрыш.
ExtStatus	Дополнительный статус, если был возврат: 0 — изменений нет, 1 — один или несколько исходов рассчитаны с изменением коэффициента.
AmountOut	Сумма выигрыша (если купон выиграл).
DateReceive	Время и дата расчёта купона.

Как интерпретировать Status и ExtStatus

• Status = 2 и ExtStatus = 0: Купон выиграл.
• Status = 4 and ExtStatus = 0: Купон проиграл.
• Status = 2 и ExtStatus = 1: Возврат. Купон рассчитан с коэффициентом 1.

Важные моменты для интеграции

• Обработка ExtStatus = 1: Это может произойти, если матч был отменён или завершён досрочно. В таких случаях все ставки рассчитываются с коэффициентом 1.
• Технические требования: Запросы отправляются методом POST. Ваш сервер должен быть готов принимать JSON-данные по пути remote_host + /api/bet/result.

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