Методы Integration API

1. Проверка Integration Key

Проверяет валидность ключа интеграции.

POST /v1/integration-key/validate

Заголовок	Тип	Обязательный	Описание
X-Integration-Key	string	да	ключ интеграции

Пример:

curl -X POST \
  "https://cloud.faceter.cam/integration-api/v1/integration-key/validate" \
  -H "X-Integration-Key: YOUR_INTEGRATION_KEY"

Response 200:

{ "isValid": true }

Поле	Тип	Описание
isValid	boolean	признак валидности ключа

2. Получение информации о камере

GET /v1/cameras/{cameraId}

Параметр	Тип	Описание
cameraId	uuid	идентификатор камеры

Пример:

curl -X GET \
  "https://cloud.faceter.cam/integration-api/v1/cameras/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-Integration-Key: YOUR_INTEGRATION_KEY"

Response 200:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "deviceId": "1fa85f64-5717-4562-b3fc-2c963f66afb1",
  "title": "Entrance Camera",
  "previewUrl": "https://example.com/preview.jpg",
  "archiveApiToken": { "signature": "string", "exp": 1712745600 },
  "archiveApiUrl": "https://archive.example.com",
  "archiveDays": 30,
  "liveRtspUrl": "rtsp://example.com/live",
  "liveHlsUrl": "https://example.com/live.m3u8",
  "isOnline": true,
  "lastOnlineDate": "2026-04-10T09:00:00Z",
  "cameraModel": "Model X",
  "platform": "Embedded",
  "serialNumber": "ABC123",
  "firmwareVersion": "1.0.0",
  "applicationVersion": "2.1.0",
  "isOwner": true,
  "isFullAccess": true,
  "isArchiveGranted": true,
  "isAudioGranted": true,
  "tempAccessExpiryDate": "2026-04-20T09:00:00Z",
  "location": {
    "id": "loc-1",
    "title": "Main Office",
    "room": { "id": "room-1", "title": "Hall" }
  }
}

Поле	Тип	Описание
id	uuid	идентификатор камеры
deviceId	uuid	идентификатор устройства
title	string	название камеры
previewUrl	string	ссылка на превью
archiveApiToken	object	токен для Archive API
archiveApiToken.signature	string	подпись токена
archiveApiToken.exp	int64	срок действия в Unix time
archiveApiUrl	string	базовый URL Archive API
archiveDays	integer	глубина архива в днях
liveRtspUrl	string	RTSP URL live-потока
liveHlsUrl	string	HLS URL live-потока
isOnline	boolean	камера онлайн
lastOnlineDate	datetime	дата последнего онлайна
cameraModel	string	модель камеры
platform	string	`Embedded` / `ThirdParty` / `Mobile`
serialNumber	string	серийный номер
firmwareVersion	string	версия прошивки
applicationVersion	string	версия приложения
isOwner	boolean	пользователь — владелец
isFullAccess	boolean	полный доступ
isArchiveGranted	boolean	доступ к архиву
isAudioGranted	boolean	доступ к аудио
tempAccessExpiryDate	datetime	срок временного доступа
location.id	string	идентификатор локации
location.title	string	название локации
location.room.id	string	идентификатор комнаты
location.room.title	string	название комнаты

Ошибки: 404 Not Found

3. Получение списка камер

GET /v1/cameras

Пример:

curl -X GET \
  "https://cloud.faceter.cam/integration-api/v1/cameras" \
  -H "X-Integration-Key: YOUR_INTEGRATION_KEY"

Response 200 — массив объектов, каждый имеет ту же структуру, что и ответ метода GET /v1/cameras/{cameraId}.

4. Получение событий камеры

GET /v1/cameras/{cameraId}/events

Path-параметры:

Параметр	Тип	Описание
cameraId	uuid	идентификатор камеры

Query-параметры:

Параметр	Тип	Описание
eventTypes	array[string]	список типов событий
startDate	datetime	дата начала периода
endDate	datetime	дата окончания периода
mergeInterval	integer	интервал объединения событий
limit	integer	максимальное количество записей
sortOrder	string	`None` / `Asc` / `Desc`

Типы событий: Motion, Human, Vehicle, LineCrossing, Intrusion, PeopleCounting, LicensePlate, Pet, PersonalMobilityVehicle, Face, Custom

Пример:

curl -G \
  "https://cloud.faceter.cam/integration-api/v1/cameras/3fa85f64-5717-4562-b3fc-2c963f66afa6/events" \
  -H "X-Integration-Key: YOUR_INTEGRATION_KEY" \
  --data-urlencode "startDate=2026-04-01T00:00:00Z" \
  --data-urlencode "endDate=2026-04-10T00:00:00Z" \
  --data-urlencode "eventTypes=Motion" \
  --data-urlencode "sortOrder=Desc" \
  --data-urlencode "limit=100"

Response 200:

{
  "items": [
    {
      "id": "7fa85f64-5717-4562-b3fc-2c963f66afa1",
      "cameraId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "Motion",
      "startTime": "2026-04-10T08:00:00Z",
      "endTime": "2026-04-10T08:01:00Z",
      "previewUrl": "https://example.com/event-preview.jpg",
      "mergedEventsCount": 2,
      "attributes": [{ "confidence": "0.98" }]
    }
  ],
  "hasMore": false
}

Поле	Тип	Описание
items	array	список событий
hasMore	boolean	есть ли ещё данные
id	uuid	идентификатор события
type	string	тип события
startTime	datetime	время начала
endTime	datetime	время окончания
previewUrl	string	ссылка на превью
mergedEventsCount	integer	количество объединённых событий
attributes	array	дополнительные атрибуты

Ошибки: 400 Bad Request, 404 Not Found

5. Создание события камеры

POST /v1/cameras/{cameraId}/events
Content-Type: multipart/form-data

Тело запроса передаётся как multipart/form-data. Текстовые значения отправляются отдельными полями формы, а snapshot и objectSnapshot — как бинарные файлы.

Поля формы:

Поле	Тип	Описание
eventId	uuid	идентификатор события
startDate	datetime	дата начала события в UTC в формате ISO 8601
endDate	datetime, nullable	дата окончания события в UTC в формате ISO 8601
eventType	string	тип события
instant	boolean	признак мгновенного события
grid.rows	integer	количество строк сетки
grid.cols	integer	количество колонок сетки
grid.cells	int64, повторяемое поле	значения ячеек сетки; каждое значение передаётся отдельным полем `grid.cells`
attributes[key]	string	дополнительный атрибут, где `key` — имя атрибута
snapshot	binary file, nullable	снимок события размером не более 5 МБ
objectSnapshot	binary file, nullable	снимок объекта размером не более 5 МБ

Если grid передаётся, значения grid.rows и grid.cols должны быть больше нуля, а grid.cells не должен быть пустым. Ключи и значения в attributes не должны быть пустыми.

Пример:

curl -X POST \
  "https://cloud.faceter.cam/integration-api/v1/cameras/<cameraId>/events" \
  -H "X-Integration-Key: YOUR_INTEGRATION_KEY" \
  --form 'eventId=7fa85f64-5717-4562-b3fc-2c963f66afa1' \
  --form 'startDate=2026-04-10T08:00:00Z' \
  --form 'endDate=2026-04-10T08:01:00Z' \
  --form 'eventType=Motion' \
  --form 'instant=false' \
  --form 'grid.rows=3' \
  --form 'grid.cols=3' \
  --form 'grid.cells=1' \
  --form 'grid.cells=0' \
  --form 'grid.cells=0' \
  --form 'grid.cells=1' \
  --form 'grid.cells=1' \
  --form 'grid.cells=0' \
  --form 'grid.cells=0' \
  --form 'grid.cells=0' \
  --form 'grid.cells=1' \
  --form 'attributes[confidence]=0.98' \
  --form 'snapshot=@./event.jpg;type=image/jpeg' \
  --form 'objectSnapshot=@./object.jpg;type=image/jpeg'

Заголовок Content-Type вручную устанавливать не нужно — curl сам добавит в него необходимый boundary.

Response 204 — событие принято, тело ответа отсутствует.

Ошибки:

Код	Причина
400 Bad Request	некорректные поля формы, пустой файл, файл более 5 МБ или некорректные параметры события
404 Not Found	камера не найдена или недоступна интеграции
429 Too Many Requests	превышено ограничение в 10 запросов создания событий в секунду; время до повторного запроса — в заголовке `Retry-After`

Событие увидит пользователь, только если его тип включён в фильтре событий в приложении. Событие создано и возвращается методом GET /v1/cameras/{cameraId}/events, но в ленте не показывается — почти всегда причина в этом, а не в ошибке отправки.
Тип Custom в текущих версиях приложений не отображается. Он доступен для собственной обработки через API; для событий, которые должен увидеть пользователь, выбирайте тип из остальных значений ClientsEventType.
id события в ленте не совпадает с отправленным eventId. Свой eventId служит ключом идемпотентности и наружу не возвращается — сохраняйте связку у себя.
Повторный запрос с тем же eventId не создаёт дубль. Для ещё не завершённого события можно передать endDate, чтобы завершить его; одновременно обновится grid. Повторно переданные snapshot и objectSnapshot заменят сохранённые снимки. Поля attributes, startDate, eventType и instant существующего события не изменяются.
snapshot и objectSnapshot передаются как бинарные части multipart-формы. Base64, строки с префиксом data:image/... и URL не поддерживаются. Оба снимка необязательны; если файл передаётся, он не должен быть пустым и не должен превышать 5 МБ. Без snapshot карточка события в ленте будет без изображения.
Вложенные значения не передаются JSON-объектами — используйте поля grid.rows, grid.cols, повторяемое поле grid.cells и поля вида attributes[имя].
Удалить созданное событие через Integration API нельзя — оно исчезнет вместе с архивом по истечении срока хранения (archiveDays камеры).

6. Получение интервалов записей

GET /v1/cameras/{cameraId}/recordings

Response 200:

[{ "startDate": "2026-04-10T08:00:00Z", "durationSeconds": 300 }]

Поле	Тип	Описание
startDate	datetime	начало записи
durationSeconds	integer	длительность в секундах

Ошибки: 404 Not Found

7. Получение фрагмента архива (синхронный)

GET /v1/cameras/{cameraId}/archive/clip

Query-параметры:

Параметр	Тип	Описание
startDate	datetime	начало фрагмента
duration	int64	длительность в секундах

Пример:

curl -G \
  "https://cloud.faceter.cam/integration-api/v1/cameras/3fa85f64-5717-4562-b3fc-2c963f66afa6/archive/clip" \
  -H "X-Integration-Key: YOUR_INTEGRATION_KEY" \
  --data-urlencode "startDate=2026-04-10T08:00:00Z" \
  --data-urlencode "duration=60" \
  -o clip.mp4

Response 200 — бинарный файл видео.

Ошибки: 400 Bad Request, 404 Not Found

8. Запуск экспорта архива (асинхронный)

POST /v1/cameras/{cameraId}/archive/exports

Request Body:

{
  "startDate": "2026-04-10T08:00:00Z",
  "durationSeconds": 120,
  "audioEnabled": true,
  "callbackUrl": "https://example.com/webhook"
}

Поле	Тип	Описание
startDate	datetime	начало экспортируемого интервала
durationSeconds	int32	длительность в секундах
audioEnabled	boolean	включать аудио
callbackUrl	string	URL для callback после завершения

Response 202:

{ "exportId": "9fa85f64-5717-4562-b3fc-2c963f66afa2", "status": "Queued" }

Ошибки: 400 Bad Request, 404 Not Found, 500 Server Error

9. Статус экспорта архива

GET /v1/cameras/{cameraId}/archive/exports/{exportId}

Response 200:

{
  "exportId": "9fa85f64-5717-4562-b3fc-2c963f66afa2",
  "status": "Completed",
  "videoUrl": "https://example.com/archive.mp4",
  "previewUrl": "https://example.com/archive-preview.jpg",
  "errorMessage": null,
  "createdAtUtc": "2026-04-10T08:00:00Z",
  "completedAtUtc": "2026-04-10T08:02:00Z"
}

Поле	Тип	Описание
exportId	uuid	идентификатор экспорта
status	string	статус экспорта
videoUrl	string	ссылка на готовое видео
previewUrl	string	ссылка на превью
errorMessage	string	текст ошибки (если есть)
createdAtUtc	datetime	дата создания
completedAtUtc	datetime	дата завершения

Ошибки: 403 Forbidden, 404 Not Found, 500 Server Error

10. Запуск экспорта аудио (асинхронный)

POST /v1/cameras/{cameraId}/exports/audio

Request Body:

{
  "startDate": "2026-04-10T08:00:00Z",
  "durationSeconds": 120,
  "callbackUrl": "https://example.com/webhook"
}

Response 202:

{ "exportId": "afa85f64-5717-4562-b3fc-2c963f66afa3", "status": "Queued" }

Ошибки: 400 Bad Request, 404 Not Found, 500 Server Error

11. Статус экспорта аудио

GET /v1/cameras/{cameraId}/exports/audio/{exportId}

Response 200:

{
  "exportId": "afa85f64-5717-4562-b3fc-2c963f66afa3",
  "status": "Completed",
  "audioUrl": "https://example.com/audio.mp3",
  "errorMessage": null,
  "createdAtUtc": "2026-04-10T08:00:00Z",
  "completedAtUtc": "2026-04-10T08:02:00Z"
}

Поле	Тип	Описание
exportId	uuid	идентификатор экспорта
status	string	статус экспорта
audioUrl	string	ссылка на аудиофайл
errorMessage	string	текст ошибки (если есть)
createdAtUtc	datetime	дата создания
completedAtUtc	datetime	дата завершения

Ошибки: 403 Forbidden, 404 Not Found, 500 Server Error

Справочник типов

SortOrder: None · Asc · Desc

CameraPlatform: Embedded · ThirdParty · Mobile

ClientsEventType: Motion · Human · Vehicle · LineCrossing · Intrusion · PeopleCounting · LicensePlate · Pet · PersonalMobilityVehicle · Face · Custom