Результати ставок, ставки та купони — технічна документація API

• базова URL API;
• логін та пароль клієнтського облікового запису;
• при використанні callback - включення функції та секретну фразу callback_secret.

У прикладах використовується умовна адреса:

BASE_URL="https://coupon-api.example.com"

У production використовуйте HTTPS. Усі дати передаються як Unix timestamp у мілісекундах, а грошові значення – як десяткові числа без фіксованої точності.

Успіх:

{
  "code": 1,
  "body": {},
  "error_code": null,
  "error_message": null,
  "date": 1784970000000,
  "time_ms": 5,
  "path": "/api/partner/example"
}

Бізнес-помилка зазвичай також надходить з HTTP 200:

{
  "code": 0,
  "body": null,
  "error_code": 1002,
  "error_message": "Not all params",
  "date": 1784970000000,
  "time_ms": 5,
  "path": "/api/partner/example"
}

Завжди перевіряйте код HTTP, потім code, потім error_code. Не використовуйте error_message як програмний ключ.

POST /api/partner/login
Content-Type: application/json

{
  "username": "partner-demo",
  "password": "strong-password"
}

Поле login підтримується як сумісний аліас username.

Успішна відповідь:

{
  "code": 1,
  "body": {
    "token": "<jwt-token>",
    "user_id": 17,
    "username": "partner-demo"
  },
  "error_code": null,
  "error_message": null
}

У всіх захищених запитах передавайте:

Authorization: Bearer <jwt-token>

Основні помилки входу:

Ці помилки повертаються з HTTP 200, code = 0. HTTP 401 захищеного методу означає, що JWT відсутній, невірний, минув або відкликаний; виконайте вхід повторно. HTTP 403 означає невідповідну роль або заборону доступу.

Кожен вибраний результат передається готовим рядком зі спортивної лінії:

line_type#game_id#group_id#type_id#rate#coefficient[#player_id]

Приклади:

line#737779544#1#1#0#1.85
live#738917381|119|5869|0.5#3.6#149439538

• line_type: line або live;
• rate: параметр тотала/фори або 0;
• player_id: необов’язковий ID гравця;
• роздільники # та | підтримуються.

Не збирайте та не виправляйте вказівник вручну – передавайте отримане з лінії значення без змін.

POST /api/partner/coupons/place
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "list_bets": [
    "line#737779544#1#1#0#1.85"
  ],
  "amount": 10,
  "currency": "USD",
  "callback_url": "https://partner.example.com/api/coupon-result",
  "lang": "en",
  "mode": "reject",
  "mode_type": null,
  "multi": false
}

Коефіцієнти

Ординар, експрес та multi

Один експрес може містити трохи більше 15 подій. Не можна об’єднувати кілька ставок одного матчу, включаючи основний матч, тайми, періоди, кутові, фоли та інші пов’язані саб-події. Така комбінація повертає 506.

Повна успішна відповідь з даними купона та прийнятої ставки всередині events_data:

{
  "code": 1,
  "body": {
    "coupons": [
      {
        "coupon_code": "000000000272",
        "amount": 10,
        "win": 18.5,
        "potential_win": 18.5,
        "real_win": null,
        "coef": 1.85,
        "original_coef": 1.85,
        "calculate_coef": null,
        "has_return": false,
        "date": 1784970000000,
        "status": 0,
        "asian": false,
        "calculate_date": null,
        "coupon_type": 1,
        "events_count": 1,
        "events_data": [
          {
            "id": 912,
            "game_id": 737779544,
            "main_game_id": 737779544,
            "is_sub_game": false,
            "parent_game_id": null,
            "sub_game_key": null,
            "raw_pointer": "line#737779544#1#1#0#1.85",
            "line_type": "line",
            "is_live": false,
            "bet_group_id": 1,
            "bet_group_name": "Match result",
            "bet_id": 1,
            "bet_name": "First team to win",
            "sport_id": 1,
            "sport_name": "Football",
            "tournament_id": 10001,
            "tournament": "National League",
            "event_date": 1784971800000,
            "status": 0,
            "opp1": "Team A",
            "opp2": "Team B",
            "coef": 1.85,
            "calc_coef": null,
            "bet_score": "line#737779544#1#1#0#1.85",
            "calculate_date": null,
            "calculate_score": null,
            "settlement_reason_code": null,
            "settlement_reason": null,
            "placement_score_full": null,
            "placement_score_periods": null,
            "calculation_score_full": null,
            "calculation_score_periods": null,
            "timer": null,
            "dop_name": null,
            "rate": "0",
            "sgame_id": null,
            "game_num": null,
            "stat_id": null,
            "team1_id": 101,
            "team2_id": 102,
            "opp_icon1": 101,
            "opp_icon2": 102
          }
        ]
      }
    ]
  },
  "error_code": null,
  "error_message": null,
  "date": 1784970000015,
  "time_ms": 45,
  "path": "/api/partner/coupons/place"
}

Поля купона

Кожен елемент body.coupons[] - окремий купон.

Поля ставки

Кожен елемент events_data[] визначає конкретну прийняту ставку всередині купона.

Значення null є нормальним для даних, що ще не розраховані або недоступні. Не замінюйте його автоматично на 0 або порожній рядок.

Вважайте купон прийнятим тільки при code = 1 та наявності об’єктів у body.coupons. До цього кошик є попереднім вибором: результат міг зникнути, заблокуватися чи змінити коефіцієнт.

Після успіху:

1. збережіть усі об’єкти body.coupons, а не лише перший;
2. збережіть coupon_code рядком із провідними нулями;
3. збережіть потрібні дані із events_data;
4. зіставте купон із кінцевим користувачем;
5. зафіксуйте фінансову операцію користувача у системі партнера.

Ідентифікатори:

currency не повертається до повної моделі та callback. Якщо валюта потрібна, збережіть значення із запиту створення.

Для 501–504 новий API повертає проблемні ставки у body.changes[]. Поле change_type: 1 - коефіцієнт зріс, 2 - знизився, null - напрямок не застосовується.

Не повторюйте POST /coupons/place наосліп після timeout: перший запит міг бути прийнятий, і повтор створить дублікат.

За кодами можна передати до 100 значень:

{
  "coupon_ids": ["000000000272", "000000000273"]
}

Або передати період створення не більше 24 годин:

{
  "start_date": 1784880000000,
  "end_date": 1784966400000
}

Не поєднуйте coupon_ids і дати в одному запиті. results фільтрує за часом створення, а calculated - за часом остаточного розрахунку.

Статуси купона:

Статуси ставки:

Для фінансового нарахування кінцевому користувачу використовуйте готовий real_win. Не використовуйте potential_win та не перераховуйте виплату самостійно. До розрахунку real_win, calculate_coef, calc_coef та calculate_date рівні null, а не 0.

При першому статусі купона 15, якщо попередній результат вже був фінансово оброблений, партнер один раз повторно списує amount з кінцевого користувача, чекає на новий фінальний статус і нараховує нове real_win. Захистіть операції від повторної обробки.

Кожна ставка в повній моделі і callback є:

До розрахунку обидва поля дорівнюють null. Для локалізованого повідомлення використовуйте код, наприклад:

• MATCH_POSTPONED - матч перенесений;
• MATCH_CANCELLED - матч скасований;
• MARKET_PUSH - повернення за правилами ринку.

При невідомому коді збережіть його та використовуйте непустий settlement_reason як запасний текст. Не розраховуйте виплату з причини - використовуйте статуси і real_win.

Ці поля пояснюють вже виконаний розрахунок чи повернення і не є окремою реальноючасом-стрічкою стану матчу.

Callback необов’язковий. Партнер може працювати лише через polling. Для callback менеджер повинен увімкнути функцію та створити callback_secret; URL передається в кожному створюваному купоні.

URL callback партнер визначає самостійно. У виробництві він повинен використовувати https://; у тестовому оточенні допускається http://.

Система відправляє:

POST {callback_url}
Content-Type: application/json
X-Coupon-Signature: sha256=<hex_hmac_sha256>

Скорочений payload:

{
  "event": "coupons.settled",
  "batchId": "d407e986f3a64d9d36a77bf532322ef8",
  "couponCount": 1,
  "coupons": [
    {
      "coupon_code": "000000000272",
      "realWin": 18.5,
      "calculate_coefficient": 1.85,
      "status": 2,
      "calculate_date": 1784973600000,
      "events_data": [
        {
          "uuid": "912",
          "status": 1,
          "calculate_coefficient": 1.85,
          "calculate_date": 1784973600000,
          "calculate_score": "2:1",
          "settlement_reason_code": "REMOTE_WIN",
          "settlement_reason": "Win",
          "timer": 0
        }
      ]
    }
  ]
}

Обов’язкові правила:

1. обчислюйте sha256=<hex(HMAC-SHA256(raw_body, callback_secret))> за точними вихідними байтами тіла до розбору JSON і порівнюйте підписи безпечним способом;
2. обробляйте всі елементи coupons, пакет може містити до 100 купонів;
3. зберігайте batchId з унікальним індексом;
4. повторний batchId не повинен повторювати списання чи нарахування;
5. один coupon_code може приходити з різними batchId при прогресивному розрахунку та перерахунку;
6. повертайте HTTP 200 лише після надійного збереження всього пакета.

Мінімальна успішна відповідь – порожня HTTP 200. Розширений:

{
  "success": true,
  "processed": 1
}

processed повинен дорівнювати couponCount. Відповіді 201, 202 та 204 не вважаються успішними.

Повтори виконуються тільки при timeout, транспортній помилці або HTTP 500, 502, 503, 504: відразу, потім через 1, 5, 15 та 60 хвилин – не більше п’яти. На HTTP 200 із success: false або частковим processed автоматичного повтору немає.

Навіть при callback періодично звіряйте результати:

GET /api/partner/coupons/calculated?time=10

Після перерви більше 120 хвилин використовуйте POST /api/partner/coupons/results за збереженими coupon_ids або періоди створення до 24 годин. Повторне отримання того ж таки стану не повинно повторювати фінансові операції.

• зберігайте логін, пароль, JWT та callback_secret тільки на сервері;
• не передавайте JWT URL і не записуйте повний токен в логи;
• використовуйте десятковий тип для грошей;
• зберігайте coupon_code рядком;
• зберігайте amount, потрібні дані ставок та currency, якщо вона використовується;
• розрізняйте статуси купона та ставки;
• невідомі поля та коди причин приймайте без помилки;
• усі фінансові операції кінцевого користувача робіть ідемпотентними.

Старі маршрути продовжують підтримуватись, але нові інтеграції повинні використовувати /api/partner/**. Формати старих відповідей та помилок відрізняються. Для оновлення існуючого клієнта використовуйте єдиний файл Перехід зі старого API.

Cashout знаходиться в розробці, повністю не протестований і не рекомендується для виробництва.

• Отримано BASE_URL, логін та пароль.
• JWT передається як Bearer token.
• Вказівники беруться з лінії без змін.
• Кошик зберігається як прийнятий купон лише після code = 1.
• Оброблено multi, обмеження експресу та помилки 501–507.
• Враховано автоматичне списання клієнтського балансу.
• Збережено всі coupon_code та ID ставок.
• Фінальна виплата береться із real_win.
• Callback перевіряється за вихідними байтами та дедуплікується за batchId.
• Настроєний резервний polling.
• баланс користувача відокремлений від клієнтського балансу SportAPI.

Детальна документація починається з огляду API. Повна карта endpoint знаходиться в довіднику.