Общий формат ответа Sport Line API

Какие форматы ответа встречаются

Sport Line API может вернуть три основных типа JSON-ответа:

1. Успешную оболочку с данными в body.
2. Служебное сообщение метода event внутри body.message.
3. Ошибку с полями error_code и error_message без обычной оболочки.

ответ Sport Line API
├── status + page + body       → данные или пустая выборка
├── status + page + body.message → состояние конкретного матча
└── error_code + error_message → ошибка доступа или параметров

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

Успешная оболочка

Обычный успешный ответ содержит три поля верхнего уровня:

{
  "status": 1,
  "page": "/v1/sports",
  "body": [
    {
      "id": 1,
      "name": "Футбол",
      "counter": 39
    }
  ]
}

В документации не подтверждены другие значения status. Не создавайте бизнес-логику на предположениях о значениях 0, 2 или других неподтверждённых статусах.

Поле status

В обычном успешном ответе:

{
  "status": 1
}

Однако status: 1 означает, что API сформировал корректный ответ. Это значение не гарантирует, что body содержит запрошенные данные.

Например, сообщение о недоступном матче также возвращается со status: 1:

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

Поэтому после проверки status всегда анализируйте тип и содержимое body.

Поле page

page показывает, какой метод сформировал ответ.

В ответе topmatches фактически используется строка /v1/topmathes без буквы c. Это текущее значение API, а не путь, по которому нужно выполнять запрос.

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

Поле body

Тип и вложенная структура body зависят от метода.

Для метода event объект body также может содержать только поле message. Эту структуру нужно проверять до разбора полей матча.

Пример ответа со списком

Большинство методов возвращает массив в body:

{
  "status": 1,
  "page": "/v1/countries",
  "body": [
    {
      "id": 1,
      "name": "Международные",
      "sport_id": 1,
      "counter": 8
    }
  ]
}

Структура элементов массива зависит от метода. Нельзя обрабатывать menu, events и search одним и тем же парсером только потому, что их body является массивом.

Пример ответа конкретного матча

Метод event возвращает объект матча непосредственно в body:

{
  "status": 1,
  "page": "/v1/event",
  "body": {
    "game_id": 746146992,
    "game_mid": 746146992,
    "sport_id": 1,
    "opp_1_name": "Арсенал",
    "opp_2_name": "Ковентри Сити",
    "game_oc_counter": 278
  }
}

Не ожидайте массив внутри body метода event и не применяйте к нему парсер метода events.

Пустая выборка

Если по условиям запроса нет доступных данных, API может вернуть пустой массив:

{
  "status": 1,
  "page": "/v1/events",
  "body": []
}

Пустой body не обязательно является ошибкой. Он может означать, что:

• для выбранного вида спорта или турнира сейчас нет матчей;
• в выбранном типе линии нет доступных событий;
• поиск не нашёл совпадений;
• навигационный раздел сейчас пуст.

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

Служебное сообщение в body.message

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

Матч не найден

{
  "status": 1,
  "page": "/v1/event",
  "body": {
    "message": "Game not found"
  }
}

Матч больше недоступен

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

Game id finished не сообщает, почему матч исчез. Он мог перейти из Prematch в Live с новым game_id, быть отменён или стать недоступным по другой причине.

После получения сообщения:

1. Не пытайтесь разобрать body как объект матча.
2. Прекратите частое обновление старого game_id.
3. Обновите список матчей методом events.
4. Не присваивайте матчу статус «завершён», «начался» или «отменён» только на основании текста сообщения.

Формат ошибки API

Ошибки доступа и проверки параметров возвращаются без полей status, page и body:

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

Не полагайтесь только на HTTP-статус. После разбора JSON отдельно проверяйте наличие error_code и error_message.

Полный список подтверждённых ошибок и рекомендации находятся в документе «Обработка ошибок».

Рекомендуемый порядок разбора ответа

получить HTTP-ответ
        ↓
разобрать JSON
        ↓
есть error_code/error_message?
  ├── да  → обработать ошибку API
  └── нет
        ↓
есть status/page/body?
  ├── нет → неизвестный формат ответа
  └── да
        ↓
body содержит message?
  ├── да  → обработать состояние метода event
  └── нет
        ↓
body — пустой массив?
  ├── да  → показать пустое состояние
  └── нет → разобрать данные по схеме запрошенного метода

Пример общей проверки на JavaScript:

function parseSportApiResponse(payload) {
  if (
    payload &&
    typeof payload === 'object' &&
    !Array.isArray(payload) &&
    payload.error_code !== undefined
  ) {
    return {
      type: 'error',
      code: payload.error_code,
      message: payload.error_message
    };
  }

  if (
    !payload ||
    typeof payload !== 'object' ||
    Array.isArray(payload) ||
    payload.status === undefined ||
    typeof payload.page !== 'string' ||
    !('body' in payload)
  ) {
    return { type: 'unknown-response', payload };
  }

  if (
    payload.body &&
    !Array.isArray(payload.body) &&
    typeof payload.body === 'object' &&
    typeof payload.body.message === 'string'
  ) {
    return { type: 'event-message', message: payload.body.message };
  }

  if (Array.isArray(payload.body) && payload.body.length === 0) {
    return { type: 'empty', data: [] };
  }

  return {
    type: 'data',
    page: payload.page,
    data: payload.body
  };
}

После общей проверки данные всё равно нужно передать парсеру конкретного метода.

Что логировать

Для диагностики сохраняйте:

• время запроса и часовой пояс;
• запрошенный метод;
• тип линии live или line;
• HTTP-статус;
• значение page;
• error_code и error_message, если они есть;
• body.message, если оно есть;
• использованные ID и язык.

Не сохраняйте действующий API-ключ в публичных журналах, сообщениях об ошибках или клиентской аналитике.

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

1. Всегда сначала разбирайте верхний уровень JSON.
2. Проверяйте error_code до обработки обычной оболочки.
3. Не считайте status: 1 гарантией наличия данных.
4. Учитывайте, что body может быть массивом или объектом.
5. Проверяйте body.message до разбора объекта матча.
6. Обрабатывайте пустой массив как отсутствие данных, а не как системную ошибку.
7. Выбирайте схему данных по запрошенному методу, а не только по значению page.
8. Не полагайтесь только на HTTP-статус при определении ошибки API.

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

• Быстрый старт
• Авторизация и доступ
• Обработка ошибок
• Единый справочник полей
• Методы Sport Line API