API ПАК ВсМК

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. Работа с объектами

Метод	Параметры	Результат	Описание
GET https://pakvcmk.ru/api/objects	нет	JSON Массив объектов	Получение списка всех объектов компании
GET https://pakvcmk.ru/api/objects/:id	нет	JSON объект	Получение информации по объекту
DELETE https://pakvcmk.ru/api/objects/:id	нет		Удаление объекта
POST https://pakvcmk.ru/api/objects	JSON объект	code 201 - Created { "status": "success", "object_id": "%id%" }	Создание нового объекта
PUT https://pakvcmk.ru/api/objects/:id	Аналогично POST запросу	В случае успеха: code 200 Json объект с новыми данными. Код ошибки 4 или 5 { "error" :"Описание ошибки" }	Изменение объекта
POST https://pakvcmk.ru/api/approve	{ "object_id": "ID объекта", "comment" : "Тест комментария" }	В случае успеха: code 200	Передача объекта на согласование

Метод

Параметры

Результат

Описание

GET https://pakvcmk.ru/api/objects

нет

JSON Массив объектов

Получение списка всех объектов компании

GET https://pakvcmk.ru/api/objects/:id

нет

JSON объект

Получение информации по объекту

DELETE https://pakvcmk.ru/api/objects/:id

нет

Удаление объекта

POST https://pakvcmk.ru/api/objects

JSON объект

code 201 - Created

{ "status": "success", "object_id": "%id%" }

Создание нового объекта

PUT https://pakvcmk.ru/api/objects/:id

Аналогично POST запросу

В случае успеха:

code 200 Json объект с новыми данными.

Код ошибки 4** или 5**

{ "error" :"Описание ошибки" }

Изменение объекта

POST https://pakvcmk.ru/api/approve

{

"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 в полях
Пример использования	$.ajax({ url: "/objects", dataType: "json", data : { "object_num": "2", "address": "dfsadasdasdasd", "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"=> "Описание зоны" } ] }, type : "PUT", success : function(r) { console.log(r); } });

Наименование

Добавление нового объекта в систему

URL

/objects

Метод

POST

Параметры URL

нет

Данные

JSON Формат объекта

Ответ при удачном запросе

Код ответа: 201

Содержимое: {status: "success", object_id: %id%}

Ответ при ошибке

Код ответа: 401 UNAUTHORIZED

Содержимое: ""

Возникает в случае, если пользователь не авторизован, либо у него нет прав на создание объекта

или

Код ответа: 500 Internal Server Error

Содержимое: { error : "Описание ошибки" }

Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях

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

$.ajax({
  url: "/objects",
  dataType: "json",
  data : {
  "object_num": "2",
  "address": "dfsadasdasdasd",
  "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"=> "Описание зоны"
   }
  ]
 },
  type : "PUT",
  success : function(r) {
    console.log(r);
  }
});

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 в полях
Пример использования	$.ajax({ url: "/objects/5213a389-ccda-11e6-9751-0cc47aac4166", dataType: "json", data : { "object_num": "2", "address": "dfsadasdasdasd", "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"=> "Описание зоны" } ] }, type : "PUT", success : function(r) { console.log(r); } });

Наименование

Изменение данных объекта

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 в полях

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

$.ajax({
  url: "/objects/5213a389-ccda-11e6-9751-0cc47aac4166",
  dataType: "json",
  data : {
  "object_num": "2",
  "address": "dfsadasdasdasd",
  "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"=> "Описание зоны"
   }
  ]
 },
  type : "PUT",
  success : function(r) {
    console.log(r);
  }
});

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 в полях
Пример использования	`$.ajax({ url: "/objects/5213a389-ccda-11e6-9751-0cc47aac4166", type : "GET", success : function(r) { console.log(r); } });`

Наименование

Получение списка всех объектов

URL

/objects/:id

Метод

GET

Параметры URL

Обязательно:

id:[UUID]
Пример: 5213a389-ccda-11e6-9751-0cc47aac4166

Данные

нет

Ответ при удачном запросе

Код ответа: 200

Содержимое: JSON Формат объекта

Ответ при ошибке

Код ответа: 401 UNAUTHORIZED

Содержимое: ""

Возникает в случае, если пользователь не авторизован, либо у него нет прав на получение данных объекта

или

Код ответа: 500 Internal Server Error

Содержимое: { error : "Описание ошибки" }

Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях

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

$.ajax({
  url: "/objects/5213a389-ccda-11e6-9751-0cc47aac4166",
  type : "GET",
  success : function(r) {
    console.log(r);
  }
});

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

Получение списка объектов с основными данными. Расширенные данные можно получить по запросу Получение объекта

Наименование	Получение списка всех объектов
URL	/objects
Метод	GET
Параметры URL	нет
Данные	нет
Ответ при удачном запросе	Код ответа: 200 Содержимое: JSON Массив объектов [ Формат объекта, Формат объекта ]
Ответ при ошибке	Код ответа: 401 UNAUTHORIZED Содержимое: "" Возникает в случае, если пользователь не авторизован, либо у него нет прав на создание объекта или Код ответа: 500 Internal Server Error Содержимое: { error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях
Пример использования	`$.ajax({ url: "/objects", dataType: "json", type : "GET", success : function(r) { console.log(r); } });`

Наименование

Получение списка всех объектов

URL

/objects

Метод

GET

Параметры URL

нет

Данные

нет

Ответ при удачном запросе

Код ответа: 200

Содержимое: JSON Массив объектов

[ Формат объекта, Формат объекта ]

Ответ при ошибке

Код ответа: 401 UNAUTHORIZED

Содержимое: ""

Возникает в случае, если пользователь не авторизован, либо у него нет прав на создание объекта

или

Код ответа: 500 Internal Server Error

Содержимое: { error : "Описание ошибки" }

Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях

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

$.ajax({
  url: "/objects",
  dataType: "json",
  type : "GET",
  success : function(r) {
    console.log(r);
  }
});

3.5. Передача объекта на согласование

Наименование	Передача объекта на согласование с подразделением УВО
URL	/approve
Метод	POST
Параметры URL	нет
Данные	JSON объект `{ "object_id": "ID объекта", "comment" : "Тест комментария" }`
Ответ при удачном запросе	Код ответа: 200 Содержимое: ""
Ответ при ошибке	Code: 400 Bad Request Content: {Error:"описание ошибки"} Возникает в случае, если согласование объекта невозможно по каким-либо причинам Code: 401 UNAUTHORIZED Content: {Error:"no access"} Возникает в случае, если пользователь не авторизован, либо у него нет прав на изменение объекта Code: 500 Internal Server Error Content: { error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях
Пример использования	`$.ajax({ url: "/approve", dataType: "json", data : { "object_id": "5213a389-ccda-11e6-9751-0cc47aac4166", "comment": "Первичное согласование объекта" }, type : "POST", success : function(r) { console.log(r); } });`

Наименование

Передача объекта на согласование с подразделением УВО

URL

/approve

Метод

POST

Параметры URL

нет

Данные

JSON объект

{
 "object_id": "ID объекта",
 "comment" : "Тест комментария"
}

Ответ при удачном запросе

Код ответа: 200
Содержимое: ""

Ответ при ошибке

Code: 400 Bad Request
Content: {Error:"описание ошибки"}

Возникает в случае, если согласование объекта невозможно по каким-либо причинам

Code: 401 UNAUTHORIZED
Content: {Error:"no access"}

Возникает в случае, если пользователь не авторизован, либо у него нет прав на изменение объекта

Code: 500 Internal Server Error
Content: { error : "Описание ошибки" }

Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях

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

$.ajax({
  url: "/approve",
  dataType: "json",
  data : {
  "object_id": "5213a389-ccda-11e6-9751-0cc47aac4166",
  "comment": "Первичное согласование объекта"
 },
  type : "POST",
  success : function(r) {
    console.log(r);
  }
});

3.6. Отмена согласования объекта

Наименование	Снятие согласования объекта с подразделением УВО
URL	/unapprove
Метод	POST
Параметры URL	нет
Данные	JSON объект `{ "object_id": "ID объекта", "comment" : "Тест комментария" }`
Ответ при удачном запросе	Код ответа: 200 Содержимое: ""
Ответ при ошибке	Code: 400 Bad Request Content: {Error:"описание ошибки"} Возникает в случае, если согласование объекта невозможно по каким-либо причинам Code: 401 UNAUTHORIZED Content: {Error:"no access"} Возникает в случае, если пользователь не авторизован, либо у него нет прав на изменение объекта Code: 403 Forbidden Content: {Error:"Exists alerts on this object"} Code: 500 Internal Server Error Content: { error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях
Пример использования	`$.ajax({ url: "/unapprove", dataType: "json", data : { "object_id": "5213a389-ccda-11e6-9751-0cc47aac4166", "comment": "Закрытие договора" }, type : "POST", success : function(r) { console.log(r); } });`

Наименование

Снятие согласования объекта с подразделением УВО

URL

/unapprove

Метод

POST

Параметры URL

нет

Данные

JSON объект

{
 "object_id": "ID объекта",
 "comment" : "Тест комментария"
}

Ответ при удачном запросе

Код ответа: 200

Содержимое: ""

Ответ при ошибке

Code: 400 Bad Request
Content: {Error:"описание ошибки"}

Возникает в случае, если согласование объекта невозможно по каким-либо причинам

Code: 401 UNAUTHORIZED
Content: {Error:"no access"}

Возникает в случае, если пользователь не авторизован, либо у него нет прав на изменение объекта

Code: 403 Forbidden
Content: {Error:"Exists alerts on this object"}

Code: 500 Internal Server Error
Content: { error : "Описание ошибки" }

Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях

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

$.ajax({
  url: "/unapprove",
  dataType: "json",
  data : {
  "object_id": "5213a389-ccda-11e6-9751-0cc47aac4166",
  "comment": "Закрытие договора"
 },
  type : "POST",
  success : function(r) {
    console.log(r);
  }
});

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 в полях
Пример использования	`$.ajax({ url: "/objects/5213a389-ccda-11e6-9751-0cc47aac4166", type : "DELETE", success : function(r) { console.log(r); } });`

Наименование

Удаление объекта

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 в полях

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

$.ajax({
  url: "/objects/5213a389-ccda-11e6-9751-0cc47aac4166",
  type : "DELETE",
  success : function(r) {
    console.log(r);
  }
});

3.8. Формат объекта

Table 1. Список полей
Идентификатор	Тип	Наименование	Доп.	Обяз.
object_num	Строка	Пультовый номер	Уникальное поле,	да
address	Объект Формат поля адрес	Адрес объекта		да
category_id	Число	Категория объекта	Варианты поля Категория объекта(category_id): Категория объекта	да
phone	Строка	Телефон на объекте		нет
name	Строка	Наименование объекта		да
locked	Строка	Характеристика объекта, уязвимые места и места возможного проникновения		нет
district_id	UUID	Идентификатор подразделения		да
type_id	Число	Тип объекта	Варианты поля Тип объекта(type_id): Тип объекта	да
contacts	Массив	Доверенные лица	Массив доверенных лиц	нет
zones	Массив	Зоны	Массив зон объекта	нет

Listing 1. Пример данных в json

{
"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. Формат поля адрес

Table 2. Список полей
Идентификатор	Тип	Наименование	Доп.	Обяз.
text	Строка	Адрес объекта	Адрес в человеко-читаемом виде, например: `г Москва, ул Ленина, д 1, кв 1`. В случае отсутствия координат будет произведена попытка их определения на основе адреса.	да
lat	Float 64	Координаты объекта, широта		нет
lng	Float 64	Координаты объекта, долгота		нет
comment	Строка	Комментарий	Комментарий к адресу, например: уточнение какое здание или где вход, этаж и т.д.	нет

Listing 2. Пример данных в json

{
"text": "Адрес объекта",
"lat": 55.56789,
"lng": 55.56789,
"comment": "Комментарий"
}

3.9. Работа с файлами

3.9.1. Добавление файла к объекту

Наименование	Добавление файла к объекту
URL	/objects/:id/file
Метод	POST
Параметры URL	id - Идентификатор объекта
Данные	JSON объект `{ "name": "Наименование файла", "description": "Описание файла", "file": "base64 кодированный файл" }`
Ответ при удачном запросе	Код ответа: 200 Содержимое: { "description": "Описание файла", "id": "e9952ce6-e87e-11e6-8069-40167e6733b0", // идентификатор файла "name": "Наименование файла" }
Ответ при ошибке	Код ответа: 401 UNAUTHORIZED Содержимое: "" Возникает в случае, если пользователь не авторизован, либо у него нет прав на создание объекта или Код ответа: 500 Internal Server Error Содержимое: { error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях
Пример использования

Наименование

Добавление файла к объекту

URL

/objects/:id/file

Метод

POST

Параметры URL

id - Идентификатор объекта

Данные

JSON объект

{
    "name": "Наименование файла",
    "description": "Описание файла",
    "file": "base64 кодированный файл"
}

Ответ при удачном запросе

Код ответа: 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 Содержимое: { error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях
Пример использования

Наименование

Получение данных

URL

/file/:id

Метод

GET

Параметры URL

Обязательно:

id:[UUID] - Идентификатор файла
Пример: 5213a389-ccda-11e6-9751-0cc47aac4166

Данные

нет

Ответ при удачном запросе

Код ответа: 200
Содержимое: Содержимое файла

Ответ при ошибке

Код ответа: 401 UNAUTHORIZED
Содержимое: ""

Возникает в случае, если пользователь не авторизован, либо у него нет прав на получение данных объекта

или

Код ответа: 500 Internal Server Error
Содержимое: { 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 Содержимое: { error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях
Пример использования

Наименование

Получение данных

URL

/file/:id

Метод

DELETE

Параметры URL

Обязательно:

id:[UUID] - Идентификатор файла
Пример: 5213a389-ccda-11e6-9751-0cc47aac4166

Данные

нет

Ответ при удачном запросе

Код ответа: 200
Содержимое: Содержимое файла

Ответ при ошибке

Код ответа: 401 UNAUTHORIZED
Содержимое: ""

Возникает в случае, если пользователь не авторизован, либо у него нет прав на получение данных объекта

или

Код ответа: 500 Internal Server Error
Содержимое: { error : "Описание ошибки" }

Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях

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

4. Тревоги

4.1. Поддерживаемые запросы по работе с тревогами

Метод	Параметры	Результат	Описание
GET GET https://pakvcmk.ru/api/alerts	нет	JSON Массив текущих тревог	Получение списка всех активных тревог
POST https://pakvcmk.ru/api/alert	JSON Объект: Формат передаваемой тревоги	JSON объект Тикет принятой тревоги	Создание новой тревоги по объекту
POST https://pakvcmk.ru/api/alert/:id/event	JSON Объект Формат события по тревоге	JSON объект со временем передачи события: { "event_id": "ID события" "delivery_time":"0001-01-01T00:00:00Z" }	Отправка события по тревоге
POST https://pakvcmk.ru/api/alert/:id/cancel	JSON объект с комментарием о причине отмены: { "comment": "причина отмены" }	code 200 В случае успеха, code 4, 5 в случае ошибки и JSON объект: { "Error": "Сообщение об ошибке" }	Отмена ранее переданной тревоги

Метод

Параметры

Результат

Описание

GET GET https://pakvcmk.ru/api/alerts

нет

JSON Массив текущих тревог

Получение списка всех активных тревог

POST https://pakvcmk.ru/api/alert

JSON Объект: Формат передаваемой тревоги

JSON объект Тикет принятой тревоги

Создание новой тревоги по объекту

POST https://pakvcmk.ru/api/alert/:id/event

JSON Объект Формат события по тревоге

JSON объект со временем передачи события:

{ "event_id": "ID события" "delivery_time":"0001-01-01T00:00:00Z" }

Отправка события по тревоге

POST https://pakvcmk.ru/api/alert/:id/cancel

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 в полях
Пример использования

Наименование

Создание новой тревоги по объекту

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 объект со временем передачи события: `{ "event_id": "ID события", "delivery_time":"0001-01-01T00:00:00Z" }`
Ответ при ошибке	Код ответа: 401 UNAUTHORIZED Содержимое: "" Возникает в случае, если пользователь не авторизован, либо у него нет прав на создание объекта или Код ответа: 500 Internal Server Error Содержимое: { error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях
Пример использования

Наименование

Отправка нового события по тревоге

URL

/alert/:id/event

Метод

POST

Параметры URL

:id - Идентификатор тревоги

Данные

JSON объект: Формат события по тревоге

Ответ при удачном запросе

Код ответа: 200

Содержимое: JSON объект со временем передачи события:

{
    "event_id": "ID события",
    "delivery_time":"0001-01-01T00:00:00Z"
}

Ответ при ошибке

Код ответа: 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 в полях
Пример использования

Наименование

Получение списка активных тревог

URL

/alerts

Метод

GET

Параметры URL

нет

Данные

нет

Ответ при удачном запросе

Код ответа: 200

Содержимое: JSON Массив из Формат тревоги

[ Формат тревоги, Формат тревоги ]

Ответ при ошибке

Код ответа: 401 UNAUTHORIZED

Содержимое: ""

Возникает в случае, если пользователь не авторизован, либо у него нет прав на создание тревоги по объекту

или

Код ответа: 500 Internal Server Error

Содержимое: { error : "Описание ошибки" }

Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях

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

4.5. Отмена ранее переданной тревоги

Наименование	Отмена ранее переданной тревоги
URL	https://pakvcmk.ru/api/alert/:id/cancel
Метод	POST
Параметры URL	:id - Идентификатор тревоги
Данные	JSON объект причиной отмены: `{ "comment": "причина отмены" }`
Ответ при удачном запросе	Код ответа: 200 Содержимое: нет
Ответ при ошибке	Код ответа: 401 UNAUTHORIZED Содержимое: "" Возникает в случае, если пользователь не авторизован, либо у него нет прав на отмену тревоги или Код ответа: 500 Internal Server Error Содержимое: { Error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON или UUID в полях
Пример использования	`$.ajax({ url: "/api/alert/5213a389-ccda-11e6-9751-0cc47aac4166/cancel", dataType: "json", data : { "comment": "Получен ответ от собственника" }, type : "POST", success : function(r) { console.log(r); } });`

Наименование

Отмена ранее переданной тревоги

URL

https://pakvcmk.ru/api/alert/:id/cancel

Метод

POST

Параметры URL

:id - Идентификатор тревоги

Данные

JSON объект причиной отмены:

{
"comment": "причина отмены"
}

Ответ при удачном запросе

Код ответа: 200

Содержимое: нет

Ответ при ошибке

Код ответа: 401 UNAUTHORIZED

Содержимое: ""

Возникает в случае, если пользователь не авторизован, либо у него нет прав на отмену тревоги

или

Код ответа: 500 Internal Server Error

Содержимое: { Error : "Описание ошибки" }

Возникает при указании ошибочных данных, неправильного формата JSON или UUID в полях

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

$.ajax({
  url: "/api/alert/5213a389-ccda-11e6-9751-0cc47aac4166/cancel",
  dataType: "json",
  data : {
  "comment": "Получен ответ от собственника"
 },
  type : "POST",
  success : function(r) {
    console.log(r);
  }
});

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. Регионы / Подразделения

Метод	Параметры	Результат	Описание
GET https://pakvcmk.ru/api/regions	нет	JSON Массив регионов	Получение списка регионов, доступных для данной компании
GET https://pakvcmk.ru/api/districts/:id	нет	JSON массив подразделений	Получение списка подразделений по региону

Метод

Параметры

Результат

Описание

GET https://pakvcmk.ru/api/regions

нет

JSON Массив регионов

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

GET https://pakvcmk.ru/api/districts/:id

нет

JSON массив подразделений

Получение списка подразделений по региону

5.1. Получение списка регионов

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

Наименование	Получение списка регионов, доступных для данной компании
URL	/regions
Метод	GET
Параметры URL	нет
Данные	нет
Ответ при удачном запросе	Код ответа: 200 Содержимое: JSON Массив регионов Формат списка регионов
Ответ при ошибке	Код ответа: 401 UNAUTHORIZED Содержимое: "" Возникает в случае, если пользователь не авторизован, либо у него нет прав на создание объекта или Код ответа: 500 Internal Server Error Содержимое: { error : "Описание ошибки" } Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях
Пример использования	`$.ajax({ url: "/regions", dataType: "json", type : "GET", success : function(r) { console.log(r); } });`

Наименование

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

URL

/regions

Метод

GET

Параметры URL

нет

Данные

нет

Ответ при удачном запросе

Код ответа: 200

Содержимое: JSON Массив регионов

Формат списка регионов

Ответ при ошибке

Код ответа: 401 UNAUTHORIZED

Содержимое: ""

Возникает в случае, если пользователь не авторизован, либо у него нет прав на создание объекта

или

Код ответа: 500 Internal Server Error

Содержимое: { error : "Описание ошибки" }

Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях

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

$.ajax({
  url: "/regions",
  dataType: "json",
  type : "GET",
  success : function(r) {
    console.log(r);
  }
});

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 в полях
Пример использования	`$.ajax({ url: "/districts/41643c07-ee81-4d68-bf15-c4ff4a2c8a06", dataType: "json", type : "GET", success : function(r) { console.log(r); } });`

Наименование

Получение списка всех объектов

URL

/districts/:id

Метод

GET

Параметры URL

:id - Идентификатор региона

Данные

нет

Ответ при удачном запросе

Код ответа: 200

Содержимое: JSON Массив регионов

[ Формат подразделения, Формат подразделения ]

Ответ при ошибке

Код ответа: 401 UNAUTHORIZED

Содержимое: ""

Возникает в случае, если пользователь не авторизован, либо у него нет прав на создание объекта

или

Код ответа: 500 Internal Server Error

Содержимое: { error : "Описание ошибки" }

Возникает при указании ошибочных данных, неправильного формата JSON, даты или UUID в полях

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

$.ajax({
  url: "/districts/41643c07-ee81-4d68-bf15-c4ff4a2c8a06",
  dataType: "json",
  type : "GET",
  success : function(r) {
    console.log(r);
  }
});

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 в карточках объектов

1 Новый объект

2 Объект на согласовании

3 Объект на охране

4 Отклонен

5 Отключен

6 На охране / проверка

7 На охране / изменения отклонены

7.2. Статус тревоги

Поле status в данных тревог

Статуты > 90 Означают закрытую тревогу

0: Новая тревога

1: Принята

2: В работе

98: Отменена МК без взятия в работу Д.О.

99: Закрыта Д.О.

7.3. Действие оператора

Поле reaction_type в reactionList тревоги

1: Вызов группы задержания

2: Прибытие группы задержания

3: Доклад группы задержания

4: Отмена вызова группы

7.4. Коды событий

2: Нападение

4: Пожар

5: Принуждение

7: Подбор кода

9: Проникновение

7.5. Категория объекта

Всего возможно 2 варианта:

0: Обычный объект

1: Особо важный объект

7.6. Тип объекта

1: квартира

2: объект

3: МХИГ

7.7. Формат ответа при ошибке в REST API

При ошибке обработки запроса через http api возвращается структура в json:

{
    "Error":"Тестовое описание ошибки",
    "ErrorCode": integer // Код ошибка по справочнику
}

7.8. Коды ошибок при работе через REST API

Актуальные данные по кодам ошибок можно получить по адресу:

https://pakvcmk.ru/api/errors

Запрос может быть выполнен без авторизации

Данные коды ошибок передаются, если в запросе передан валидный токен, иначе запрос вернет код ответа http 401 и json объект вида :

{ "Error": "Not Authorized" }

7.8.1. Коды ошибок

1: "Нет доступа"

2: "Некорректный запрос"

3: "Недостаточно данных"

4: "Пультовый повторяется"

5: "Не найден объект или тревога"

6: "Объект на проверке"

7: "Объект не на охране"

8: "Отсутствует договор по региону"

9: "Отсутствует подразделение"

10: "Отсутствует регион"

11: "По объекту есть тревоги"

12: "Тревога закрыта"

13: "Тревога отменена"

14: "Зона не найдена"

15: "Ошибка при обработке запроса"