Исходы, ставки и купоны — техническая документация АПИ

• базовый 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.

Эти поля объясняют уже выполненный расчет или возврат и не являются отдельной realtime-лентой состояния матча.

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

URL callback партнер определяет самостоятельно. В production он должен использовать 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 находится в разработке, полностью не протестирован и не рекомендуется для production.

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

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