Методы 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

Request Body:

{
  "eventId": "7fa85f64-5717-4562-b3fc-2c963f66afa1",
  "startDate": "2026-04-10T08:00:00Z",
  "endDate": "2026-04-10T08:01:00Z",
  "eventType": "Motion",
  "instant": false,
  "grid": { "rows": 3, "cols": 3, "cells": [1, 0, 0, 1, 1, 0, 0, 0, 1] },
  "attributes": { "confidence": "0.98" },
  "snapshot": "base64-or-url",
  "objectSnapshot": "base64-or-url"
}

Поле	Тип	Описание
eventId	uuid	идентификатор события
startDate	datetime	дата начала
endDate	datetime, nullable	дата окончания
eventType	string	тип события
instant	boolean	мгновенное событие
grid.rows	integer	количество строк
grid.cols	integer	количество колонок
grid.cells	array[int64]	значения ячеек
attributes	object	дополнительные атрибуты
snapshot	string	снимок события
objectSnapshot	string	снимок объекта

Response 204 — тело ответа отсутствует.

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

---

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