10. Data Sources

Раздел описывает единый реестр источников данных системы.

10.1 Назначение раздела

Раздел Data Sources используется как общий список подключённых источников данных.

Он нужен для:

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

Раздел Data Sources не используется для хранения детальной конфигурации источников.
Конкретные типы источников описываются и управляются в отдельных разделах API.
Например, камеры описываются в разделе Cameras.

10.2 Совместимость с текущей архитектурой

Раздел Data Sources является единым реестром источников, а не местом, где описывается полная модель каждого типа источника.

Это означает:

камера остаётся полноценной сущностью в разделе Cameras;
будущие типы источников также должны иметь собственные разделы API;
раздел Data Sources только агрегирует их в единый список.

Пример:

камера создаётся через POST /cameras/new;
после создания камера должна появиться в GET /sources;
удаление или деактивация камеры должно отражаться в реестре источников.

10.3 Общие правила

Авторизация

Все эндпоинты раздела требуют авторизации.

Authorization: Bearer <access_token>

Модель доступа

Для эндпоинтов раздела используются следующие разрешения:

sources.view — просмотр источников данных;
admin.partners.view — просмотр источников данных в административном контуре.

Правила видимости данных

администратор платформы может видеть все источники;
сотрудник партнёра может видеть только доступные ему источники своего партнёра;
применяются обычные правила read_scope для данных партнёра.

Общие ошибки

Код	Тип	Описание
400	`Bad Request`	Невалидные параметры запроса.
401	`Unauthorized`	Токен отсутствует, невалиден, истёк или сессия завершена.
403	`Forbidden`	У пользователя недостаточно прав для выполнения действия.
404	`Not Found`	Источник данных не найден.
422	`Unprocessable Entity`	Ошибка валидации.
500	`Internal Server Error`	Необработанная ошибка сервера.
503	`Service Unavailable`	Сервис временно недоступен.

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

{
  "error_description": "Source not found"
}

10.4 Формат данных

Время

Все временные значения передаются в формате UTC ISO 8601:

2026-04-06T10:00:00Z

Тип источника

Поле source_type описывает класс источника данных.

Рекомендуемые значения:

camera_stream — видеопоток камеры;
partner_api — API партнёра;
parking_sensor — датчики парковки;
payment_feed — данные об оплатах;
navigator_feed — агрегированные навигационные данные;
carsharing_feed — данные каршеринга;
manual_import — ручной импорт;
other — иной источник.

Тип профильной сущности

Поле entity_type указывает, в каком профильном разделе описан конкретный источник.

Рекомендуемые значения:

camera
partner_api_source
parking_sensor_source
payment_source
navigator_source
carsharing_source
manual_import_source

В MVP фактически используется entity_type = camera.

Статус источника

Поле status описывает состояние источника.

Поддерживаемые значения:

active — источник активен;
paused — источник временно выключен;
error — источник в ошибочном состоянии;
deleted — источник деактивирован;
unknown — состояние не определено.

10.5 Модель `DataSource`

Объект источника данных в едином реестре.

source_id (integer) — уникальный идентификатор записи в реестре источников.
partner_id (integer | null) — идентификатор партнёра-владельца.
created_by_user_id (integer | null) — пользователь, создавший профильную сущность источника.
source_type (string) — тип источника данных.
entity_type (string) — тип профильной сущности источника.
entity_id (integer) — идентификатор профильной сущности.
title (string) — отображаемое название источника.
status (string) — текущее состояние источника.
last_data_at (string | null, ISO 8601) — время последнего успешно полученного или обработанного сигнала от источника.
last_error (string | null) — последнее сообщение об ошибке, если оно есть.
is_active (boolean) — активен ли источник.
created_at (string, ISO 8601) — дата создания записи в реестре.
updated_at (string, ISO 8601) — дата последнего обновления записи.

Пример

{
  "source_id": 3001,
  "partner_id": 10,
  "created_by_user_id": 123,
  "source_type": "camera_stream",
  "entity_type": "camera",
  "entity_id": 1,
  "title": "Кронверкский просп., парковка напротив ИТМО",
  "status": "active",
  "last_data_at": "2026-04-06T10:40:00Z",
  "last_error": null,
  "is_active": true,
  "created_at": "2026-04-06T09:00:00Z",
  "updated_at": "2026-04-06T10:40:00Z"
}

10.6 `GET /sources`

Возвращает список источников данных, доступных текущему пользователю.

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

Требуемые разрешения

sources.view

Headers

Authorization: Bearer <access_token>

Query-параметры (необязательные)

partner_id (integer) — фильтр по партнёру-владельцу.
source_type (string) — фильтр по типу источника.
entity_type (string) — фильтр по профильному типу сущности.
status (string) — фильтр по статусу.
is_active (boolean) — фильтр по активности.
q (string) — поиск по title.
top (integer, 1..100) — максимальное число элементов.
offset (integer, >=0) — смещение для пагинации.

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

GET /api/v1/sources?source_type=camera_stream&status=active&top=20&offset=0 HTTP/1.1
Host: api.parktrack.live
Authorization: Bearer <token>

Response (200)

items (DataSource[]) — список источников.
total (integer) — общее число источников по фильтру.
top (integer) — значение top.
offset (integer) — значение offset.

Пример ответа (200)

{
  "items": [
    {
      "source_id": 3001,
      "partner_id": 10,
      "created_by_user_id": 123,
      "source_type": "camera_stream",
      "entity_type": "camera",
      "entity_id": 1,
      "title": "Кронверкский просп., парковка напротив ИТМО",
      "status": "active",
      "last_data_at": "2026-04-06T10:40:00Z",
      "last_error": null,
      "is_active": true,
      "created_at": "2026-04-06T09:00:00Z",
      "updated_at": "2026-04-06T10:40:00Z"
    }
  ],
  "total": 1,
  "top": 20,
  "offset": 0
}

Ошибки

Код	Тип	Описание
401	`Unauthorized`	Токен отсутствует, невалиден или истёк.
403	`Forbidden`	Недостаточно прав для просмотра источников.

10.7 `GET /sources/<source_id>`

Возвращает запись источника данных из единого реестра по её идентификатору.

Этот эндпоинт не заменяет профильный раздел конкретного типа источника.
Он используется для получения общей информации и перехода к профильной сущности через поля:

entity_type
entity_id

Path-параметры

source_id (integer, required)

Требуемые разрешения

sources.view

Headers

Authorization: Bearer <access_token>

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

GET /api/v1/sources/3001 HTTP/1.1
Host: api.parktrack.live
Authorization: Bearer <token>

Response (200) — объект DataSource

Пример ответа (200)

{
  "source_id": 3001,
  "partner_id": 10,
  "created_by_user_id": 123,
  "source_type": "camera_stream",
  "entity_type": "camera",
  "entity_id": 1,
  "title": "Кронверкский просп., парковка напротив ИТМО",
  "status": "active",
  "last_data_at": "2026-04-06T10:40:00Z",
  "last_error": null,
  "is_active": true,
  "created_at": "2026-04-06T09:00:00Z",
  "updated_at": "2026-04-06T10:40:00Z"
}

Ошибки

Код	Тип	Описание
401	`Unauthorized`	Токен отсутствует, невалиден или истёк.
403	`Forbidden`	Недостаточно прав для просмотра источника.
404	`Not Found`	Источник не найден.

10.8 Требования к профильным разделам источников

Каждый конкретный тип источника данных должен иметь собственный раздел API.

Например:

Cameras
в будущем:
- Partner API Sources
- Parking Sensors
- Payment Sources
- Navigator Sources

Профильный раздел должен отвечать за:

создание сущности;
изменение сущности;
удаление сущности;
валидацию специфичных полей;
описание полной модели конкретного источника.

Раздел Data Sources должен отвечать только за:

единый список;
единый просмотр записи реестра;
унифицированную фильтрацию по типу, партнёру и статусу.

10.9 Требования к синхронизации реестра

При создании, изменении, деактивации или удалении профильной сущности источника реестр Data Sources должен обновляться автоматически.

Примеры:

при создании камеры должна автоматически появляться запись в Data Sources;
при деактивации камеры должен обновляться status и is_active в реестре;
при удалении камеры запись источника должна переводиться в состояние deleted или удаляться согласно выбранной серверной политике.

10.10 Требования к другим разделам API

Раздел Data Sources рекомендуется использовать как общий список всех источников в:

административных интерфейсах;
партнёрских кабинетах;
системных списках источников;
аналитике по источникам.

Для полной информации о конкретном источнике необходимо использовать профильный раздел, соответствующий:

entity_type
entity_id

10.1 Назначение раздела​

10.2 Совместимость с текущей архитектурой​

10.3 Общие правила​

Авторизация​

Модель доступа​

Правила видимости данных​

Общие ошибки​

10.4 Формат данных​

Время​

Тип источника​

Тип профильной сущности​

Статус источника​

10.5 Модель DataSource​

10.6 GET /sources​

10.7 GET /sources/<source_id>​

10.8 Требования к профильным разделам источников​

10.9 Требования к синхронизации реестра​

10.10 Требования к другим разделам API​