1. API
1.1. Основные положения
При работе с API существует ряд ограничений: Количество запросов ограничено 100 запросами в секунду. При превышении данного показателя на новые запросы будет выдан ответ сервера: 503 (Service Temporarily Unavailable)
1.2. Доступ
Приложение (программа, скрипт и др.) выполняет запрос к API от имени пользователя мониторинговой компании и управляет данными, принадлежащими данной компании. Пользователи из мониторинговой компании могут иметь роль Администратор МК или Сотрудник МК. Работа по API осуществаляется с ролью Сотрудник МК. Для авторизации используется механизм JWT. Подробности осуществления авторизации в системе смотрите на соответствующей странице.
1.3. Ограничение доступа по IP-адресу
Доступ к API ограничен по IP-адресу, что повышает информационную безопасность. Список разрешенных IP-адресов можно согласовать с Администратором.
1.4. Формат взаимодействия
Доступ к API предоставляется через криптографический протокол SSL. Установка SSL-соединения обязательна для вызова методов API.
Взаимодействие с API ПаК ВсМК в формате REST, используя представление данных в формате JSON. Запросы в формате JSON передаются методом HTTP POST|GET|PUT|DELETE на следующий адрес: https://pakvcmk.ru/api/
2. Авторизация
Авторизация пользователя в API производится через [JWT](https://en.wikipedia.org/wiki/JSON_Web_Token)
При работе с API нужно получить токен с помощью ниже приведенного метода API.
Последующие запросы должны содержать в заголовке значение токена в виде поля: 'Authorization:Bearer токен'
2.1. API метод авторизации
- URL
-
/login
- Метод
-
POST
Данные
Формат:
{
"username" : "[string]",
"password" : "[alphanumeric]"
}
_Возвращает токен для дальнейшей работы с системой_
- Код
-
200
- Тело ответа
-
{ token : [string] }
- Ответ при ошибке
-
Возникает в случае неправильного логина или пароля
Code: 401 UNAUTHORIZED
Content: { error : "Log in" }
- Пример использования
<?php
$token = "";
$base_url = "https://pakvcmk.ru/api/";
$user = "john"; $password = "passw0rd";
function curl_get($url, $post = "", $token = '', $method = "")
{
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
if ($method != "") {
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
}
if ($post != "") {
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($post));
}
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
$headers = array('Accept: application/json', 'Content-Type: application/json', 'Authorization:Bearer ' . $token);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$head = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode != 200 ) {
echo "Error in response: code: $httpCode, text: '$head' \n";
return false;
}
return $head;
}
$token_str = curl_get($base_url . "login", array("username" => $user, "password" => $password));
if ($token_str!=false){
$token = json_decode($token_str);
echo "Token: {$token->token}";
}
Вернет результат, в случае правильного логина и пароля:
Token: eyJhbG…nYhJQV2C4
3. Работа с объектами
Метод | Параметры | Результат | Описание |
---|---|---|---|
нет |
JSON Массив объектов |
Получение списка всех объектов компании |
|
нет |
JSON объект |
Получение информации по объекту |
|
нет |
Удаление объекта |
||
JSON объект |
code 201 - Created { "status": "success", "object_id": "%id%" } |
||
Аналогично POST запросу |
В случае успеха: code 200 Json объект с новыми данными. Код ошибки 4** или 5** { "error" :"Описание ошибки" } |
||
{ "object_id": "ID объекта", "comment" : "Тест комментария" } |
В случае успеха: code 200 |
3.1. Создание нового объекта
Наименование |
Добавление нового объекта в систему |
---|---|
URL |
/objects |
Метод |
POST |
Параметры URL |
нет |
Данные |
JSON Формат объекта |
Ответ при удачном запросе |
Код ответа: 201 Содержимое: {status: "success", object_id: %id%} |
Ответ при ошибке |
Код ответа: 401 UNAUTHORIZED Содержимое: "" Возникает в случае, если пользователь не авторизован, либо у него нет прав на создание объекта или Код ответа: 500 Internal Server Error Содержимое: { error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях |
Пример использования |
|
3.2. Изменение объекта
Наименование |
Изменение данных объекта |
---|---|
URL |
/objects/:id |
Метод |
PUT |
Параметры URL |
Обязательно: id:[UUID] Пример: 5213a389-ccda-11e6-9751-0cc47aac4166 |
Данные |
JSON Формат объекта |
Ответ при удачном запросе |
Код ответа: 200 Содержимое: {status: "success", object_id: %id%} |
Ответ при ошибке |
Код ответа: 401 UNAUTHORIZED Содержимое: "" Возникает в случае, если пользователь не авторизован, либо у него нет прав на создание объекта или Код ответа: 500 Internal Server Error Содержимое: { error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях |
Пример использования |
|
3.3. Получение объекта
Наименование |
Получение списка всех объектов |
---|---|
URL |
/objects/:id |
Метод |
GET |
Параметры URL |
Обязательно: id:[UUID] Пример: 5213a389-ccda-11e6-9751-0cc47aac4166 |
Данные |
нет |
Ответ при удачном запросе |
Код ответа: 200 Содержимое: JSON Формат объекта |
Ответ при ошибке |
Код ответа: 401 UNAUTHORIZED Содержимое: "" Возникает в случае, если пользователь не авторизован, либо у него нет прав на получение данных объекта или Код ответа: 500 Internal Server Error Содержимое: { error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях |
Пример использования |
|
3.4. Получение списка объектов
Получение списка объектов с основными данными. Расширенные данные можно получить по запросу Получение объекта
Наименование |
Получение списка всех объектов |
---|---|
URL |
/objects |
Метод |
GET |
Параметры URL |
нет |
Данные |
нет |
Ответ при удачном запросе |
Код ответа: 200 Содержимое: JSON Массив объектов |
Ответ при ошибке |
Код ответа: 401 UNAUTHORIZED Содержимое: "" Возникает в случае, если пользователь не авторизован, либо у него нет прав на создание объекта или Код ответа: 500 Internal Server Error Содержимое: { error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях |
Пример использования |
|
3.5. Передача объекта на согласование
Наименование |
Передача объекта на согласование с подразделением УВО |
---|---|
URL |
/approve |
Метод |
POST |
Параметры URL |
нет |
Данные |
JSON объект
|
Ответ при удачном запросе |
Код ответа: 200 |
Ответ при ошибке |
Code: 400 Bad Request Возникает в случае, если согласование объекта невозможно по каким-либо причинам Code: 401 UNAUTHORIZED Возникает в случае, если пользователь не авторизован, либо у него нет прав на изменение объекта Code: 500 Internal Server Error Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях |
Пример использования |
|
3.6. Отмена согласования объекта
Наименование |
Снятие согласования объекта с подразделением УВО |
---|---|
URL |
/unapprove |
Метод |
POST |
Параметры URL |
нет |
Данные |
JSON объект
|
Ответ при удачном запросе |
Код ответа: 200 Содержимое: "" |
Ответ при ошибке |
Code: 400 Bad Request Возникает в случае, если согласование объекта невозможно по каким-либо причинам Code: 401 UNAUTHORIZED Возникает в случае, если пользователь не авторизован, либо у него нет прав на изменение объекта Code: 403 Forbidden Code: 500 Internal Server Error Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях |
Пример использования |
|
3.7. Удаление объекта
Получение списка объектов с основными данными. Расширенные данные можно получить по запросу GET /objects/:id
Наименование |
Удаление объекта |
---|---|
URL |
/objects/:id |
Метод |
DELETE |
Параметры URL |
Обязательно: id:[UUID] Пример: 5213a389-ccda-11e6-9751-0cc47aac4166 |
Данные |
нет |
Ответ при удачном запросе |
Код ответа: 200 Content: { "status": 0, "object_id": %id%, "deleted": true } |
Ответ при ошибке |
Код ответа: 401 UNAUTHORIZED Содержимое: "" Возникает в случае, если пользователь не авторизован, либо у него нет прав на получение данных объекта или Код ответа: 500 Internal Server Error Содержимое: { error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях |
Пример использования |
|
3.8. Формат объекта
Идентификатор | Тип | Наименование | Доп. | Обяз. |
---|---|---|---|---|
object_num |
Строка |
Пультовый номер |
Уникальное поле, |
да |
address |
Объект Формат поля адрес |
Адрес объекта |
да |
|
category_id |
Число |
Категория объекта |
Варианты поля Категория объекта(category_id): Категория объекта |
да |
phone |
Строка |
Телефон на объекте |
нет |
|
name |
Строка |
Наименование объекта |
да |
|
locked |
Строка |
Характеристика объекта, уязвимые места и места возможного проникновения |
нет |
|
district_id |
UUID |
Идентификатор подразделения |
да |
|
type_id |
Число |
Тип объекта |
Варианты поля Тип объекта(type_id): Тип объекта |
да |
contacts |
Массив |
Доверенные лица |
Массив доверенных лиц |
нет |
zones |
Массив |
Зоны |
Массив зон объекта |
нет |
{
"object_num": "2", //Пультовый номер. Обязательное уникальное поле.
"address": { // Адрес объекта в виде строки или в формате поля адрес
"text": "Адрес объекта", //Пультовый номер. Обязательное уникальное поле.
"lat": 0.0, // Координаты объета, широта
"lng": 0.0, // Координаты объета, долгота
"comment": "Комментарий" // Комментарий к адресу, например уточнение какое здание или где вход
},
"category_id": 1,// Категория объекта по справочнику
"phone": "21321312312321",// Телефон на объекте
"name": "Аптека", // Наименование объекта
"locked": "fdsadasdasd", // Заблокированные и уязвимые места
"district_id": "5820ab00-3b53-480d-ba4a-bfdbb4eb603d", //Код Подразделения
"type_id": 0, // Тип объекта по справочнику
"contacts": [
{
"name": "Имя контакта",
"phone": "Телефон контакта"
}
],
"zones": [
{
"zone_num": "Номер зоны", // Произвольный номер зоны, используется при передаче тревоги
"name": "Наименование зоны",
"description": "Описание зоны"
}
]
}
3.8.1. Формат поля адрес
Идентификатор | Тип | Наименование | Доп. | Обяз. |
---|---|---|---|---|
text |
Строка |
Адрес объекта |
Адрес в человеко-читаемом виде, например: |
да |
lat |
Float 64 |
Координаты объекта, широта |
нет |
|
lng |
Float 64 |
Координаты объекта, долгота |
нет |
|
comment |
Строка |
Комментарий |
Комментарий к адресу, например: уточнение какое здание или где вход, этаж и т.д. |
нет |
{
"text": "Адрес объекта",
"lat": 55.56789,
"lng": 55.56789,
"comment": "Комментарий"
}
3.9. Работа с файлами
3.9.1. Добавление файла к объекту
Наименование |
Добавление файла к объекту |
---|---|
URL |
/objects/:id/file |
Метод |
POST |
Параметры URL |
id - Идентификатор объекта |
Данные |
JSON объект
|
Ответ при удачном запросе |
Код ответа: 200 Содержимое: { "description": "Описание файла", "id": "e9952ce6-e87e-11e6-8069-40167e6733b0", // идентификатор файла "name": "Наименование файла" } |
Ответ при ошибке |
Код ответа: 401 UNAUTHORIZED Содержимое: "" Возникает в случае, если пользователь не авторизован, либо у него нет прав на создание объекта или Код ответа: 500 Internal Server Error Содержимое: { error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях |
Пример использования |
3.9.2. Получение данных
Наименование |
Получение данных |
---|---|
URL |
/file/:id |
Метод |
GET |
Параметры URL |
Обязательно: id:[UUID] - Идентификатор файла Пример: 5213a389-ccda-11e6-9751-0cc47aac4166 |
Данные |
нет |
Ответ при удачном запросе |
Код ответа: 200 |
Ответ при ошибке |
Код ответа: 401 UNAUTHORIZED Возникает в случае, если пользователь не авторизован, либо у него нет прав на получение данных объекта или Код ответа: 500 Internal Server Error Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях |
Пример использования |
3.9.3. Удаление файла
Наименование |
Получение данных |
---|---|
URL |
/file/:id |
Метод |
DELETE |
Параметры URL |
Обязательно: id:[UUID] - Идентификатор файла Пример: 5213a389-ccda-11e6-9751-0cc47aac4166 |
Данные |
нет |
Ответ при удачном запросе |
Код ответа: 200 |
Ответ при ошибке |
Код ответа: 401 UNAUTHORIZED Возникает в случае, если пользователь не авторизован, либо у него нет прав на получение данных объекта или Код ответа: 500 Internal Server Error Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях |
Пример использования |
4. Тревоги
4.1. Поддерживаемые запросы по работе с тревогами
Метод | Параметры | Результат | Описание |
---|---|---|---|
GET GET https://pakvcmk.ru/api/alerts |
нет |
JSON Массив текущих тревог |
Получение списка всех активных тревог |
JSON Объект: Формат передаваемой тревоги |
JSON объект Тикет принятой тревоги |
Создание новой тревоги по объекту |
|
JSON Объект Формат события по тревоге |
JSON объект со временем передачи события: { "event_id": "ID события" "delivery_time":"0001-01-01T00:00:00Z" } |
Отправка события по тревоге |
|
JSON объект с комментарием о причине отмены: { "comment": "причина отмены" } |
code 200 В случае успеха, code 4**, 5** в случае ошибки и JSON объект: { "Error": "Сообщение об ошибке" } |
Отмена ранее переданной тревоги |
4.2. Создание новой тревоги по объекту
Наименование |
Создание новой тревоги по объекту |
---|---|
URL |
/alert |
Метод |
POST |
Параметры URL |
нет |
Данные |
JSON объект: Формат передаваемой тревоги |
Ответ при удачном запросе |
Код ответа: 200 Содержимое: JSON объект: Тикет принятой тревоги |
Ответ при ошибке |
Код ответа: 401 UNAUTHORIZED Содержимое: "" Возникает в случае, если пользователь не авторизован, либо у него нет прав на создание объекта или Код ответа: 500 Internal Server Error Содержимое: { error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях |
Пример использования |
4.3. Отправка нового события по тревоге
Наименование |
Отправка нового события по тревоге |
---|---|
URL |
/alert/:id/event |
Метод |
POST |
Параметры URL |
:id - Идентификатор тревоги |
Данные |
JSON объект: Формат события по тревоге |
Ответ при удачном запросе |
Код ответа: 200 Содержимое: JSON объект со временем передачи события:
|
Ответ при ошибке |
Код ответа: 401 UNAUTHORIZED Содержимое: "" Возникает в случае, если пользователь не авторизован, либо у него нет прав на создание объекта или Код ответа: 500 Internal Server Error Содержимое: { error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях |
Пример использования |
4.4. Получение списка активных тревог
Наименование |
Получение списка активных тревог |
---|---|
URL |
/alerts |
Метод |
GET |
Параметры URL |
нет |
Данные |
нет |
Ответ при удачном запросе |
Код ответа: 200 Содержимое: JSON Массив из Формат тревоги |
Ответ при ошибке |
Код ответа: 401 UNAUTHORIZED Содержимое: "" Возникает в случае, если пользователь не авторизован, либо у него нет прав на создание тревоги по объекту или Код ответа: 500 Internal Server Error Содержимое: { error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях |
Пример использования |
4.5. Отмена ранее переданной тревоги
Наименование |
Отмена ранее переданной тревоги |
---|---|
URL |
|
Метод |
POST |
Параметры URL |
:id - Идентификатор тревоги |
Данные |
JSON объект причиной отмены:
|
Ответ при удачном запросе |
Код ответа: 200 Содержимое: нет |
Ответ при ошибке |
Код ответа: 401 UNAUTHORIZED Содержимое: "" Возникает в случае, если пользователь не авторизован, либо у него нет прав на отмену тревоги или Код ответа: 500 Internal Server Error Содержимое: { Error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON или UUID в полях |
Пример использования |
|
4.6. Форматы данных
4.6.1. Формат тревоги
{
"alert_id": "b68eea07-51b3-11e7-b659-0cc47aac4166", // Уникальный идентификатор тревоги
"object_id": "bfe91973-5117-11e7-9a59-0cc47aac4166", // Уникальный идентификатор объекта
"status_id": 2, // Статус тревоги
"delivery_time": "2017-06-15T10:16:36.19Z", // Время доставки тревоги в систему
"take_time": "2017-06-15T11:38:32.038Z", // Время взятия тревоги в работу ДО УВО
"close_time": "0001-01-01T00:00:00Z", // Время закрытия тревоги ДО УВО или отмены МК
"is_false": false, // Флаг ложной тревоги
"comment": "", // Комментарий по тревоге
"district_id": "d8d7ef2c-5112-11e7-9a55-0cc47aac4166", // Подразделение, в которое была передана тревога
"region_id": "c2608f76-7129-414c-aff6-646423bc298a", // Регион, в который была передана тревога
"company_id": "8b9c1094-1516-11e7-aa20-0cc47aac4166", // Уникальный идентификатор компании
"eventList": [ // Массив событий по объекту
{
"event_id": "b69804f8-51b3-11e7-b65a-0cc47aac4166",
"alert_id": "b68eea07-51b3-11e7-b659-0cc47aac4166",
"delivery_time": "2017-06-15T13:16:36.250132925+03:00",
"comment": "",
"type_id": 2,
"zone_id": "fb409dab-5117-11e7-9a68-0cc47aac4166",
},
{
"event_id": "b698059e-51b3-11e7-b65b-0cc47aac4166",
"alert_id": "b68eea07-51b3-11e7-b659-0cc47aac4166",
"delivery_time": "2017-06-15T13:16:36.250150176+03:00",
"comment": "",
"type_id": 7,
"zone_id": "fb409da8-5117-11e7-9a67-0cc47aac4166"
}
],
// Массив действия дежурного
"reactionList": [
{
"reaction_type": 1, // Тип действия
"reaction_group_name": "Гбр №1", // Наименование экипажа
"delivery_time": "2017-06-15T15:36:16.487133724+03:00", // Время события
"comment": "Тест", // Комментарий либо доклад Г.З.
},
{
"reaction_type": 2,
"reaction_group_name": "Гбр №1",
"delivery_time": "2017-06-15T15:36:24.021047133+03:00",
"comment": "тест",
},
{
"reaction_type": 3,
"reaction_group_name": "Гбр №1",
"delivery_time": "2017-06-15T15:36:30.432696998+03:00",
"comment": "доклад",
}
]
}
4.6.2. Формат передаваемой тревоги
{
"object_id":"ID объекта в системе",
"events":
[
{
"zone_id": "ID зоны", //Необязательное поле
"type_id": 0 //Тип события,
"comment": "Комментарий события"
}
]
}
4.6.3. Тикет принятой тревоги
{
"alert_id": "ID Тревоги",
"delivery_time": "0001-01-01T00:00:00Z" //Время доставки тревоги в систему,
"district_id":"ID подразделения, обрабатывающего тревогу"
}
4.6.4. Формат события по тревоге
{
"zone_id": "ID зоны",
"type_id": 1, //Тип события
"comment": "Комментарий события"
}
4.6.5. Коды событий
2 |
Нападение |
4 |
Пожар |
5 |
Принуждение |
7 |
Подбор кода |
9 |
Проникновение |
5. Регионы / Подразделения
Метод | Параметры | Результат | Описание |
---|---|---|---|
нет |
JSON Массив регионов |
Получение списка регионов, доступных для данной компании |
|
нет |
JSON массив подразделений |
Получение списка подразделений по региону |
5.1. Получение списка регионов
Получение списка регионов, доступных для данной компании
Наименование |
Получение списка регионов, доступных для данной компании |
---|---|
URL |
/regions |
Метод |
GET |
Параметры URL |
нет |
Данные |
нет |
Ответ при удачном запросе |
Код ответа: 200 Содержимое: JSON Массив регионов |
Ответ при ошибке |
Код ответа: 401 UNAUTHORIZED Содержимое: "" Возникает в случае, если пользователь не авторизован, либо у него нет прав на создание объекта или Код ответа: 500 Internal Server Error Содержимое: { error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях |
Пример использования |
|
5.2. Формат списка регионов
[
{
"region_id": "Идентификатор региона [uuid]",
"name": "Наименование подразделения"
},...
]
5.3. Получение списка подразделений по региону
Получение списка регионов, доступных для данной компании
Наименование |
Получение списка всех объектов |
---|---|
URL |
/districts/:id |
Метод |
GET |
Параметры URL |
:id - Идентификатор региона |
Данные |
нет |
Ответ при удачном запросе |
Код ответа: 200 Содержимое: JSON Массив регионов |
Ответ при ошибке |
Код ответа: 401 UNAUTHORIZED Содержимое: "" Возникает в случае, если пользователь не авторизован, либо у него нет прав на создание объекта или Код ответа: 500 Internal Server Error Содержимое: { error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях |
Пример использования |
|
5.4. Формат подразделения
{
"district_id": "[uuid]", //Идентификатор подразделения
"region_id": "[uuid]", //Идентификатор региона
"name": [string], //Наименование подразделения
"address": [string], // Адрес подразделения
"phone":[string], // Телефоны подразделения
"time_zone" :[integer] // Смещение часового пояса подразделения относительно GMT
},
6. Передача изменений в мониторинговую компанию
Передача изменений состояния объекта в ПО мониторинговой компании осуществляется вызовом POST запроса по URL, указанном в настройках АРМ.
Настройка url производится в веб интерфейсе на странице https://pakvcmk.ru/#!/settings
Вызов данных url производится системой при любом изменении объекта или тревоги.
Для тревог вызов будет при взятии в работу, вызове ГЗ, закрытии тревоги и всех событиях.
Формат данных совпадает с форматом Формат объекта и Формат тревоги
7. Справочные данные
7.1. Статусы объекта
Поле status в карточках объектов
7.2. Статус тревоги
Поле status в данных тревог
7.3. Действие оператора
Поле reaction_type в reactionList тревоги
7.5. Категория объекта
Всего возможно 2 варианта:
7.7. Формат ответа при ошибке в REST API
При ошибке обработки запроса через http api возвращается структура в json:
7.8. Коды ошибок при работе через REST API
Актуальные данные по кодам ошибок можно получить по адресу:
https://pakvcmk.ru/api/errors
Запрос может быть выполнен без авторизации
Данные коды ошибок передаются, если в запросе передан валидный токен, иначе запрос вернет код ответа http 401 и json объект вида :