---
id: integration-guide
title: Sport Line API — руководство по подключению
description: Последовательное руководство по подключению Sport Line API к сайту, приложению или внутренней системе клиента.
version: v1
language: ru
---

# Sport Line API — руководство по подключению


Sport Line API предоставляет актуальные спортивные данные для сайта, приложения или
другого программного продукта клиента.

Официальный сайт: [sportapi.net](https://sportapi.net).

Поддержка в Telegram: [@suport_sportapi](https://t.me/suport_sportapi).

## Содержание

1. [Что предоставляет Sport Line API](#1-что-предоставляет-sport-line-api)
2. [Что необходимо для подключения](#2-что-необходимо-для-подключения)
3. [Как выполнить первый запрос](#3-как-выполнить-первый-запрос)
4. [Основная последовательность интеграции](#4-основная-последовательность-интеграции)
5. [Prematch и Live](#5-prematch-и-live)
6. [Какие данные возвращаются](#6-какие-данные-возвращаются)
7. [Дополнительные методы](#7-дополнительные-методы)
8. [Готовые иконки](#8-готовые-иконки)
9. [Обновление данных](#9-обновление-данных)
10. [Live 3D Tracker](#10-live-3d-tracker)
11. [Видеотрансляции](#11-видеотрансляции)
12. [Обработка ошибок](#12-обработка-ошибок)
13. [Примеры интеграции](#13-примеры-интеграции)
14. [Подробная документация](#14-подробная-документация)
15. [Поддержка](#15-поддержка)

## 1. Что предоставляет Sport Line API

С помощью Sport Line API Вы можете получать:

- доступные виды спорта;
- страны, турниры и чемпионаты;
- предстоящие матчи Prematch;
- матчи, которые проходят в Live;
- команды или участников матча;
- время начала, текущий счёт, период и таймер;
- краткий список основных коэффициентов в списке матчей;
- полный список групп ставок и коэффициентов выбранного матча;
- субматчи: таймы, угловые, карточки, фолы и другие дополнительные события;
- основные показатели Live-статистики;
- информацию о наличии Live 3D Tracker и видеотрансляции.

Sport Line API работает через REST API. Для получения актуальных данных Ваше приложение
выполняет обычные HTTP-запросы.

Подключение через WebSocket находится в разработке и пока недоступно для рабочей
интеграции.

## 2. Что необходимо для подключения

Чтобы подключить Sport Line API, Вам необходимо:

1. Написать [менеджеру SportAPI в Telegram](https://t.me/suport_sportapi) и сообщить,
   что Вы хотите подключить спортивную линию.
2. Получить у менеджера базовый URL API и персональный ключ доступа.
3. Уточнить, какие виды спорта и языки входят в Ваш тариф.
4. Сохранить ключ в защищённых настройках backend-приложения.
5. Передавать ключ в HTTP-заголовке `Package` при каждом запросе.

Базовый URL может отличаться для разных подключений. Во всех примерах замените
`https://YOUR_API_DOMAIN` на адрес, полученный от менеджера.

Ключ передаётся так:

```http
Package: YOUR_API_KEY
```

Не добавляйте ключ в URL и не размещайте его в браузерном JavaScript, мобильном
приложении, публичном репозитории или сообщениях об ошибках. Рекомендуется выполнять
запросы к Sport Line API через backend клиента.

Доступные виды спорта, языки и срок действия определяются тарифом Вашего ключа.

Подробно: [«Авторизация и доступ»](getting-started/authentication-and-access.md).

## 3. Как выполнить первый запрос

Для проверки подключения запросите Live-меню:

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

В этом запросе:

- `live` означает текущие Live-матчи;
- `ru` означает русский язык ответа;
- `Package` — HTTP-заголовок с Вашим API-ключом.

Успешный ответ имеет общую оболочку:

```json
{
  "status": 1,
  "page": "/v1/menu",
  "body": [
    {
      "id": 1,
      "name": "Футбол",
      "counter": 53,
      "sub": []
    }
  ]
}
```

| Поле | Что означает |
|---|---|
| `status` | Статус выполнения. В успешном ответе обычно равен `1` |
| `page` | Метод API, который сформировал ответ |
| `body` | Данные выбранного метода |

Значения в примере показывают структуру ответа. Фактический состав спортивной линии
постоянно изменяется.

Подробно: [«Быстрый старт»](getting-started/quick-start.md).

## 4. Основная последовательность интеграции

Для основной интеграции используйте следующую цепочку:

```text
menu → events → event
```

### Шаг 1. Получите актуальное меню

```http
GET /v1/menu/{type}/{lang}
```

Метод `menu` за один запрос возвращает доступную структуру:

```text
вид спорта → страна → турнир
```

Из ответа выберите актуальные `sportId` и `tournamentId`.

Подробно: [`menu` — меню спортивной линии](api-reference/menu.md).

### Шаг 2. Получите список матчей

```http
GET /v1/events/{sportId}/{tournamentId}/sub/50/{type}/{lang}
```

Для метода `events`:

- используйте только формат `sub`;
- передавайте `50` в обязательном сегменте `count`;
- передайте ID конкретного турнира или `tournamentId=0`, чтобы получить матчи всех
  турниров выбранного вида спорта.

Параметр `count` больше не ограничивает количество результатов. Значение `50` сохранено
в URL для совместимости, а API возвращает все доступные матчи выбранной выборки.

Ответ группируется по турнирам:

```text
body
└── турнир
    └── events_list
        └── матчи
```

В `game_oc_list` каждого матча находится краткий список основных коэффициентов. Состав
этого списка зависит от вида спорта. Например, в футболе может использоваться группа
`1X2`, в баскетболе — победа первой или второй команды, а в теннисе нет исхода на ничью.

Не привязывайте интерфейс к одному постоянному набору названий исходов. Читайте
фактические группы и коэффициенты из ответа.

Подробно: [`events` — список матчей](api-reference/events.md).

### Шаг 3. Получите подробные данные матча

Возьмите `game_id` выбранного матча из ответа `events` и выполните запрос:

```http
GET /v1/event/{gameId}/group/{type}/{lang}
```

Для метода `event` используется только формат `group`. API уже:

- распределяет исходы по группам ставок;
- формирует колонки внутри групп;
- сортирует исходы по значениям.

Сохраняйте порядок групп, колонок и исходов, который вернул API.

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

Подробно: [`event` — конкретный матч](api-reference/event.md).

### Используйте только актуальные ID

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

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

Перед запросом `events` проверяйте, что выбранные `sportId` и `tournamentId` всё ещё
присутствуют в актуальном меню того же типа `live` или `line`.

## 5. Prematch и Live

Sport Line API разделяет данные на два типа:

| Значение в URL | Что возвращает |
|---|---|
| `line` | Prematch — матчи, которые ещё не начались |
| `live` | Live — матчи, которые проходят сейчас |

Prematch- и Live-данные нужно запрашивать и хранить отдельно.

Когда матч переходит из Prematch в Live, для него создаётся новый `game_id`. Live-ID не
совпадает с Prematch-ID, поэтому не связывайте две версии матча по `game_id`.

Если матч больше недоступен по прежнему ID, метод `event` может вернуть:

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

Это сообщение не объясняет причину. Матч мог перейти в Live с новым ID, быть отменён или
исчезнуть из линии по другой причине. После такого ответа прекратите запрашивать старый
`game_id` и обновите актуальное меню и список матчей.

## 6. Какие данные возвращаются

### Матч

Объект матча может содержать:

- `game_id` — ID матча для метода `event`;
- `game_start` — время начала в формате Unix Timestamp, в секундах;
- данные вида спорта, страны и турнира;
- названия и ID команд или участников;
- счёт, период и таймер Live-матча;
- группы ставок и коэффициенты;
- статистику и субматчи;
- поля трекера и видео, если они доступны.

Поле `timer` передаётся в секундах. Для отображения минут разделите значение на `60` и
при необходимости округлите его для интерфейса. Не отправляйте запрос каждую секунду
только для обновления таймера: изменяйте отображение локально и синхронизируйте его при
следующем плановом запросе.

Подробно: [«Модель данных: матч»](data-models/match.md).

### Коэффициенты

Структура коэффициентов выглядит так:

```text
game_oc_list
└── группа ставок
    └── oc_list
        └── колонка
            └── исходы и коэффициенты
```

Основные поля одного исхода:

| Поле | Что означает |
|---|---|
| `oc_name` | Название исхода |
| `oc_rate` | Текущее значение коэффициента |
| `oc_size` | Значение форы, тотала или другого параметра |
| `oc_pointer` | Уникальный код ставки или исхода |
| `oc_block` | Признак блокировки исхода |

Если подключена отдельная система приёма и расчёта ставок, именно `oc_pointer`
используется для передачи выбранного исхода в эту систему. Формат передачи описан на странице
[«Указатель ставки»](https://sportapi.net/ru/docs/coupon/bet-placement/bet-pointer.html), а следующий запрос — в разделе
[«Создание купона»](https://sportapi.net/ru/docs/coupon/bet-placement/place-coupon.html).

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

### Субматчи

Субматчи — это отдельные события внутри основного матча. Например:

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

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

Коэффициенты ответа относятся только к выбранному субматчу. Например, при запросе
«Угловые первого тайма» API возвращает коэффициенты только на угловые первого тайма, а
не на весь матч и не на все угловые матча.

Подробно: [«Дополнительные матчи и субматчи»](data-models/sub-events.md).

### Live-статистика

Основная Live-статистика находится в `stat_list` и возвращается только для Live:

- в списке матчей `events`;
- в подробном ответе конкретного матча `event`.

Набор показателей зависит от вида спорта и конкретного матча. Это основные текущие
характеристики Live-матча, а не отдельное API подробной спортивной аналитики.

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

Подробно: [«Статистика матча»](data-models/live-statistics.md).

Полная таблица JSON-полей находится в
[«Едином справочнике полей Sport Line API»](data-models/field-reference.md).

## 7. Дополнительные методы

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

Основная рекомендуемая цепочка остаётся прежней:

```text
menu → events → event
```

| Метод | Назначение | Особенность |
|---|---|---|
| [`sports`](api-reference/optional-methods/sports.md) | Получить виды спорта | Пошаговая альтернатива `menu` |
| [`countries`](api-reference/optional-methods/countries.md) | Получить страны выбранного вида спорта | Используется после `sports` |
| [`tournaments`](api-reference/optional-methods/tournaments.md) | Получить турниры выбранных спорта и страны | Используется после `countries` |
| [`topmatches`](api-reference/optional-methods/topmatches.md) | Получить готовую подборку топ-матчей | Поддерживает Live и Prematch |
| [`toplist`](api-reference/optional-methods/toplist.md) | Получить топ-матчи выбранного вида спорта | Только Prematch |
| [`search`](api-reference/search.md) | Найти матчи по тексту | Текст нужно кодировать для URL |

Обычно лучше использовать `menu`, потому что он за один запрос возвращает виды спорта,
страны и турниры. Цепочка `sports → countries → tournaments` требует трёх запросов и
предназначена для отдельных сценариев интерфейса.

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

```text
?cybersport=true
```

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

## 8. Готовые иконки

SportAPI предоставляет стандартные иконки. Подставьте актуальное значение из ответа API
в соответствующий URL:

| Объект | URL |
|---|---|
| Вид спорта | `https://cdn.sportapi.net/sports/v1/color/{sportId}.webp` |
| Страна | `https://cdn.sportapi.net/flags/v1/color/{countryId}.webp` |
| Турнир | `https://cdn.sportapi.net/tournaments/v1/color/{tournamentId}.webp` |
| Команда или участник | `https://cdn.sportapi.net/opp/v1/color/{iconName}.webp` |

Для команды или участника используйте `opp_1_icon` или `opp_2_icon`. Перед подстановкой
в `{iconName}` уберите исходное расширение файла, если оно присутствует.

## 9. Обновление данных

Каждый REST-запрос возвращает снимок данных на момент обращения. Чтобы получать
изменения счёта, периода, статистики и коэффициентов, повторяйте запросы с рекомендуемым
интервалом.

| Данные или метод | Live | Prematch (`line`) |
|---|---:|---:|
| `menu` | не менее 20 секунд | не менее 60 секунд |
| `sports`, `countries`, `tournaments` | не менее 60 секунд | не менее 120 секунд |
| `events` | не менее 7 секунд | не менее 30 секунд |
| `event` | не менее 5 секунд | не менее 30 секунд |
| `topmatches` | не менее 30 секунд | не менее 120 секунд |
| `toplist` | не используется | не менее 120 секунд |

Интервал «не менее 5 секунд» означает, что запрос не нужно отправлять чаще одного раза
в 5 секунд. Если менеджер предоставил другие интервалы для Вашего подключения,
используйте значения менеджера.

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

Подробно:
[«Рекомендации по обновлению данных»](getting-started/update-guidelines.md).

## 10. Live 3D Tracker

Live 3D Tracker — это отдельный готовый виджет визуализации Live-матча. Sport Line API
не передаёт данные для самостоятельной отрисовки трекера. Он возвращает ID готового
виджета в поле `zp`.

```text
gameid трекера = zp из Sport Line API
```

Если `zp` равен `null`, трекер для этого матча недоступен. Не подставляйте вместо `zp`
значение `game_id` или другой идентификатор.

Трекер можно показывать только для Live-матча, если:

- `zp` заполнен;
- вид спорта поддерживается трекером;
- у клиента есть активный ключ трекера;
- домен клиента разрешён для этого ключа;
- вид спорта и язык входят в тариф.

Поддерживаемые виды спорта:

| ID | Вид спорта |
|---:|---|
| `1` | Футбол |
| `2` | Хоккей |
| `3` | Баскетбол |
| `4` | Теннис |
| `5` | Бейсбол |
| `6` | Волейбол |
| `7` | Регби |
| `8` | Гандбол |
| `10` | Настольный теннис |
| `13` | Американский футбол |
| `17` | Водное поло |
| `21` | Дартс |
| `26` | Формула-1 |
| `28` | Австралийский футбол |
| `44` | Скачки |
| `66` | Крикет |
| `86` | CS:GO / киберспорт |

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

Готовый виджет подключается прямым `iframe` или через `embed.js`.

- [Краткое описание связи Sport Line API с трекером](additional-services/live-3d-tracker.md)
- [Полная инструкция по подключению Live 3D Tracker](https://sportapi.net/ru/docs/live-3d-tracker/service-overview.html)
- [Задание для ИИ-агента по интеграции Tracker](https://sportapi.net/ru/docs/live-3d-tracker/ai-agent-instructions.html)
- <a href="https://bet-embed-sport-tracker-stage.vercel.app/showcase" target="_blank" rel="noopener noreferrer">Демонстрация внешнего вида</a>

Демонстрационная страница показывает внешний вид и не использует реальные Live-данные.

## 11. Видеотрансляции

Sport Line API показывает наличие видеотрансляции Live-матча с помощью двух полей:

| Поле | Значение |
|---|---|
| `va` | `1` — трансляция есть; `null` — трансляции нет |
| `vi` | Строковый ID видеотрансляции или `null` |

Значение `va: 0` не используется. Даже если `vi` содержит только цифры, сохраняйте его
как строку.

Показывайте видео только при `va: 1` и заполненном `vi`. Само значение `vi` не является
URL видеопотока или готовым адресом `iframe`: оно передаётся в отдельный готовый
видеовиджет.

Видео доступно только для части Live-матчей. SportAPI не транслирует матчи топовых
спортивных лиг. Не обещайте наличие видео для конкретного соревнования или матча до
проверки актуальных `va` и `vi`.

Подробно: [«Видеотрансляции в Sport Line API»](additional-services/video-streaming.md).

## 12. Обработка ошибок

Ошибка API обычно возвращается в формате:

```json
{
  "error_code": 100,
  "error_message": "Invalid Package"
}
```

Проверяйте наличие `error_code` и `error_message`, а не только HTTP-статус.

| `error_message` | Что проверить |
|---|---|
| `Missing Package header` | Передан ли HTTP-заголовок `Package` |
| `Invalid Package` | Правильно ли скопирован ключ |
| `Package has expired` | Активен ли ключ и не закончился ли срок доступа |
| `Access denied` | Входит ли вид спорта или запрошенная возможность в тариф |
| `Invalid language` | Поддерживается ли код языка |
| `The language is not available in your package.` | Входит ли язык в тариф ключа |
| `Wrong data type (accept only live or line)` | Правильно ли указан тип `live` или `line` |

Пустой массив `body: []` не всегда является ошибкой. Он может означать, что в текущей
выборке сейчас нет доступных данных.

Подробно: [«Обработка ошибок»](getting-started/error-handling.md).

## 13. Примеры интеграции

Готовые примеры используют вымышленные ключи и базовые URL:

- [cURL](examples/curl.md)
- [JavaScript для Node.js](examples/javascript.md)
- [Python](examples/python.md)
- [PHP](examples/php.md)

Это лёгкие рабочие примеры интеграции, а не готовые SDK. Они показывают авторизацию,
основную цепочку `menu → events → event` и обработку ответов.

Полные реальные JSON-ответы без API-ключей:
[«Проверочные ответы Sport Line API»](examples/json-responses/README.md).

## 14. Подробная документация

### Начало работы

- [Быстрый старт](getting-started/quick-start.md)
- [Авторизация и доступ](getting-started/authentication-and-access.md)
- [Основные понятия](getting-started/core-concepts.md)
- [Рекомендации по обновлению](getting-started/update-guidelines.md)
- [Обработка ошибок](getting-started/error-handling.md)

### Основные методы

- [`menu`](api-reference/menu.md)
- [`events`](api-reference/events.md)
- [`event`](api-reference/event.md)

### Модели данных

- [Общий формат ответа](data-models/response-format.md)
- [Матч](data-models/match.md)
- [Коэффициенты и группы ставок](data-models/odds.md)
- [Статистика матча](data-models/live-statistics.md)
- [Дополнительные матчи и субматчи](data-models/sub-events.md)
- [Единый справочник полей](data-models/field-reference.md)

## 15. Поддержка

Если запрос не работает, отправьте менеджеру:

- URL запроса без API-ключа;
- время выполнения запроса;
- HTTP-статус;
- `error_code` и `error_message`;
- используемые тип линии, язык и ID;
- пример кода без секретных данных.

Не отправляйте API-ключ в общий чат или публичную задачу.

- Поддержка SportAPI: [@suport_sportapi](https://t.me/suport_sportapi)
- Официальный сайт: [sportapi.net](https://sportapi.net)
