Модель купона и ставки

Полная модель содержит:

• общие данные купона;
• суммы и коэффициенты;
• статус и даты расчета;
• массив events_data со всеми ставками купона.

Один объект events_data описывает одну принятую ставку внутри купона.

Общая структура

{
  "coupon_code": "000000000272",
  "amount": 10,
  "status": 0,
  "events_count": 1,
  "events_data": [
    {
      "id": 84521,
      "game_id": 737779544,
      "bet_id": 1,
      "status": 0
    }
  ]
}

Статус купона и статус ставки — разные справочники. Всегда учитывайте, на каком уровне находится поле.

Идентификаторы

Не путайте эти значения:

coupon_code → купон
id / uuid   → конкретная ставка внутри купона
game_id     → спортивное событие
bet_id      → исход в линии
batchId     → пакет callback

Для локального хранения ставки рекомендуется составной ключ:

coupon_code + events_data[].id

При обработке callback сопоставляйте строковый uuid с сохраненным id.

game_id и bet_id могут повторяться в разных купонах, поэтому они не заменяют внутренний ID принятой ставки.

Поля купона

Основные данные

events_count должен описывать количество объектов ставок, однако при обработке ответа все равно перебирайте фактический массив events_data.

Суммы

Для финансового начисления после финального расчета используйте real_win.

Не используйте potential_win как фактическую выплату: это только возможный результат, рассчитанный при создании купона.

Кратко:

amount        → сколько поставлено
potential_win → сколько можно было получить при создании
real_win      → сколько фактически нужно выплатить после расчета

Поле win сохраняется для отображения и совместимости. Если партнеру нужно изменить баланс пользователя, основным полем должно быть real_win.

Коэффициенты купона

Кратко:

original_coef  → коэффициент при создании
coef           → текущее отображаемое значение
calculate_coef → окончательный расчетный коэффициент

Для финансовой операции не пересчитывайте выплату самостоятельно по отображаемому coef. Используйте готовое значение real_win.

Дата расчета

До расчета значение всегда равно null:

{
  "calculate_date": null
}

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

Статусы купона

Статус 15 не означает обычное обновление карточки. При нем соответствующая ставка имеет статус 4, а партнер ожидает новый расчетный результат.

Финансовые действия при статусах подробно описаны в разделе «Статусы и расчет выплаты».

Поля ставки в events_data

ID события и саб-события

Для основной игры часть полей саб-события будет равна null.

Пример основной игры:

{
  "game_id": 737779544,
  "main_game_id": 737779544,
  "is_sub_game": false,
  "parent_game_id": null,
  "sub_game_key": null,
  "dop_name": null
}

Для саб-события game_id идентифицирует выбранное саб-событие, а main_game_id и parent_game_id позволяют связать его с основным матчем.

Исходный указатель и тип линии

raw_pointer сохраняется без изменений:

line#737779544#1#1#0#1.85

Он полезен для технической сверки, но не заменяет events_data[].id как ID принятой ставки.

Спорт, турнир и участники

opp_icon1 и opp_icon2 — исторические совместимые названия. Несмотря на слово icon, эти поля содержат ID участников, а не URL или файл изображения.

Для нового кода рекомендуется использовать team1_id и team2_id.

Группа ставок и исход

bet_name уже может содержать расшифрованный параметр исхода и имя игрока, если они применимы.

Пример:

{
  "bet_group_id": 17,
  "bet_group_name": "Тотал голов",
  "bet_id": 9,
  "bet_name": "Тотал больше 2.5",
  "rate": "2.5"
}

Коэффициенты и расчет ставки

calc_coef зависит от результата ставки:

Поле calc_coef — расчетный множитель конкретной ставки, а calculate_coef на уровне купона — результат расчета всего купона.

Причина расчета

Поля причины дополняют числовой статус ставки:

• settlement_reason_code подходит для программной обработки и аналитики;
• settlement_reason содержит поясняющий текст и не является стабильным программным значением.

Примеры кодов:

Список кодов может расширяться. Не отклоняйте ответ из-за неизвестного settlement_reason_code: сохраните значение и определяйте финансовый результат по status, calc_coef и итоговому real_win.

Уведомление конечного пользователя

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

1. прочитать settlement_reason_code;
2. сопоставить известный код с локализованным текстом партнера;
3. если код неизвестен, использовать непустой settlement_reason как запасное пояснение;
4. сохранить оба исходных поля для последующей сверки.

Например:

Не предполагайте, что settlement_reason переведен на язык купона: поле может содержать исходный текст источника расчета. Причина предназначена для объяснения результата и не заменяет status, calc_coef или real_win.

Эти поля описывают причину уже выполненного расчета или возврата, а не текущее состояние спортивного события. До расчета оба поля равны null; API не гарантирует отдельное предварительное уведомление о переносе или отмене матча через эти поля.

Счет события

Важно. Несмотря на название, bet_score не является счетом матча. Это совместимое поле, которое содержит исходный указатель ставки. Для счета используйте calculate_score и расширенные поля placement_* / calculation_*.

Формат счета зависит от вида спорта и данных поставщика. Храните его как строку и не рассчитывайте результат ставки самостоятельно только по этому полю.

Полный пример активного купона

{
  "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,
      "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": "Исход матча",
      "bet_id": 1,
      "bet_name": "Победа первой команды",
      "sport_id": 1,
      "sport_name": "Футбол",
      "tournament_id": 10001,
      "tournament": "Национальная лига",
      "event_date": 1784971800000,
      "status": 0,
      "opp1": "Команда A",
      "opp2": "Команда 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
    }
  ]
}

После выигрыша ординара основные расчетные поля изменятся:

{
  "status": 2,
  "real_win": 18.5,
  "calculate_coef": 1.85,
  "calculate_date": 1784973600000,
  "events_data": [
    {
      "id": 84521,
      "status": 1,
      "calc_coef": 1.85,
      "calculate_date": 1784973600000,
      "calculate_score": "2:1",
      "settlement_reason_code": "AUTOMATIC_SETTLEMENT",
      "settlement_reason": "Calculated automatically",
      "calculation_score_full": "2:1"
    }
  ]
}

Это сокращенный снимок изменений, а не отдельный формат ответа.

Nullable-поля

null является штатным значением, если данные:

• еще не рассчитаны;
• не применимы к конкретному виду спорта;
• отсутствуют у поставщика;
• относятся только к live или саб-событиям.

Не заменяйте null автоматически числом 0 или пустой строкой: эти значения могут иметь другое значение в контракте.

Особенно важно сохранить:

real_win = null до финального расчета
calculate_coef = null до финального расчета
calculate_date = null до расчета
calc_coef = null до расчета ставки
settlement_reason_code = null до расчета ставки
settlement_reason = null до расчета ставки

Даты и десятичные значения

Все даты в этой модели передаются в Unix-миллисекундах:

1784973600000

Не путайте их с Unix-секундами.

Суммы и коэффициенты передаются как десятичные числа без фиксированного количества знаков после запятой. Партнер самостоятельно определяет правила отображения и округления в своей системе.

Рекомендуется использовать десятичный тип данных, а не двоичный float, для хранения денег и финансовых расчетов.

Язык названий

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

API поддерживает около 50 языков. Передается двухбуквенный код языка; полный перечень в документации не публикуется.

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

Отличия полной модели от callback

Callback передает расчетный снимок, а не всю карточку купона.

В callback отсутствуют, в частности:

• amount;
• названия спорта, турнира, команд, рынка и исхода;
• часть исходных данных купона.

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

Валюта

Поле currency передается при создании купона, но не входит в полную модель ответа купона и callback.

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

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

Что рекомендуется хранить

Партнер самостоятельно определяет необходимый набор данных. Для надежной интеграции рекомендуется как минимум сохранять:

На уровне купона

• coupon_code;
• amount;
• переданную при создании currency, если она используется;
• coupon_type;
• status;
• real_win;
• original_coef;
• calculate_coef;
• date;
• calculate_date.

На уровне ставки

• coupon_code;
• events_data[].id;
• raw_pointer;
• game_id;
• bet_group_id;
• bet_id;
• coef;
• status;
• calc_coef;
• calculate_date;
• settlement_reason_code;
• settlement_reason, если текст нужен для журнала или отображения.

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

Хранить весь ответ целиком необязательно. Однако coupon_code нужно сохранить обязательно: это основной связующий ключ между системой партнера и Системой расчета купонов SportAPI.

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

• coupon_code хранится как строка с ведущими нулями.
• Купон и ставки сохраняются как разные связанные сущности.
• Ставка идентифицируется по coupon_code + id.
• uuid из callback сопоставляется с id полной модели.
• batchId не используется как ID купона или ставки.
• real_win используется для финальной выплаты.
• potential_win не используется как фактическая выплата.
• Статусы купона и ставки читаются по разным справочникам.
• calculate_date до расчета равен null, а не 0.
• Поле bet_score не интерпретируется как счет матча.
• Nullable-поля обрабатываются без искусственной замены значений.
• Для логики причины используется settlement_reason_code, а не текст settlement_reason.
• Даты читаются как Unix-миллисекунды.
• Валюта сохраняется партнером при создании, если она нужна.
• Язык названий фиксируется при создании купона.

Следующий раздел: «Cashout».