BOX 3.x

API BOX 3.x

REST API BOX 3.x: получение токена, чтение профиля и событий, параметры пагинации, ответы и OpenAPI.

Для кого: разработчик / интегратор

Применимость: BOX 3.xВыбрать версию и роль →

Подробные инструкции

BOX 3.2: поля API и правила заполненияBOX 3.2

На этой странице

Точки входа

REST API покрывает прикладные и административные сущности BOX: камеры, события, сценарии, модели, пользователей, справочники, отчёты, аудит, видеоархив и специализированные модули. Интерактивный Swagger показывает методы, параметры, схемы запросов и ответы фактически опубликованного контура.

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

Откройте Swagger в своей установке по пути /api/docs/; описание API в формате OpenAPI доступно по /api/swagger.json. Адрес системы выдаёт её администратор.

BOX 3.2: интерактивная документация Swagger. Сверху — ссылка на OpenAPI-схему и кнопка Authorize, ниже — группы base и auth с методами ping, входа и чтения профиля. Набор методов проверяйте в своей установке. Открыть в полном размере

Авторизация

Для авторизации API используется OAuth 2.0 Password Flow. Токен выдаётся методом POST /api/statistics/auth/login/ и передаётся в защищённые запросы как Bearer-токен. Для проверки текущего пользователя доступен GET /api/statistics/auth/me/.

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

curl -H 'Authorization: Bearer <access_token>' \
  https://<box-host>/api/statistics/auth/me/

POST /auth/login/: форма и ответ

Метод POST /api/statistics/auth/login/ принимает application/x-www-form-urlencoded. Поля username и password обязательны; это не JSON-запрос. Дополнительно схема предусматривает grant_type со значением password, scope, client_id и client_secret. Последние поля используются только если это требуется настройкой сервера.

Полученный access_token передаётся в заголовке Authorization: Bearer. Ответ также содержит refresh_token; наличие поля password_expire_after_sec не означает срок жизни access_token — это отдельный параметр пароля.

Начало работы интеграционного клиента

1
GET /api/base/ping/
Проверка доступности API без изменения бизнес-данных.
↓ API доступен
2
POST /api/statistics/auth/login/
Отправить форму с учётными данными и получить access_token.
↓ Authorization: Bearer …
3
GET /api/statistics/auth/me/
Проверить текущего пользователя и доступ.
↓ Чтение данных
4
GET /api/statistics/event-storage/events/
Запросить небольшую страницу событий и проверить её формат.

Поле ответа	Тип	Смысл
access_token	string	Токен для защищённых запросов
refresh_token	string	Токен обновления сессии; следуйте схеме авторизации целевого сервера
token_type	string / null	В схеме по умолчанию bearer
password_expire_after_sec	integer / null	Информация об истечении пароля
wait_for_update	boolean	Дополнительный признак состояния учётной записи

POST /api/statistics/auth/login/ HTTP/1.1
Host: <box-host>
Content-Type: application/x-www-form-urlencoded

username=<urlencoded-username>&password=<urlencoded-password>&grant_type=password

GET /event-storage/events/: поиск и пагинация

Полный путь: /api/statistics/event-storage/events/. Пример читает первую страницу, ограничивает размер выдачи и сортирует по времени убывания. BOX_ORIGIN задаётся без завершающего слеша, BOX_ACCESS_TOKEN берётся из ответа авторизации. Команда не изменяет события.

Фильтры времени в OpenAPI имеют тип integer; единицы измерения нужно проверить на целевом контуре до задания диапазона. В примере временные фильтры намеренно не заданы. Для массивов используйте сериализацию query-параметров OpenAPI-клиента; в curl это повторение одноимённого параметра.

Query-параметр	Тип / значение по умолчанию	Назначение
page	integer · 1	Номер страницы
page_size	integer · 100	Число записей на странице
sorting	string · -timestamp	Порядок сортировки
from_time / to_time	integer / null	Границы времени; единицы уточняются в описании параметров API вашей установки
camera_ids	integer[]	Камеры, события которых нужны клиенту
scenario_version_ids	integer[]	Версии сценариев
confirmation_statuses	integer[]	Статусы подтверждения; значения перечисления смотрите в Swagger
messages_uuids	string[]	Поиск по идентификаторам сообщений

curl --fail-with-body --get \
  "${BOX_ORIGIN}/api/statistics/event-storage/events/" \
  -H "Authorization: Bearer ${BOX_ACCESS_TOKEN}" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=20" \
  --data-urlencode "sorting=-timestamp"

Разбор ответа списка событий

Коллекция возвращается в объекте StoredViolationEvents. Не обрабатывайте весь ответ как массив: события находятся в поле events. Схему каждого элемента определяет StoredViolationEvent целевого сервера. Приведённые ниже имена полей взяты из схемы API; ограничения размера страницы и правила дальнейшего обхода проверяйте на установленной версии.

Обрабатывайте пустую выдачу без ошибки.
Сохраняйте идентификаторы уже полученных событий при повторном опросе: появление новых записей может сдвигать страницы.
При 422 изучите ответ валидации и типы query-параметров. При ошибке доступа проверьте токен и область видимости роли.

Поле	Тип	Назначение
page	integer	Номер страницы
page_size	integer	Размер страницы
page_number	integer	Поле серверной пагинации; значение и правила использования проверяйте по описанию API установленной версии
total	integer	Общее количество записей выдачи
events	StoredViolationEvent[]	Массив событий; пустой массив допустим

Основные группы методов

Ориентируйтесь на бизнес-домен и теги Swagger, а не на внутреннее имя сервиса.

Задача	Группы API	Типичные операции
Источники видео	camera-storage, mediaserver, video-archive	Объекты, камеры, дерево, статусы, поток и архив
События	event-storage, event-filter, decision-matrix	Поиск, карточка, статусы, фильтры и правила реакции
Модели и сценарии	models-registry, scenario-storage, flows-manager	Версии, назначения, запуски и управление потоками
Пользователи и доступ	auth, access, audit	Вход, пользователь, роли, разрешения и журнал действий
Справочники и активы	directory-storage, asset-storage	Справочные сущности, файлы и медиаматериалы
Отчёты и интеграции	report generators, alerts, специализированные адаптеры	Выгрузки, уведомления и обмен со смежными системами

Первый безопасный запрос

Для проверки доступности без изменения данных используйте GET /api/base/ping/. Затем авторизуйтесь тестовой учётной записью, вызовите /api/statistics/auth/me/ и только после этого переходите к чтению бизнес-сущностей.

Не начинайте интеграцию с массовых POST, PUT или DELETE. Сначала зафиксируйте базовый URL, версию схемы, тестовые данные, пагинацию, часовой пояс, формат идентификаторов и ожидаемые коды ошибок.

curl https://<box-host>/api/base/ping/

Правила обмена данными

Сгенерированный по OpenAPI клиент ускоряет старт, но не заменяет согласование правил обмена данными между командами. Зафиксируйте владельца данных, допустимую частоту запросов, идемпотентность, повторные попытки, тайм-ауты, обработку 401/403/404/409/422/5xx и правила обновления версии.

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

Перед production

Прогоните интеграцию в тестовом контуре, ограничьте права клиента, включите аудит, исключите секреты и персональные данные из логов, настройте тайм-ауты и повторные попытки. Храните использованную OpenAPI-схему вместе с версией клиента и проверяйте изменения схемы API при каждом обновлении BOX.

Отдельная интеграционная учётная запись
Минимальные роли и область видимости
TLS и доверенный сертификат
Секреты во внешнем хранилище
Ограниченные тайм-ауты и retries
Аудит запросов и действий
Проверка совместимости OpenAPI
План отката клиента