Содержание

Описание методов
Предусловия и ограничения
Формат запроса (Request Body)
Формат ответа (Responses Code)
Справочник типов событий (AlarmType)

Описание методов

В настоящий момент корректное взаимодействие с методами API гарантируется только при использовании клиента Postman (файлы коллекции и окружения).

Внешний контур событий видеоаналитики предоставляет доступ к событиям (alarms) и сведениям о медиафайлах событий по протоколу OData v4. Контур предназначен для самостоятельной интеграции: выгрузка событий по своим ТС, контроль наличия видеодоказательств, построение собственных отчётов.

Метод	Описание
GET /odata/VaAlarms	Возвращает список событий видеоаналитики по доступным ТС. Поддерживает выбор полей, фильтрацию, сортировку и постраничный вывод через query options OData (поддерживает $filter, $select, $orderby, $top, $skip, $count). Состав выборки ограничен терминалами, доступными учётной записи по её правам.
GET /odata/VaAlarms({key})	Одно событие по идентификатору AlarmId. Каноническая форма записи ключа в OData. Значение подставляется из переменной alarmId, которую заполняет скрипт запроса коллекции.
GET /odata/VaAlarms/{key}	Событие по идентификатору, форма записи ключа через сегмент пути. Форма эквивалентна методу GET /odata/VaAlarms({key})
GET /odata/VaAlarms/$count	Количество событий числом, без выгрузки данных. Поддерживает $filter

Предусловия и ограничения

Требуется аутентификация
При работе с методом УЗ должна быть присвоена роль со следующими скоупами для работы:

Метод	Назначение метода	Scope	Чек-боксы в справочнике ролей для scope
GET /odata/VaAlarms	Выборка событий видеоаналитики	externalVaAlarms:read	«Просмотр таблицы событий», «Просмотр таблицы событий с ограничениями»
GET /odata/VaAlarms({alarmId})	Одно событие по идентификатору	externalVaAlarms:read	«Просмотр таблицы событий», «Просмотр таблицы событий с ограничениями»

Ограничения:

Все методы только на чтение.
Размер страницы $top - не более 1000; большие объёмы - постраничный обход с $skip и сортировкой, дополненной ключом AlarmId.
Скачивание содержимого видеофайлов и фотоснимков - в разработке: сейчас API отдаёт метаданные, файлы доступны через интерфейсы SKAI.
Пакетные запросы OData не поддерживаются.
Скорость в поле Speed - километры в час.

Формат запроса (Request Body)

Атрибут	Поле	Тип	Обязательность	Описание
$filter	beginFrom	String	Нет	Дата и время начала периода фильтрации. ISO 8601. Пример: 2026-08-01T00:00:00Z
$filter	beginTo	String	Нет	Дата и время конца периода фильтрации. ISO 8601. Пример: 2026-08-02T00:00:00Z
$select	AlarmId, TelemetryId, Begin, End, Type, AlarmStatus, RegulationStatus, UnitStateNumber, DriverFullName, VideoCount	String	Нет	Массив полей, включаемых в ответ. Пример: ["AlarmId","Begin","UnitStateNumber"]
$orderBy		String	Нет	Поле и направление сортировки (asc / desc). Пример: Begin asc
$top		Integer	Нет	Максимальное количество возвращаемых записей. Пример: 100
$skip		Integer	Нет	Количество пропускаемых записей от начала выборки. Применяется вместе с $top.
$count		Boolean	Нет	Признак включения общего количества записей в ответ в поле @odata.count. Не учитывает $top и $skip.

Пример запроса:

GET /odata/VaAlarms?$filter=Begin ge 2026-08-01T00:00:00Z and Type eq 'Drowsiness'&$top=100

Формат ответа (Responses Code)

В случае успеха метод возвращает ответ с кодом 200 и телом ответа в формате OData JSON:

Поле	Атрибут	Тип	Описание
@odata.context	-	String	URL-ссылка на контекст метаданных OData
value	-	Array	Массив объектов с данными
	AlarmId	UUID	Уникальный идентификатор события, ключ сущности
	TerminalId	UUID	Идентификатор терминала
	UnitId	UUID или null	Идентификатор транспортного средства
	UnitName	String или null	Название транспортного средства
	UnitStateNumber	String или null	Государственный номер ТС
	TerminalSerialId	String или null	Серийный номер терминала
	DeviceTypeName	String или null	Тип оборудования
	DriverId	UUID или null	Идентификатор водителя
	DriverFullName	String или null	Полное имя водителя
	AlarmStatus	String.Enum: Created Accepted Rejected Deleted	Статус валидации события
	Begin	DateTime	Дата и время начала события, ISO 8601 со смещением
	End	DateTime	Дата и время окончания события
	TimeZoneOffset	String	Смещение часового пояса в формате ISO 8601
	Type	String	Тип события (например, Drowsiness)
	Comment	String или null	Комментарий к событию
	TelemetryId	String или null	Идентификатор события, сгенерированный оборудованием; связывает событие с медиафайлами
	Speed	Number	Скорость ТС в момент события в км/ч
	Latitude	Double или null	Широта координаты
	Longitude	Double или null	Долгота координаты
	Address	String или null	Адрес места события
	VideoCount	Integer	Число загруженных и неудалённых видеофайлов события
	VideoSizeBytes	Integer	Общий размер видеофайлов события в байтах
	CameraIds	Integer[] или null	Идентификаторы камер, подключённых на момент события
	RequestedCameraIds	Integer[] или null	Идентификаторы запрошенных камер
	CreateVideoDate	DateTime или null	Дата и время создания первого видеофайла по событию
	ReceiptDate	DateTime	Дата и время получения события платформой
	AlarmModifiedDate	DateTime	Дата и время последнего изменения события
	ValidationModifiedDate	DateTime или null	Дата и время изменения валидации
	ValidationEndTimestamp	DateTime или null	Дата и время завершения валидации
	RegulationModifiedDate	DateTime или null	Дата последнего изменения реагирования
	RegulationStatus	Enum: Completed InProgress Canceled None	Статус реагирования

Пример ответа:

{
  "@odata.context": "https://public.skai.online/odata/$metadata#VaAlarms",
  "value": [{
    "AlarmId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "TerminalId": "b2c3d4e5-0000-4000-8000-000000000001",
    "UnitId": "a1b2c3d4-0000-4000-8000-000000000002",
    "UnitName": "Газель 27057",
    "UnitStateNumber": "А123ВС777",
    "TerminalSerialId": "9C05123456",
    "DeviceTypeName": "ADPlus",
    "DriverId": null,
    "DriverFullName": null,
    "AlarmStatus": "Accepted",
    "Begin": "2026-08-01T07:14:22+03:00",
    "End": "2026-08-01T07:14:30+03:00",
    "TimeZoneOffset": "PT3H",
    "Type": "Drowsiness",
    "Comment": null,
    "TelemetryId": "17223456789012345",
    "Speed": 62,
    "Latitude": 55.751244,
    "Longitude": 37.618423,
    "Address": "Москва, ул. Тверская, 7",
    "VideoCount": 2,
    "VideoSizeBytes": 10485760,
    "CameraIds": [1, 3],
    "RequestedCameraIds": [1, 2, 3],
    "CreateVideoDate": "2026-08-01T07:15:40+03:00",
    "ReceiptDate": "2026-08-01T07:14:35+03:00",
    "AlarmModifiedDate": "2026-08-01T09:02:11+03:00",
    "ValidationModifiedDate": "2026-08-01T09:02:11+03:00",
    "ValidationEndTimestamp": "2026-08-01T09:02:11+03:00",
    "RegulationModifiedDate": null,
    "RegulationStatus": null
  }]
}

В случае ошибок авторизации или валидации запроса метод возвращает код, соответствующий ошибке, и тело в формате OData:

Тело ответа		Тип	Обязательность	Описание
error		Object[]	Да	Корневой объект, содержащий информацию об ошибке
code		String	Да	Машиночитаемый код ошибки
message		String	Да	Человекочитаемое сообщение об ошибке
target		String	Нет	Цель ошибки (например, имя поля)
	details	Object[]	Да	Массив детализированных ошибок
200 (пусто)	-			Учётной записи не открыт доступ к данным: не назначены транспортные средства, либо не выдан доступ на просмотр
400	Bad Request			Значение $top свыше предела 1000. Ошибка синтаксиса, неизвестное поле, $top > 1000
401	Unautorized			Токен невалидный или истек срок действия. Запрос без авторизации. Ожидаемый код 401 подтверждает, что маршрут опубликован и защищён. Если вместо 401 приходит 404, неверен базовый адрес или контур.
403	Forbidden			Учётной записи не выдано нужное право
404	Not Found			Обращение по заведомо отсутствующему ключу. Такой же ответ приходит, если запись существует, но недоступна учётной записи по её правам: различить эти случаи на стороне клиента нельзя.

Справочник типов событий (AlarmType)

Значение поля Type передаётся строкой. Категории соответствуют группировке типов в интерфейсах платформы.

Код	Значение	Категория	Описание
1	NoDriver	DMS	Отсутствие водителя
2	Drowsiness	DMS	Сонливость
3	Distraction	DMS	Отвлечение внимания, водитель не смотрит на дорогу
4	Smoking	DMS	Курение во время движения
5	Phone	DMS	Использование телефона во время движения
6	SeatBelt	DMS	Не пристёгнутый ремень безопасности
7	Yawning	DMS	Зевота
8	CollisionWarning	ADAS	Предупреждение о столкновении
9	DangerousDistance	ADAS	Опасная дистанция
10	RoadMarkingsViolation	ADAS	Опасное пересечение разметки
11	PedestrianWarning	ADAS	Предупреждение о пешеходе или велосипедисте
12	SpeedLimitViolation	БВ	Нарушение скоростного режима
13	SharpAcceleration	БВ	Резкое ускорение
14	SharpBraking	БВ	Резкое торможение
15	SharpLeftTurn	БВ	Резкий поворот налево
16	SharpRightTurn	БВ	Резкий поворот направо
17	Overturn	БВ	Переворот
18	Collision	БВ	Столкновение
19	VideoLoss	Прочее	Потеря видео
20	LossGps	Прочее	Потеря GPS
21	EmergencyAlarm	DMS	Нажатие тревожной кнопки
22	MotionDetection	Прочее	Движение в кадре
23	PowerDisconnect	Прочее	Отключение устройства
24	LeftBlindSpotDanger	Прочее	Опасность в слепой зоне слева
25	RightBlindSpotDanger	Прочее	Опасность в слепой зоне справа
26	StorageError	Прочее	Ошибка бортового хранилища
27	LowVoltage	Прочее	Низкое напряжение
28	TemperatureChangeAbnormal	Прочее	Аномальное изменение температуры, перегрев устройства
29	DriverVerificationFailed	Прочее	Идентификация водителя не пройдена
30	UnsafeGlasses	DMS	Несоответствующие очки
31	Io1	Прочее	Срабатывание датчика IO1
32	Io2	Прочее	Срабатывание датчика IO2
33	Io3	Прочее	Срабатывание датчика IO3
34	Io4	Прочее	Срабатывание датчика IO4
35	Io5	Прочее	Срабатывание датчика IO5
36	Io6	Прочее	Срабатывание датчика IO6
37	Io7	Прочее	Срабатывание датчика IO7
38	Io8	Прочее	Срабатывание датчика IO8
39	Io9	Прочее	Срабатывание датчика IO9
40	Sabotage	DMS	Саботаж камеры, накрытие камеры
41	StopSignSignal	ADAS	Сигнал о знаке СТОП
42	SpeedLimitSign	ADAS	Знак ограничения скорости
43	Meal	DMS	Приём пищи во время движения
44	GeofenceOne	Прочее	Геозона 1; в интерфейсах отображается как вход в геозону
45	GeofenceTwo	Прочее	Геозона 2; в интерфейсах отображается как выход из геозоны
46	FrontBlindSpotDanger	Прочее	Опасность в слепой зоне спереди
47	BackBlindSpotDanger	Прочее	Опасность в слепой зоне сзади

Публичный API [3.0]. Видеоаналитика. Список событий видеоаналитики