API: версия v1 от 09.04.2025

1. Введение 

В данном документе описывается API, позволяющий организовать программное взаимодействие между «Приток-А» и сторонней системой (далее - система «Х»).

Взаимодействие осуществляется по протоколу HTTP, формат данных - JSON.

API позволяет системе «Х»:

запрашивать список охраняемых объектов и их устройств,

запрашивать информацию из карточек охраняемых объектов и историю событий,

получать уведомления при изменении информации и охранного состояния объектов,

передавать на выполнение команды управления устройствами.

1.1. Настройки взаимодействия 

Для взаимодействия по API в системе «Приток-А» должно быть настроено и запущено приложение «Приток-Охрана-WEB».

Для организации взаимодействия «Приток-Охрана-WEB» открывает точку доступа. Точка доступа определяет наименование подключения, адрес для выполнения запросов по API, версию протокола, обратный URL для уведомлений, токены авторизации. Параметры точки доступа настраиваются через панель администратора.

В данном документе, для примера, адрес точки доступа для выполнения запросов имеет наименование - x.

Предполагается, что система «Х» после получения списка объектов кэширует эти данные. Обновление информации по объектам из системы «Приток-А» в систему «Х» происходит через обратный URL. Чтобы получать актуальные данные, если это требуется, в системе «Х» необходимо настроить сервер для обработки уведомлений согласно протоколу (см. раздел 3. Уведомления).

Запрос дополнительных данных по объектам (см. разделы 2.6-2.8) система «Х» может выполнять по необходимости.

1.2. Порядок взаимодействия 

Порядок взаимодействия между системами представлен в виде диаграммы. Диаграмму можно масштабировать с помощью колеса мыши.

           sequenceDiagram

    actor User

    participant Система-Х

    participant Приток-Охрана-WEB

    participant Ядро



    Note over Система-Х,Приток-Охрана-WEB: СТАРТ



    Система-Х->>+Приток-Охрана-WEB: Запросит состояние сервиса: HTTP GET /api/x/ 

    Приток-Охрана-WEB-->>-Система-Х: Информация о сервисе

    Система-Х->>+Приток-Охрана-WEB: Запросить список пультов: HTTP GET /api/x/pults

    Приток-Охрана-WEB-->>-Система-Х: Список [Pult]

    

    Loop для каждого пульта

      Система-Х->>+Приток-Охрана-WEB: Запросить список объектов пульта: HTTP GET /api/x/pult/<pult_id>/objs

      Приток-Охрана-WEB-->>-Система-Х: Список [Obj]

    end



    Note over Система-Х,Приток-Охрана-WEB: ФОНОВАЯ РАБОТА

    

    Ядро->>Приток-Охрана-WEB: Обновилось интегральное состояние объекта

    Приток-Охрана-WEB->>Система-Х: Обновилось интегральное состояние объекта: POST /changes/obj



    Ядро->>Приток-Охрана-WEB: Добавлен новый объект

    Приток-Охрана-WEB->>Система-Х: Добавлен новый объект: POST /changes/obj



    Ядро->>Приток-Охрана-WEB: Изменена информация по объекту

    Приток-Охрана-WEB->>Система-Х: Изменена информация по объекту: POST /changes/obj



    Ядро->>Приток-Охрана-WEB: Удалён объект

    Приток-Охрана-WEB->>Система-Х: Удалён объект: POST /changes/obj



    Note over Система-Х,Приток-Охрана-WEB: ДЕЙСТВИЯ ПОЛЬЗОВАТЕЛЯ

   

    User->>+Система-Х: Открыть список объектов

    Система-Х->>Система-Х: Выбор объектов из кеша

    Система-Х->>-User: Список объектов



    User->>+Система-Х: Посмотреть информацию по устройству

     Система-Х->>+Приток-Охрана-WEB: GET /api/x/pult/<pult_id>/dev/<dev_id> 

     Приток-Охрана-WEB-->>-Система-Х: Информация по устройству [Device] 

    Система-Х->>-User: Информация по объекту



    User->>+Система-Х: Посмотреть информацию по карточке

     Система-Х->>+Приток-Охрана-WEB: GET /api/x/pult/<pult_id>/dev/<dev_id>/cust 

     Приток-Охрана-WEB-->>-Система-Х: Информация по карточке [CustInfo] 

    Система-Х->>-User: Информация по объекту





    User->>+Система-Х: Посмотреть историю по устройству

     Система-Х->>+Приток-Охрана-WEB: GET /api/x/pult/<pult_id>/dev/<dev_id>/history

     Приток-Охрана-WEB-->>-Система-Х: История по устройству [History] 

    Система-Х->>-User: История по объекту



    

    User->>+Система-Х: Выполнить команду

     Система-Х->>+Приток-Охрана-WEB: POST /api/x/pult/<pult_id>/action

      Приток-Охрана-WEB-->>+Ядро: Отправить команду по списку устройств

     Приток-Охрана-WEB-->>-Система-Х: Результат выполнения: JSON-массив ActionResult    

    Система-Х->>-User: Команда отправлена

    Система-Х->>Система-Х: Подождать и запросить состояние устройства





    Ядро->>-Приток-Охрана-WEB: Обновилось интегральное состояние объекта

    Приток-Охрана-WEB->>Система-Х: Обновилось интегральное состояние объекта: POST /changes/obj

    Система-Х->>User: Уведомление об изменении состояния

2. Запросы 

Каждый запрос должен содержать заголовок X-Prtgrdweb-API-Auth: <токен>, в котором необходимо передавать токен для аутентификации.

2.1. Запросить информацию о сервисе 

Запрос: GET /api/x

Описание: Проверить доступность сервиса и получить версию протокола.

Параметры: Нет.

Ответ: JSON-объект:

{
    "version": "v1",
    "entry": {
        "callback": {
            "url": "http://10.10.10.10"
        }
    }
}

version - версия протокола,
entry - служебная информация,
url - URL для уведомлений.

2.2. Запросить список пультов 

Запрос: GET /api/x/pults

Описание: Получить список пультов.

Параметры: Нет.

Ответ: JSON-массив объектов Pult (см. 4.1. Pult).

Пример:

[{"pult_id": 2106336625, "name": "local"}]

2.3. Запросить список объектов пульта 

Запрос: GET /api/x/pult/<pult_id>/objs

Описание: Получить список объектов пульта.

Параметры: Нет.

Ответ: JSON-массив объектов Obj (см. 4.2. Obj).

Пример:

[
    {
        "dev_id": 3979,
        "name": "Кв. Лобачева",
        "channels": [{"current": true, "active": true, "type": "ethernet"}],
        "istate": {"code": 2, "name": "Снят с охраны", "comment": "", "type": "disarmed"},
        "cust": {
            "name": "Кв. Лобачева",
            "pultnum": "100000",
            "location": {"address": "", "lon": 104.245231, "lat": 52.280406},
            "type": "Автомобильная стоянка",
            "category": "Важный"
        }
    }
]

2.4. Запросить информацию по объекту 

Запрос: GET /api/x/pult/<pult_id>/obj/<dev_id>

Описание: Получить описание объекта.

Параметры: Нет.

Ответ: JSON-объект Obj (см. 4.2. Obj).

Пример аналогичен разделу 2.3.

2.5. Запросить информацию по устройству 

Запрос: GET /api/x/pult/<pult_id>/dev/<dev_id>

Описание: Получить описание устройства.

Параметры: Нет.

Ответ: JSON-объект Device (см. 4.11. Device).

Пример:

{
    "dev_id": 3979,
    "num": 12,
    "name": "Кв. Лобачева",
    "state": {"code": 2, "name": "Взят под охрану", "comment": "", "type": "ok"},
    "actions": [],
    "devices": [
        {
            "dev_id": 3980,
            "num": 1,
            "name": "Дверь001",
            "type": "guard",
            "state": {"code": 3, "name": "Снят с охраны", "comment": "", "type": "ok"},
            "actions": [
                {"code": 200, "name": "Взять под охрану", "comment": "", "type": "arm"},
                {"code": 202, "name": "Снять с охраны", "comment": "", "type": "disarm"},
                {"code": 204, "name": "Запросить состояние", "comment": "", "type": "getstate"}
            ],
            "devices": []
        },
        {
            "dev_id":3981,
            "num":2,
            "name":"ТС002",
            "type":"guard",
            "state":{"code":2,"name":"Взят под охрану","comment":"","type":"ok"},
            "actions":[
                {"code":200,"name":"Взять под охрану","comment":"","type":"arm"},
                {"code":202,"name":"Снять с охраны","comment":"","type":"disarm"},
                {"code":204,"name":"Запросить состояние","comment":"","type":"getstate"}
              ],
              "devices":[]
        }
    ]
}

2.6. Запросить историю 

Запрос: GET /api/x/pult/<pult_id>/dev/<dev_id>/history

Описание: Получить историю событий по устройству.

Параметры:

startid - начальный идентификатор события

Eсли параметр передан - идентификаторы возвращаемых событий будут строго меньше его значения

startdt - начальная дата/время события в формате unix-time

Eсли параметр передан - дата/время возвращаемых событий будут меньше или равны его значения

limit - ограничение на количество возвращаемых событий

Если параметр не передан или его значение превышает внутренние ограничения сервера - количество возвращаемых событий будет меньше или равно значению внутреннего ограничения сервера, при этом в ответе вернется поле enforced-limit со значением текущего ограничения

Пример:

/history

/history?limit=100

/history?startid=82413815&limit=10

/history?startdt=1673586557&limit=50

Ответ: JSON-объект History (см. 4.15. History).

Пример:

{
    "timestamp": 1742889938083,
    "events": [
        {"ev_id": 5449672, "dt": 1742876967000, "type": "red", "name": "Взят", "comment": "Команда из моб.приложения/Веб-интерфейса", "source": "Кв. Лобачева"},
        {"ev_id": 5449670, "dt": 1742876967000, "type": "none", "name": "Взять объект под охрану с подачей команды", "comment": "kubernetes.docker.internal", "source": "Кв. Лобачева"},
        {"ev_id": 5449669, "dt": 1742876967000, "type": "none", "name": "Запрос на взятие", "comment": "API: E-THG", "source": "Кв. Лобачева"}
    ]
}

2.7. Запросить описание технических параметров устройства 

Запрос: GET /api/x/pult/<pult_id>/dev/<dev_id>/hwinfo

Описание: Получить техническое описание устройства.

Параметры: Нет.

Ответ: JSON-объект Hwinfo (см. 4.13. Hwinfo).

Пример:

{"ident": "100000", "model": "Приток-А-КОП-02.4", "version": "KOP-02.4 V2.22(16)"}

2.8. Запросить информацию из карточки 

Запрос: GET /api/x/pult/<pult_id>/dev/<dev_id>/cust

Описание: Получить описание карточки устройства.

Параметры: Нет.

Ответ: JSON-объект CustInfo (см. 4.6. CustInfo).

Пример:

{
    "pultnum": "100000",
    "name": "Кв. Лобачева",
    "contract": {"dtPauseStart": 0, "dtPauseStop": 0, "num": "qwerty", "dtActive": 1742486400000, "dtClose": 0, "status": "disactive"},
    "phones": [],
    "xos": []
}

2.9. Выполнить команду 

Запрос: POST /api/x/pult/<pult_id>/action

Описание: Выполнить команду по устройству.

Тело запроса: JSON-объект ActionRequest (см. 4.17. ActionRequest).

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

{"code": 202, "dev_ids": [3979]}

Ответ: JSON-массив ActionResult (см. 4.18. ActionResult).

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

[{"text": "Устройство не найдено", "type": "deny", "dev_id": 39279}]

3. Уведомления 

Для получения уведомлений необходимо настроить сервер на принимающей стороне для обработки запросов (см. раздел 3.1).

При регистрации изменений в значении полей по объекту (см. 4.2. Obj), выполняется запрос на URL, указанный при настройке точки доступа.

Каждый запрос содержит заголовок: X-Prtgrdweb-API_v1-Noty: <токен>

3.1. Уведомление об изменении бъекта 

Запрос: POST /changes/obj

Описание: Уведомление об изменении информации по объекту или состояния объекта.

Тело запроса: JSON-массив Changes (см. 4.19. ChangeObj).

Пример:

[{"pult_id": 2106336625, "obj": {"dev_id": 3979, "istate": {"code": 2, "name": "Снят с охраны", "comment": "", "type": "disarmed"}}, "type": "upd"}]

Ответ: Нет.

4. Сущности 

4.1. Pult 

Описание пульта:

pult_id: number – идентификатор
name: string – наименование

4.2. Obj 

Описание объекта:

dev_id: number – идентификатор устройства
name: string – наименование объекта
channel: array<Channel> – каналы связи (см. 4.4. Channel)
istate: Istate – интегральное состояние
cust: CustBase – карточка (базовая)

4.3. Istate 

Описание интегрального состояния:

code: number – код
type: enum<IstateType> – тип (см. 5.2. IstateType)
name: string – текстовое представление
comment: string – комментарий

4.4. Channel 

Описание канала связи:

type: enum<ChannelType> - тип (см. 5.1. ChannelType)
active: boolean - признак, что канал активен
current: boolean - признак, что канал используется в данный момент

4.5. CustBase 

Описание карточки объекта (набор полей: base):

pultnum: string – пультовый номер
name: string – наименование
type: string – тип объекта
category: string – категория объекта
location: Location – местоположение

4.6. CustInfo 

Описание карточки объекта (набор полей: info):

pultnum: string – пультовый номер
name: string – наименование карточки объекта
contract: Contract – договор
phones: array<Phone> – контакты объекта (см. 4.9. Phone)
xos: array<Xo> – список хоз. органов (см. 4.10. Xo)

4.7. Contract 

Описание договора:

num: string – номер договора
status: enum<ContractStatus> – статус (см. 5.3. ContractStatus)
dtActive: number – дата заключения
dtClose: number – дата завершения
dtPauseStart: number – дата начала приостановки
dtPauseStop: number – дата завершения приостановки

4.8. Location 

Описание местоположения:

address: string – адрес
lat: double – широта (DD)
lon: double – долгота (DD)

4.9. Phone 

Описание средства связи:

type: string – тип
text: string – текстовое представление
comment: string – комментарий

4.10. Xo 

Описание хоз. органа:

xo_id: number – идентификатор
num: number – номер
fio: string – ФИО
type: string – тип
role: enum<XoRole> – роль (см. 5.4. XoRole)
phones: array<Phone> – контакты (см. 4.9. Phone)

4.11. Device 

Описание устройства:

dev_id: number – идентификатор
num: number – локальный номер
name: string – наименование устройства (из дерева конфигурации системы)
state: State – состояние
value: var – значение
type: enum<DeviceType> – тип (см. 5.5. DeviceType)
devices: array<Device> – список дочерних устройств (см. 4.11. Device)
actions: array<Action> – список разрешенных действий (см. 4.14. Action)

4.12. State 

Описание состояния:

code: number – код
type: enum<StateType> – тип (см. 5.6. StateType)
name: string – наименование
comment: string – комментарий

4.13. Hwinfo 

Тех. описание устройства:

ident: string – идентификатор в системе
model: string – тип/модель
version: string – версия ПО

4.14. Action 

Описание действия:

code: number – код команды
type: <ActionType> – тип (см. 5.7. ActionType)
name: string – название
comment: string – комментарий
payload: var – нагрузка

4.15. History 

История событий:

timestamp: number – метка времени
events: array<Event> – массив событий (см. 4.16. Event)
enforced-limit: number – принудительно установленное ограничение на количество возвращаемых событий