Devices Management API

API для управления зарегистрированными TVIP-приставками.

GET /api/devices

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

URL: /api/devices

Метод: GET

Теги: Devices-config

Query Parameters

Параметр	Тип	Обязательный	Описание
`ip`	string	Нет	Фильтр по IP-адресу (точное совпадение)
`model`	string	Нет	Фильтр по модели приставки (точное совпадение)
`last_activity_after`	string	Нет	Фильтр: активность после указанной даты (ISO 8601)
`last_activity_before`	string	Нет	Фильтр: активность до указанной даты (ISO 8601)
`sort_by_last_activity`	string	Нет	Сортировка по возрастанию/убыванию (по умолчанию: descending)
`limit`	integer	Нет	Максимальное количество записей
`offset`	integer	Нет	Смещение для pagination (по умолчанию: 0)

Response

Status Code: 200 OK

Content-Type: application/json

Body: Массив объектов устройств

Структура объекта Device:

[
   {
      "id": "e97df4c1-191e-4c6f-bd6c-837c175763f0",
      "mac_address": "10:27:be:28:e1:65",
      "model": "s530",
      "ip_address": "192.168.1.237",
      "last_activity": "2025-11-29T12:15:42.271447"
   }
]

Поля ответа:

id — уникальный идентификатор устройства (UUID)
mac_address — MAC-адрес устройства (уникальный идентификатор)
model — модель TVIP-приставки (может быть null)
ip_address — последний известный IP-адрес (может быть null)
last_activity — время последнего обращения (может быть null)

Примеры использования

Получить все устройства:

curl http://localhost:7373/api/devices

Фильтр по IP-адресу:

curl "http://localhost:7373/api/devices?ip=192.168.1.111"

Фильтр по модели:

curl "http://localhost:7373/api/devices?model=s530"

Фильтр по дате последней активности:

curl "http://localhost:7373/api/devices?last_activity_after=2025-01-01T00:00:00"

Pagination (20 записей, начиная с 40):

curl "http://localhost:7373/api/devices?limit=20&offset=40"

Комбинированные фильтры:

curl "http://localhost:7373/api/devices?ip=192.168.1.111&model=s530&limit=10"

Python пример:

import requests

params = {
    "model": "s530",
    "limit": 50,
    "offset": 0
}

response = requests.get("http://localhost:7373/api/devices", params=params)
devices = response.json()

for device in devices:
    print(f"{device['mac_address']}: {device['ip_address']}")

—

GET /api/devices/{mac_address}/config

Получить конфигурацию конкретного устройства по MAC-адресу.

URL: /api/devices/{mac_address}/config

Метод: GET

Теги: Devices-config

Path Parameters

Параметр	Тип	Описание
`mac_address`	string	MAC-адрес устройства (формат: `XX:XX:XX:XX:XX:XX`)

Response

Status Code: 200 OK

Content-Type: application/json

Body: Объект конфигурации в формате dot notation

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

{
    "provision.@reload": "86400",
    "provision.operator.@name": "MyOperator",
    "provision.logo.@url": "http://example.com/logo.png",
    "provision.time.@tz": "Europe/Moscow",
    "provision.time.@ntp": "pool.ntp.org",
    "provision.features.mediaplayer.@enabled": "true",
    "provision.features.dvr.@enabled": "false",
    "provision.tv_protocols.@default": "stalker",
    "provision.tv_protocols.protocol.@type": "stalker",
    "provision.tv_protocols.protocol.@server": "http://portal.example.com"
}

Примеры использования

curl http://localhost:7373/api/devices/00:11:22:33:44:55/config

Python пример:

import requests

mac = "00:11:22:33:44:55"
response = requests.get(f"http://localhost:7373/api/devices/{mac}/config")
config = response.json()

print(f"Reload interval: {config['provision.@reload']}")
print(f"Operator: {config['provision.operator.@name']}")

Ошибки

404 Not Found

Устройство с указанным MAC-адресом не найдено:

{
    "detail": "Device not found"
}

—

PUT /api/devices/{mac_address}/config/update

Частичное обновление конфигурации устройства (merge).

URL: /api/devices/{mac_address}/config/update

Метод: PUT

Теги: Devices-config

Path Parameters

Параметр	Тип	Описание
`mac_address`	string	MAC-адрес устройства

Request Body

Content-Type: application/json

Объект с обновлениями в формате dot notation. Будут обновлены только указанные поля, остальные сохранятся.

{
    "provision.time.@tz": "Europe/London",
    "provision.operator.@name": "NewOperator"
}

Response

Status Code: 200 OK

Content-Type: application/json

Body: Обновлённая конфигурация (полная)

Примеры использования

curl -X PUT "http://localhost:7373/api/devices/00:11:22:33:44:55/config/update" \
     -H "Content-Type: application/json" \
     -d '{
       "provision.time.@tz": "Europe/London",
       "provision.operator.@name": "NewOperator"
     }'

Python пример:

import requests

mac = "00:11:22:33:44:55"
updates = {
    "provision.time.@tz": "Europe/London",
    "provision.features.vod.@enabled": "true"
}

response = requests.put(
    f"http://localhost:7373/api/devices/{mac}/config/update",
    json=updates
)

updated_config = response.json()

Ошибки

404 Not Found — устройство не найдено

422 Unprocessable Entity — неверный формат данных

—

PUT /api/devices/{mac_address}/config/replace

Полная замена конфигурации устройства.

URL: /api/devices/{mac_address}/config/replace

Метод: PUT

Теги: Devices-config

Предупреждение

Этот endpoint полностью заменяет конфигурацию устройства. Все предыдущие настройки будут удалены.

Path Parameters

Параметр	Тип	Описание
`mac_address`	string	MAC-адрес устройства

Request Body

Content-Type: application/json

Полная конфигурация в формате dot notation:

{
    "provision.@reload": "3600",
    "provision.operator.@name": "MyOperator",
    "provision.time.@tz": "Europe/Moscow",
    "provision.time.@ntp": "pool.ntp.org",
    "provision.tv_protocols.@default": "stalker",
    "provision.tv_protocols.protocol.@type": "stalker",
    "provision.tv_protocols.protocol.@server": "http://portal.example.com"
}

Response

Status Code: 200 OK

Content-Type: application/json

Body: Новая конфигурация

Примеры использования

curl -X PUT "http://localhost:7373/api/devices/00:11:22:33:44:55/config/replace" \
     -H "Content-Type: application/json" \
     -d @new_config.json

Python пример:

import requests

mac = "00:11:22:33:44:55"
new_config = {
    "provision.@reload": "3600",
    "provision.operator.@name": "CustomOperator",
    "provision.time.@tz": "America/New_York"
}

response = requests.put(
    f"http://localhost:7373/api/devices/{mac}/config/replace",
    json=new_config
)

—

POST /api/devices/{mac_address}/config/reset

Сбросить конфигурацию устройства к дефолтной.

URL: /api/devices/{mac_address}/config/reset

Метод: POST

Теги: Devices-config

Path Parameters

Параметр	Тип	Описание
`mac_address`	string	MAC-адрес устройства

Request Body

Не требуется.

Response

Status Code: 200 OK

Content-Type: application/json

Body: Сообщение об успешном сбросе

{
    "message": "Device configuration reset to default"
}

Примеры использования

curl -X POST "http://localhost:7373/api/devices/00:11:22:33:44:55/config/reset"

Python пример:

import requests

mac = "00:11:22:33:44:55"
response = requests.post(
    f"http://localhost:7373/api/devices/{mac}/config/reset"
)

print(response.json()["message"])

Логика работы

После сброса:

Кастомная конфигурация устройства удаляется (custom_config_id → NULL)
При следующем запросе /prov/tvip_provision.xml устройство получит дефолтную конфигурацию
Метаданные устройства (MAC, IP, модель, время регистрации) сохраняются

—

Автоматическая документация

Полная автодокументация endpoints:

async presentation.api.endpoints.devices_management.get_devices_list(ip=None, model=None, last_activity_after=None, last_activity_before=None, sort_by_last_activity=SortOrder.DESC, limit=None, offset=None, use_case=Depends(get_devices_list_use_case))[исходный код]

Параметры:

ip (str | None) –
model (str | None) –
last_activity_after (str | None) –
last_activity_before (str | None) –
sort_by_last_activity (SortOrder | None) –
limit (int | None) –
offset (int | None) –
use_case (GetDevicesListUseCase) –

async presentation.api.endpoints.devices_management.get_device_config(mac_address, use_case=Depends(get_device_config_use_case))[исходный код]

Параметры:

mac_address (str) –
use_case (GetDeviceConfigUseCase) –

async presentation.api.endpoints.devices_management.update_device_config(mac_address, updates, use_case=Depends(update_device_config_use_case))[исходный код]

Параметры:

mac_address (str) –
updates (dict[str, Any]) –
use_case (UpdateDeviceConfigUseCase) –

async presentation.api.endpoints.devices_management.replace_device_config(mac_address, new_config, use_case=Depends(replace_device_config_use_case))[исходный код]

Параметры:

mac_address (str) –
new_config (dict[str, Any]) –
use_case (ReplaceDeviceConfigUseCase) –

async presentation.api.endpoints.devices_management.reset_device_config(mac_address, use_case=Depends(reset_device_config_use_case))[исходный код]

Параметры:

mac_address (str) –
use_case (ResetDeviceConfigUseCase) –