Інтеграція системи для розрахунку ставок і купонів

Як працює система розрахунку шансів і наслідків?

Інтеграція з нашою системою розрахунку ставок і купонів проходить у три ключові етапи:

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

На першому етапі необхідно авторизуватися в системі. Для цього виконується POST-запит з даними користувача (логін і пароль). Успішна авторизація повертає сесію, представлену у вигляді cookie, яка має бути збережена. Ці cookie обов’язкові для відправлення всіх наступних запитів, оскільки вони використовуються для ідентифікації сесії користувача в системі.

Етап 2: Відправлення ставки

На цьому етапі в нашу систему відправляється код ставки, що містить:

• ID матчу, що відповідає події.
• Код ставки, що описує обраний наслідок (наприклад, перемога команди, фора або тотал).
• Коефіцієнт ставки, актуальний на момент відправлення.

Під час відправлення даних обов’язково передаються cookie, отримані на етапі авторизації. Це дозволяє коректно ідентифікувати користувача й обробити ставку.

Етап 3: Отримання результатів

Після завершення розрахунку наслідків або купонів наша система відправляє POST-запити на вказаний remote_host. Цей запит містить:

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

Відправлення результатів відбувається в момент визначення наслідку. Наприклад:

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

Тепер перегляньте кожен крок окремо. Ми докладно описали запити, параметри та відповіді REST API.

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

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: Текстовий опис помилки.

If the bet is successfully accepted, the server returns a success response (see above). The coupon has been accepted, and there are no errors.

If an error occurs, the server returns a general error response (see above). One of the possible errors occurred. Below are the error codes and messages.

Можливі коди й описи помилок

Код помилки (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 і 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"
    }]
}