Активные и недавно рассчитанные купоны

Система расчета купонов SportAPI предоставляет два отдельных метода:

Метод	Что возвращает
`GET /api/partner/coupons/active`	Все текущие активные купоны партнера.
`GET /api/partner/coupons/calculated`	Купоны, окончательный результат которых появился за последние N минут.

Оба запроса требуют действующий Bearer JWT и возвращают только купоны владельца токена.

Authorization: Bearer <token>
Accept: application/json

Активные купоны

Используйте:

GET /api/partner/coupons/active

Метод не имеет параметров и возвращает все купоны партнера, которые API в текущий момент считает активными.

Он подходит для:

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

Пример запроса

HTTP:

GET /api/partner/coupons/active HTTP/1.1
Host: coupon-api.example.com
Authorization: Bearer <token>
Accept: application/json

cURL:

BASE_URL="https://coupon-api.example.com"
TOKEN="<jwt-token>"

curl --request GET \
  --url "$BASE_URL/api/partner/coupons/active" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $TOKEN"

Фактический BASE_URL партнер получает у менеджера.

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

{
  "code": 1,
  "body": [
    {
      "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": 84521,
          "game_id": 737779544,
          "raw_pointer": "line#737779544#1#1#0#1.85",
          "line_type": "line",
          "is_live": false,
          "bet_group_id": 1,
          "bet_group_name": "Исход матча",
          "bet_id": 1,
          "bet_name": "Победа первой команды",
          "status": 0,
          "opp1": "Команда A",
          "opp2": "Команда B",
          "coef": 1.85,
          "calc_coef": null,
          "calculate_date": null,
          "calculate_score": null,
          "rate": "0"
        }
      ]
    }
  ],
  "error_code": null,
  "error_message": null,
  "date": 1784970000100,
  "time_ms": 15,
  "path": "/api/partner/coupons/active"
}

До расчета:

status купона обычно равен 0;
real_win равен null;
calculate_coef равен null;
calculate_date равен null;
нерассчитанные ставки внутри events_data имеют статус 0.

Значение 0 вместо null для нерассчитанного calculate_date не используется.

Если активных купонов нет

Пустой список является успешным результатом:

{
  "code": 1,
  "body": [],
  "error_code": null,
  "error_message": null,
  "date": 1784970000100,
  "time_ms": 5,
  "path": "/api/partner/coupons/active"
}

Не считайте пустой body ошибкой и не ожидайте body.coupons: массив купонов находится непосредственно в body.

Недавно рассчитанные купоны

Используйте:

GET /api/partner/coupons/calculated?time={minutes}

time — количество минут назад от текущего момента.

Параметр `time`

Условие	Поведение
Параметр не передан	Используются последние 5 минут.
`time <= 0`	Используются последние 5 минут.
`time` от 1 до 120	Используется переданное количество минут.
`time > 120`	Значение ограничивается до 120 минут.

Примеры:

/api/partner/coupons/calculated
/api/partner/coupons/calculated?time=5
/api/partner/coupons/calculated?time=120

Пример запроса

GET /api/partner/coupons/calculated?time=10 HTTP/1.1
Host: coupon-api.example.com
Authorization: Bearer <token>
Accept: application/json

BASE_URL="https://coupon-api.example.com"
TOKEN="<jwt-token>"

curl --request GET \
  --url "$BASE_URL/api/partner/coupons/calculated?time=10" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $TOKEN"

Как выбираются купоны

Отбор выполняется по времени окончательного расчета купона:

текущий момент − time минут ≤ время окончательного расчета

Время создания купона на этот отбор не влияет.

Например, купон мог быть создан два дня назад, а рассчитан в последние 10 минут. Запрос с time=10 вернет такой купон.

Метод не возвращает:

активные купоны;
купоны других партнеров;
купоны, рассчитанные раньше выбранного временного окна.

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

{
  "code": 1,
  "body": [
    {
      "coupon_code": "000000000272",
      "amount": 10,
      "win": 18.5,
      "potential_win": 18.5,
      "real_win": 18.5,
      "coef": 1.85,
      "original_coef": 1.85,
      "calculate_coef": 1.85,
      "has_return": false,
      "date": 1784970000000,
      "status": 2,
      "asian": false,
      "calculate_date": 1784973600000,
      "coupon_type": 1,
      "events_count": 1,
      "events_data": [
        {
          "id": 84521,
          "game_id": 737779544,
          "raw_pointer": "line#737779544#1#1#0#1.85",
          "line_type": "line",
          "is_live": false,
          "bet_group_id": 1,
          "bet_group_name": "Исход матча",
          "bet_id": 1,
          "bet_name": "Победа первой команды",
          "status": 1,
          "opp1": "Команда A",
          "opp2": "Команда B",
          "coef": 1.85,
          "calc_coef": 1.85,
          "calculate_date": 1784973600000,
          "calculate_score": "2:1",
          "settlement_reason_code": "AUTOMATIC_SETTLEMENT",
          "settlement_reason": "Calculated automatically",
          "rate": "0"
        }
      ]
    }
  ],
  "error_code": null,
  "error_message": null,
  "date": 1784973600100,
  "time_ms": 12,
  "path": "/api/partner/coupons/calculated"
}

Каждый элемент body является полной моделью купона и содержит все ставки в events_data.

Названия спорта, турнира, участников, группы ставок и исхода возвращаются в полном виде на языке, который был указан при создании купона.

Если новых расчетов нет

Пустой успешный ответ:

{
  "code": 1,
  "body": [],
  "error_code": null,
  "error_message": null,
  "date": 1784973600100,
  "time_ms": 5,
  "path": "/api/partner/coupons/calculated"
}

Пустой массив означает, что в выбранном окне нет доступных окончательно рассчитанных купонов.

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

Статус проигрыша экспресса может быть определен сразу после первого проигравшего исхода.

Поэтому в актуальной модели проигравшего экспресса возможно:

status купона = 4
одна из ставок имеет status = 2
часть остальных ставок еще имеет status = 0

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

Не создавайте новый купон при повторном появлении того же coupon_code. Обновляйте существующую запись и защищайте финансовые операции от повторного выполнения.

Чем методы отличаются

Свойство	`/active`	`/calculated`
Назначение	Текущие незавершенные купоны	Недавно полученные окончательные результаты
Параметры	Нет	`time`, необязательный
Максимальное окно	Не применяется	120 минут
Время отбора	Текущее состояние	Время окончательного расчета
Активные купоны	Возвращаются	Не возвращаются
Рассчитанные купоны	Не возвращаются	Возвращаются в пределах окна
Формат результата	Массив прямо в `body`	Массив прямо в `body`

Оба метода возвращают полную модель купона нового API.

Выбор метода

Используйте /active, если нужно:

показать незавершенные купоны;
сверить локальный список активных ставок;
восстановить активные купоны после сбоя.

Используйте /calculated, если нужно:

получать результаты без callback;
контролировать доставку результатов при включенном callback;
найти купоны, рассчитанные за недавний период;
восстановиться после короткой недоступности.

Если нужно проверить конкретные известные коды после перерыва более 120 минут, используйте POST /api/partner/coupons/results с coupon_ids.

Polling с перекрытием

Для резервной сверки можно запускать запрос каждые 5 минут, но проверять последние 10 минут:

каждые 5 минут:
GET /api/partner/coupons/calculated?time=10

Так временные окна перекрываются и один пропущенный запуск не приводит к потере результата.

Повторное получение уже обработанного купона является штатным. Обновляйте данные по coupon_code и не выполняйте повторно списание или начисление.

Полная схема восстановления описана на странице «Резервный polling».

Проверка успешности

Оба метода используют общую оболочку ответа:

HTTP 2xx и code = 1 → запрос успешен, обработать весь массив body
HTTP 2xx и code = 0 → бизнес-ошибка, проверить error_code
HTTP 401 → JWT отсутствует, неверен или истек
HTTP 403 → токен не имеет необходимого доступа
HTTP 5xx → временная серверная ошибка

При code = 1 пустой body является допустимым успешным результатом.

Совместимые маршруты

Для активных купонов доступен совместимый алиас нового формата:

GET /api/v3/partner/bet/active

Для недавно рассчитанных купонов ранее использовался:

GET /coupons/calculated?time=5

Старый маршрут продолжает поддерживаться, однако новая интеграция должна использовать /api/partner/coupons/calculated.

Подробное сравнение приведено в разделе «Переход со старого API».

Контрольный список

Для активных купонов используется /api/partner/coupons/active.
Для недавних результатов используется /api/partner/coupons/calculated.
Передается действующий Bearer JWT.
У /active нет параметров.
Параметр time задается в минутах.
Значение time ограничено 120 минутами.
/calculated отбирает по времени расчета, а не создания.
Купоны читаются из массива body, а не из body.coupons.
Пустой массив считается успешным результатом.
Обрабатывается каждый купон и весь его events_data.
Повторный coupon_code обновляет существующую запись.
Финансовые операции выполняются идемпотентно.

Следующий раздел: «Модель купона и ставки».

Активные и недавно рассчитанные купоны

Активные купоны

Пример запроса

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

Если активных купонов нет

Недавно рассчитанные купоны

Параметр time

Пример запроса

Как выбираются купоны

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

Если новых расчетов нет

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

Чем методы отличаются

Выбор метода

Polling с перекрытием

Проверка успешности

Совместимые маршруты

Контрольный список

Параметр `time`