---
id: sub-events
title: 'Модель данных: дополнительные матчи и субматчи'
description: 'Описание дополнительных матчей и субматчей: таймов, угловых, карточек, фолов и других линий события.'
version: v1
language: ru
---

# Модель данных: дополнительные матчи и субматчи


## Что такое дополнительный матч

Дополнительный матч, или субматч, — это отдельная линия внутри основного спортивного
события. У субматча есть собственный `game_id` и собственный набор групп ставок и
коэффициентов.

Примеры субматчей:

- первый или второй тайм;
- угловые;
- угловые первого или второго тайма;
- жёлтые карточки;
- фолы и офсайды;
- удары по воротам и в створ ворот;
- статистика игроков;
- другие дополнительные рынки матча.

В документации термины «дополнительный матч» и «субматч» обозначают одну и ту же
сущность из массива `sub_games`.

## Основной матч и субматч

Основной матч и его субматчи связаны полями `game_id` и `game_mid`.

| Поле | Назначение |
|---|---|
| `game_id` | ID текущего объекта: основного матча или выбранного субматча |
| `game_mid` | ID основного матча |
| `game_dop_name` | Название типа субматча в его подробном ответе |

У основного матча `game_id` и `game_mid` обычно совпадают, а `game_dop_name` остаётся
пустым:

```json
{
  "game_id": 746146992,
  "game_mid": 746146992,
  "game_dop_name": ""
}
```

У субматча собственный `game_id`, а `game_mid` указывает на основной матч:

```json
{
  "game_id": 746147010,
  "game_mid": 746146992,
  "game_dop_name": "Угловые"
}
```

В этом примере:

- `746147010` — ID субматча «Угловые»;
- `746146992` — ID основного матча;
- запрос коэффициентов на угловые выполняется по `game_id` субматча `746147010`.

Не заменяйте `game_id` субматча значением `game_mid`: эти поля решают разные задачи.

## Где получается список субматчей

Список дополнительных матчей нужно получать только из поля `sub_games` подробного
ответа [`event`](../api-reference/event.md) для основного матча.

```text
events
  ↓ game_id основного матча
event основного матча
  ↓ sub_games[].game_id
event выбранного субматча
  ↓ game_oc_list
полный список его ставок и коэффициентов
```

В списке матчей [`events`](../api-reference/events.md) поле `sub_games` не используется и
возвращается пустым:

```json
{
  "sub_games": []
}
```

В `topmatches?full=true` и `toplist?full=true` список субматчей также не предоставляется.

## Структура `sub_games`

`sub_games` — массив ссылок на доступные дополнительные матчи:

```json
{
  "sub_games": [
    {
      "game_id": 746147013,
      "game_num": 150080,
      "game_name": "2-й тайм"
    },
    {
      "game_id": 746147010,
      "game_num": 205978,
      "game_name": "Угловые"
    },
    {
      "game_id": 746147314,
      "game_num": 178621,
      "game_name": "Желтые карточки"
    }
  ]
}
```

| Поле | Тип | Описание |
|---|---|---|
| `game_id` | number или `null` | ID субматча для отдельного запроса `event` |
| `game_num` | number или `null` | Старое служебное поле; не используется в клиентской интеграции и планируется к удалению |
| `game_name` | string или `null` | Название дополнительного матча на языке запроса |

`game_name` предназначен для отображения. Не используйте текст названия как
технический идентификатор: он зависит от выбранного языка.

Для запроса используйте только `game_id`. Не формируйте ID субматча самостоятельно и
не используйте вместо него `game_num`.

## Что находится внутри `sub_games`

Элемент `sub_games` содержит только ссылку и название субматча. В нём нет:

- коэффициентов;
- групп ставок;
- полного объекта матча;
- отдельной статистики;
- списка дочерних субматчей.

Чтобы получить ставки и коэффициенты, выполните отдельный запрос `event` по `game_id`
выбранного дополнительного матча.

## Запрос дополнительного матча

Основной Live-матч вернул ссылку на субматч «Угловые»:

```json
{
  "game_id": 746147010,
  "game_num": 205978,
  "game_name": "Угловые"
}
```

Запрос субматча выполняется тем же методом `event`:

```bash
curl --request GET \
  --url 'https://YOUR_API_DOMAIN/v1/event/746147010/group/live/ru' \
  --header 'Package: YOUR_API_KEY'
```

Сокращённый фрагмент ответа:

```json
{
  "status": 1,
  "page": "/v1/event",
  "body": {
    "game_id": 746147010,
    "game_mid": 746146992,
    "game_dop_name": "Угловые",
    "game_desk": "Тайм",
    "game_oc_counter": 175,
    "sub_games": []
  }
}
```

Полный список ставок субматча находится в `body.game_oc_list`. Он имеет такую же
структуру `group`, как список ставок основного матча.

Сохранённый полный ответ:
[субматч «Угловые», Live, русский язык](../examples/json-responses/event.subgame-746147010.corners.group.live.ru.json).

## Live и Prematch

Дополнительные матчи могут возвращаться как в Live, так и в Prematch. Запрашивайте
субматч в том же типе линии, из которого был получен его `game_id`:

```text
sub_games из Live     → event/{gameId}/group/live/{lang}
sub_games из Prematch → event/{gameId}/group/line/{lang}
```

Prematch- и Live-версии матчей имеют разные ID. Не переносите `game_id` основного матча
или субматча из `line` в `live`.

Состав `sub_games` также может различаться между Prematch и Live. Используйте только
актуальный список из текущего ответа API.

## Названия и типы субматчей

В списке `sub_games` название находится в `game_name`:

```json
{
  "game_name": "Угловые"
}
```

После запроса дополнительного матча его тип возвращается в `game_dop_name`:

```json
{
  "game_dop_name": "Угловые"
}
```

Поле `game_desk` может дополнительно обозначать игровой отрезок, например `Тайм`, `Сет`
или `Четверть`. Оно не заменяет `game_id` и не используется как постоянный ID типа
субматча.

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

## Коэффициенты субматча

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

- `game_id`;
- `game_oc_counter`;
- группы в `game_oc_list`;
- исходы и коэффициенты;
- значения `oc_pointer`.

Коэффициенты в `game_oc_list` относятся только к выбранному субматчу. Они не содержат
ставки основного матча или других дополнительных матчей.

Например, если запрошен субматч «Угловые, 1-й тайм», ответ содержит коэффициенты только
на угловые первого тайма:

- не на все события первого тайма;
- не на все угловые основного матча;
- не на основной матч целиком.

Чтобы получить коэффициенты на все угловые матча, нужно отдельно открыть субматч
«Угловые». Для коэффициентов основного матча нужно запросить `event` по `game_id`
основного матча.

Для отображения полного списка используйте формат `group` и сохраняйте порядок групп,
колонок и исходов, сформированный API.

Подробное описание структуры ставок:
[«Коэффициенты и группы ставок»](odds.md).

## Статистика в субматче

Поле `stat_list` внутри ответа субматча относится к основному матчу целиком. Оно не
содержит отдельную статистику выбранного дополнительного матча.

Например, при запросе «Угловые, 1-й тайм» или «1-й тайм» в `stat_list` всё равно
передаются основные показатели главного матча. Не фильтруйте статистику по
`game_dop_name`.

Подробные правила описаны в документе [«Статистика матча»](live-statistics.md).

## Когда субматч недоступен

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

При запросе устаревшего `game_id` API может вернуть:

```json
{
  "status": 1,
  "page": "/v1/event",
  "body": {
    "message": "Game id finished"
  }
}
```

После такого ответа прекратите обновлять прежний ID. Сообщение не объясняет точную
причину исчезновения дополнительного матча.

## Групповые матчи и `event_plan`

`event_plan` и `sub_games` — разные структуры.

| Поле | Что описывает |
|---|---|
| `sub_games` | Дополнительные линии и рынки одного основного матча |
| `event_plan` | Полный список команд, выступающих на стороне хозяев и гостей в групповом матче |

`event_plan` предназначен для групповых матчей. В основном объекте такого события
стороны могут называться обобщённо, например «Хозяева — Гости». Поле `event_plan`
раскрывает состав этих сторон и перечисляет все реальные команды, которые участвуют в
групповом матче.

Каждый объект массива связывает одну команду со стороны хозяев с соответствующей
командой со стороны гостей. Полный массив содержит все такие пары и тем самым показывает
полный список команд обеих сторон.

Например, `sub_games` может содержать отдельный рынок «Угловые» или «1-й тайм», а
`event_plan` для группового матча «Хозяева — Гости» содержит пары конкретных команд:

```text
Хозяева                         Гости
Anzoategui          →           Trujillanos
Caracas             →           Carabobo
```

Заполненный `event_plan` можно получить только через конкретный `event`. В списке
`events` поле возвращается как `[]`.

### Поля объекта `event_plan`

| Поле | Тип | Описание |
|---|---|---|
| `opp_1_name` | string | Название команды, выступающей на стороне хозяев |
| `opp_2_name` | string | Название команды, выступающей на стороне гостей |
| `opp_1_id` | number или `null` | ID команды со стороны хозяев |
| `opp_2_id` | number или `null` | ID команды со стороны гостей |
| `opp_1_country_id` | number или `null` | ID страны команды со стороны хозяев |
| `opp_2_country_id` | number или `null` | ID страны команды со стороны гостей |
| `opp_1_icon` | string | Имя файла иконки команды со стороны хозяев |
| `opp_2_icon` | string | Имя файла иконки команды со стороны гостей |
| `opp_1_date` | number или `null` | Дата команды со стороны хозяев в формате Unix Timestamp |
| `opp_2_date` | number или `null` | Дата команды со стороны гостей в формате Unix Timestamp |
| `game_start` | number или `null` | Время начала встречи этой пары в формате Unix Timestamp |

Сокращённый пример состава группового матча:

```json
{
  "event_plan": [
    {
      "opp_1_name": "Anzoategui",
      "opp_2_name": "Trujillanos",
      "opp_1_id": 6354451,
      "opp_2_id": 2792,
      "opp_1_country_id": 41,
      "opp_2_country_id": 41,
      "opp_1_icon": "b85e2e3631e4b873b1d74975e6dd4e93.png",
      "opp_2_icon": "2792.png",
      "game_start": 1787342400
    },
    {
      "opp_1_name": "Caracas",
      "opp_2_name": "Carabobo",
      "opp_1_id": 2776,
      "opp_2_id": 29081,
      "opp_1_country_id": 41,
      "opp_2_country_id": 41,
      "opp_1_icon": "6309ee8475d59f87fff70fd08858e36f.png",
      "opp_2_icon": "56b11c23ac71e2f6934a7e0feb46dd5e.png",
      "game_start": 1787353200
    }
  ]
}
```

Элементы `event_plan` не являются ссылками на субматчи: в них нет отдельного `game_id`
для запроса `event`. Используйте их для отображения полного состава команд на стороне
хозяев и гостей и расписания пар внутри группового матча.

Для иконки участника удалите расширение из `opp_1_icon` или `opp_2_icon` и подставьте
оставшееся имя в URL:

```text
https://cdn.sportapi.net/opp/v1/color/{iconName}.webp
```

## Практические правила интеграции

1. Получайте `sub_games` только из подробного ответа основного матча `event`.
2. Для открытия субматча используйте его собственный `game_id`.
3. Запрашивайте дополнительный матч в том же типе линии: `live` или `line`.
4. Не используйте устаревшее поле `game_num`.
5. Не ожидайте коэффициенты непосредственно внутри `sub_games`.
6. Связывайте субматч с основным матчем через `game_mid`.
7. Не интерпретируйте статистику субматча как отдельную статистику его рынка.
8. Не смешивайте дополнительные матчи из `sub_games` с составом группового матча в
   `event_plan`.
9. Обновляйте список субматчей по актуальному ответу API.

## Проверочные ответы

- [Основной Live-матч с 13 субматчами](../examples/json-responses/event.game-746146992.group.live.ru.json)
- [Основной Prematch с 24 субматчами](../examples/json-responses/event.game-730321837.group.line.ru.json)
- [Подробный ответ субматча «Угловые»](../examples/json-responses/event.subgame-746147010.corners.group.live.ru.json)

## Связанные документы

- [Модель данных: матч](match.md)
- [Модель данных: статистика матча](live-statistics.md)
- [Коэффициенты и группы ставок](odds.md)
- [`event` — конкретный матч](../api-reference/event.md)
- [Единый справочник полей](field-reference.md)
