Видеосервер API

REST API для интеграций: список объектов, последнее положение, история треков, команды регистраторам и сводка по видео (каналы, архив, неисправности).

Базовый адрес: https://videoapi.glonassservice.ru. Все пути начинаются с /api/v1. Формат — JSON, кодировка UTF-8, только HTTPS.

Быстрый старт

# 1. получить токен
curl -s -d 'grant_type=password&username=ЛОГИН&password=ПАРОЛЬ' \
  https://videoapi.glonassservice.ru/api/v1/auth/login
# → {"access_token":"...","refresh_token":"...","expires_in":1794067466,"token_type":"Bearer"}

# 2. список объектов с последним положением
curl -s -H "Authorization: Bearer $TOKEN" \
  'https://videoapi.glonassservice.ru/api/v1/units?incllsv=1&pl=50'

# 3. сводка по видео: объекты с неисправностями
curl -s -H "Authorization: Bearer $TOKEN" \
  'https://videoapi.glonassservice.ru/api/v1/video/units?hasErrors=true'

Логин и пароль — те же, что для входа в веб-интерфейс. Для постоянных интеграций удобнее API-ключ.

Авторизация

Все методы, кроме входа и служебных адресов, требуют заголовок Authorization: Bearer <значение>. Значение — токен входа или API-ключ.

Токены

grant_type=password&username=<логин>&password=<пароль>

→ 200 {"access_token":"...","refresh_token":"...","expires_in":1794067466,"token_type":"Bearer"}

{"refresh_token":"..."}

{"id":1,"login":"ivan","name":"Иван","role":"manager","companyId":2,
 "companyName":"Ромашка","companyInn":"7707083893","viaApiKey":false,"canWrite":false}

Токены — JWT (HS256), как у Gelios. expires_in — момент истечения access-токена в unix-секундах (так же, как у Gelios, а не число секунд). access_token действует 1 час, refresh_token — 30 суток. Смена пароля или удаление пользователя сразу отзывает все его токены. После 5 неудачных входов с одного адреса вход временно блокируется (429).

API-ключи

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

{"name":"CRM","write":false}
→ 201 {"id":3,"name":"CRM","key":"vsk_...","write":false}

Права доступа

Те же, что в веб-интерфейсе:

Чужой объект отвечает 404 — его существование не раскрывается. Команды доступны только администратору и только токену или ключу с правом записи (403 иначе).

Соглашения

• Идентификатор объекта (id, unit_id) — строка: номер терминала, может начинаться с нуля ("0120040"). Не приводите к числу.
• Время — unix-секунды, UTC.
• Постраничность: pl — размер страницы (1–1000, по умолчанию 100), po — смещение. Ответ: {"items":[…],"paginationMetadata":{"totalCount":73,"startRow":0,"endRow":50}}.
• Единицы: скорость — км/ч, пробег — км, координаты — градусы WGS-84.

Компании

{"items":[{"id":1,"name":"Ромашка","inn":"7707083893"}]}

ИНН — 10 цифр (организация) или 12 (ИП); может быть пустым.

Объекты

{"id":"018270814098","name":"АЗС","plate":"C868YM97","manufacturer":"72302","model":"MR9708E-B1",
 "iconType":"car","groupId":3,"groupName":"Одигитрия","companyId":2,
 "channelsCount":8,"online":true,"lastSeen":1794055748,
 "imei":"018270814098","hwManufacturer":"72302","hwType":"MR9708E-B1",
 "creator":{"id":8,"login":"hodegetria","legalName":"ООО Одигитрия"},
 "isBlock":false,"removed":false,"phone":"","unitType":"vehicle","currentUserAccess":7,
 "lastMsg":{…}}

channelsCount — число видеоканалов, online — регистратор на связи, lastSeen — время последнего пакета.

Создатель (владелец) объекта — creator — это верхний управляющий компании, которой принадлежит объект (компания определяется по группе объекта, в том числе вложенной в группу первого уровня). Если в компании нет управляющих, создателем указывается её самый ранний сотрудник; у объектов вне компаний — главный администратор. В creator всегда объект с id, login, legalName; id совпадает с id пользователя в разделе «Пользователи».

Поля imei (номер терминала), hwManufacturer, hwType, isBlock, removed, phone, unitType и currentUserAccess отдаются для совместимости с моделью объекта Gelios; значения isBlock, removed и phone у нас фиксированные (false, false, пусто).

{"unitIds":["0120040","018270814098"]}      // пустой список — все доступные

Последнее сообщение (lastMsg)

Положение — последняя точка с корректным фиксом, поэтому time может быть старше lastSeen (регистратор на связи, но спутников нет).

История

curl -s -H "Authorization: Bearer $TOKEN" \
  'https://videoapi.glonassservice.ru/api/v1/storage/messages?unit_id=0120040&time_from=1762400000&time_to=1762486400&columns=latitude,longitude,speed'

Точки с фиксом, по возрастанию времени. Поля: time, latitude, longitude, altitude, speed, course, valid, ignition, satellites, rssi, mileage, fuel, alarmBits. Если точек больше limit, в ответе truncated:true — сузьте период.

Команды

{"text":"...","type":"tcp"}
→ 201 {"taskId":12,"historyRowId":12,"status":"sent"}

• Текст — до 1000 байт; объект должен быть на связи (409 иначе); 502 — регистратор не принял.
• Статус sent означает «отправлено регистратору»; подтверждения исполнения нет.
• История хранит только команды, отправленные через этот API.

Пользователи

Раздел повторяет /api/v1/users Gelios. «Клиент» Gelios соответствует у нас компании с её пользователями; создавать и менять пользователей может только администратор токеном или ключом с правом записи. Администратор сервиса видит всех пользователей, управляющий — пользователей своей компании, обычный пользователь — себя.

Создатель — поле creator — у каждого пользователя это объект {id, login, legalName} (у главного администратора — он сам: 1С читает creator.id у каждого элемента). Для администратора, который читает список, верхние записи клиентов (управляющие компаний) показываются как его прямые подчинённые: у них creator.id равен id его сессии, как у Gelios. subordinatesCount — сколько пользователей создал этот пользователь.

{"login":"client1","password":"secret1","creatorId":1,"isAdmin":true,
 "legalName":"ООО Ромашка","email":"a@b.ru","phone":"+79001234567","isBlock":false,"inn":"7707083893"}
→ 201 {"id":12,"login":"client1","legalName":"ООО Ромашка","isAdmin":true,"role":"manager",
       "companyId":5,"companyName":"ООО Ромашка","inn":"7707083893","creator":{"id":1,"login":"admin"},…}

• login — 3–40 символов: латиница, цифры, _ . @ -; уникален (409, если занят). password — от 6 символов.
• creatorId — кто создаёт. Если это администратор, создаётся новый клиент: компания с названием legalName (если пусто — по логину) и первой группой объектов; такая компания уже есть — пользователь добавляется в неё. Если это сотрудник компании, пользователь попадает в его компанию. Создателем можно указать только того, кого вы видите; чужой creatorId отклоняется (400, «пользователь не найден»).
• isAdmin: true — управляющий компании (видит все её объекты и пользователей), false — обычный пользователь с доступом к корневым группам компании. Администраторов системы через API не создают.
• inn — наше дополнение: ИНН компании (10 или 12 цифр с проверкой).
• Прочие поля Gelios (billingInfo, extraInfo, smtpConfig и т. п.) принимаются и игнорируются: у нас нет биллинга и этих настроек.

Заблокированный пользователь не может войти ни в API, ни в веб-интерфейс, его токены перестают действовать.

Доступ пользователя к объектам

Доступ выдаётся по группам объектов (и только пользователям с role=user: управляющие видят всю компанию). PUT …/accesses/units/{unit_id} по одному объекту не поддерживается и отвечает 422.

Видео

Сводка о состоянии видео на объектах: сколько каналов, идёт ли поток, какова глубина архива, какие неисправности. Данные берутся из кэша сервера, регистраторы при запросе не опрашиваются.

{"unitId":"022000130712","name":"Кран","online":false,"channelsCount":6,"channelsActive":0,
 "videoPresent":false,
 "archive":{"known":false,"depthDays":null,"depthFrom":null,"checkedAt":null},
 "errors":[{"code":"device_offline","message":"регистратор не на связи","channel":null}]}

Живое видео

Номер канала — от 1 до channelsCount объекта. Параметр stream: sub — дополнительный поток (по умолчанию, меньше трафика), main — основной. Регистратор должен быть на связи (409 иначе). Видео идёт кодеком H.264.

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  'https://videoapi.glonassservice.ru/api/v1/video/units/018270814098/channels/1/live?stream=sub'

{"unitId":"018270814098","channel":1,"stream":"sub","expiresAt":1794057611,"ttl":300,
 "wsUrl":"wss://videoapi.glonassservice.ru/api/v1/video/live/1~0182…~sub~…",
 "httpUrl":"https://videoapi.glonassservice.ru/api/v1/video/live/1~0182…~sub~…",
 "snapshotUrl":"https://videoapi.glonassservice.ru/api/v1/video/snapshot/1~0182…~sub~…"}

Ссылки содержат короткоживущий билет: 5 минут на начало просмотра, после чего подключиться по ним нельзя (уже идущий поток не прерывается). Их можно отдавать плееру или браузеру, не раскрывая токен или ключ. Билет привязан к объекту, каналу и потоку, перестаёт действовать при смене пароля пользователя.

Можно обойтись без билета: GET /api/v1/video/units/{unit_id}/channels/{channel}/live с заголовком Authorization отдаёт тот же поток (WebSocket при запросе с Upgrade, иначе HTTP).

Снимки

curl -s -H "Authorization: Bearer $TOKEN" -o cam1.jpg \
  'https://videoapi.glonassservice.ru/api/v1/video/units/018270814098/channels/1/snapshot'

Снимок делается из живого потока: сервер дожидается ключевого кадра и отдаёт его как image/jpeg (разрешение — как у выбранного потока, sub или main). Обычно 1–3 секунды; если видео на канале не открыто, до 15–25 секунд на запуск. Ссылка snapshotUrl из запроса видеопотока работает без заголовка авторизации, её можно подставить в <img src>. Ошибки: 409 — регистратор не на связи, 502 — устройство не прислало видео.

Поля сводки

Коды ошибок

Ошибки и лимиты

Тело ошибки — {"detail":"текст"}.

Совместимость с Gelios

Формы запросов и ответов повторяют Gelios API (/api/v1/…, items + paginationMetadata, вход OAuth2 password): интеграции, написанные под Gelios, достаточно перенацелить на другой хост. Различия:

Служебные адреса

Без авторизации: GET / (имя и версия), /healthcheck, /heartbeat. Описание API (openapi.json) и Swagger — на портале документации.