Описание API

Пример создания заявки через API из CURL на PHP

$host= 'http://localhost/api/requests/'; //запрос для каждой модели свой
$username = 'admin';
$password = 'admin';
$postFields = http_build_query(['service_id' => 3, 'CUsers_id' => 'admin', 'Status' => 'Открыта',
'ZayavCategory_id' => 'Заявка на обслуживание', 'Priority' => 'Низкий',
'Name' => 'Название', 'Content' => 'текст заявки']); //передается urlencoded POST-массив
$process = curl_init($host);
curl_setopt($process, CURLOPT_HEADER, 1);
curl_setopt($process, CURLOPT_USERPWD, $username . ":" . $password);
curl_setopt($process, CURLOPT_TIMEOUT, 30);
curl_setopt($process, CURLOPT_POST, 1);
curl_setopt($process, CURLOPT_POSTFIELDS, $postFields);
curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
$postFields = curl_exec($process);
curl_close($process);

Для авторизации необходимо передать логин и пароль пользователя через BASIC авторизацию. Роль пользователя должна иметь права на основные действия через API.

Сущность заявки - таблица request:

Получение всех заявок

GET /api/requests/

Возвращает массив объектов Request

Получение заявок с выборкой

GET /api/requests/?Managers_id=manager

(выборка заявок с определенным исполнителем, указывается логин);

GET /api/requests/?timestamp=2016-06-17

(выборка за определенную дату);

GET /api/requests/?timestamp=2016-06-17 10:00

(выборка за определенную дату и время);

GET /api/requests/?timestamp=>2016-06-17 10:00

(выборка за дату и время большую чем указана);

GET /api/requests/?service_id=3

(выборка по определенному сервису, id сервиса можно посмотреть в БД);

Возвращает массив объектов Request отфильтрованных по условию, поддерживаются значения = (равно), =<> (неравно), =< (меньше), => (больше).

Получение одной заявки

GET /api/requests/{id}

Возвращает объект Request по id

Создание новой заявки

POST /api/requests/

Для создания заявки необходимо передать объект Request. Минимальный набор полей для создания заявки:

service_id, Name, Content, Status, CUsers_id, Zayavcategory_id, Priority.

Редактирование заявки

PUT /api/requests/{id}

Для редактирования заявки по id, необходимо передать объект Request в JSON формате

Пример: {"Name":"TEST22","Content":"TEST55"}

Удаление заявки

DELETE /api/requests/{id}

Удаляет заявку по id

Получение записей истории заявки

GET /api/history/?zid={id}

Передача файлов вложени

Для передачи файлов, их необходимо предварительно загрузить и после передать в массиве files перечисление id файлов.

Описание полей таблицы request доступных через API:

Обозначение	Тип данных (длина)	Описание	Пример значения
id	int(10)	Идентификатор заявки (автоинкрементное поле)	2
pid	int(10)	Идентификатор родительской заявки	1
Name	varchar (100)	Тема обращения	Тестовая заявка
ZayavCategory_id	varchar (50)	Категория заявки	Заявка на обслуживание
Date	varchar (50)	Дата создания заявки (отображаемая)	07.05.2016 11:17
StartTime	varchar (50)	Планируемая дата начала исполнения (отображаемая)	09.05.2016 09:30
fStartTime	varchar (50)	Фактическая дата начала исполнения (отображаемая)	09.05.2016 09:27
EndTime	varchar (50)	Планируемая дата выполнения (отображаемая)	09.05.2016 10:30
fEndTime	varchar(50)	Фактическая дата выполнения (отображаемая)	09.05.2016 10:25
Status	varchar (100)	Статус заявки	Просрочено исполнение
slabel	varchar(400)	Статус заявки оформленный html тегами	Пример лэйбла можно посмотреть в БД
Priority	varchar (50)	Приоритет заявки	Низкий
Managers_id	varchar (50)	Логин исполнителя	manager
CUsers_id	varchar (50)	Логин пользователя	user
phone	varchar (50)	Телефон пользователя	+79003113133
room	varchar (50	Комната	233
Address	varchar (50)	Адрес пользователя	Москва, ул. Пупырина, д.6
company	varchar (50)	Компания пользователя	Компания А
Content	text	Содержимое заявки (HTML или Текст)	<p>Сломался принтер</p>
cunits	varchar (500)	Перечисление ID связанных конфигурационных единиц (через запятую)	1, 2, 5
closed	varchar (50)	Метка состояния заявки	1 - этот параметр означает новую заявку; 2 - этот параметр означает, что заявка принята в исполнение; 3 - этот параметр означает закрытие заявки, дальше его не будет обрабатывать CRON и сверять дедлайны; 8 - этот параметр означает, что заявка отложена; 10 - заявка в архиве;
service_id	int(10)	ID сервиса(находим в БД)	3
service_name	varchar (50)	Сервис заявки	Обслуживание внутренних клиентов
timestamp	datetime	Дата создания заявки	2016-06-17 10:46:41
timestampStart	datetime	Планируемая дата начала работ	2016-06-17 12:16:00
timestampfStart	datetime	Фактическая дата начала работ	2016-06-17 12:12:11
timestampEnd	datetime	Планируемая дата завершения работ	2016-06-17 01:16:00
timestampfEnd	datetime	Фактическая дата завершения работ	2016-06-17 01:13:27
fullname	varchar (100)	Имя заказчика в заявке	Администратор
mfullname	varchar (100)	Имя исполнителя в заявке	Васин В.В.
gfullname	varchar (100)	Группа исполнителя	Первая линия поддержки
creator	varchar (100)	Имя создателя заявки	Администратор
watchers	varchar (2000)	Наблюдатели (полные имена пользователей через запятую)	Администратор,Волобуев Антон
rating	int(1)	Оценка заявки	5
lead_time	time	Время выполнения заявки	00:53:33
subs	array	Массив с комментариями заявок	[...]
files	array	Массив с вложениями заявок	[...]
flds	array	Массив с дополнительными полями	[...]

Сущность комментарии к заявке:

Получение списка комментариев к заявке осуществляется через запрос к заявке по id

GET /api/requests/{id}

Список комментариев отдеается в массиве subs

Создание нового комментария к заявке

POST /api/comments/

Описание полей таблицы comments доступных через API:

Обозначение	Тип данных (длина)	Описание	Пример значения
id	int (10)	Идентификатор комментария	10
rid	int (10)	ID заявки к которой добавляется комментарий	22
timestamp	varchar (100)	Дата добавления	14.08.2018 09:49:46
author	varchar (100)	Автор комментария	Администратор
comment	text	Текст комментария (HTML или текст)	<p>Ваш комментарий в HTML формате</p>
show	int (1)	Отображать комментарий заказчику или нет	1 (не отображать) или 0 (отображать)
channel	varchar (100)	Канал получения комментария	email, manual, widget, telegram, viber, portal

Сущность вложения (файла) к заявке:

Создание нового вложения к заявке

POST /api/files/

Пример отправки файла через CURL на сервер:

curl -u admin:admin -F "file=@/home/20250616_125534.jpg" http://vsdesk.local/api/files

Для создания заявки необходимо передать объект типа file

Возвращает объект file, в котором ID, имя и URL файла.

{"url":"http:\/\/vsdesk.local\/uploads\/68a0c1f70429a.jpg","name":"20250616_125534.jpg","id":"10"}

При создании заявки можно передать массив загруженных ранее файлов files[]={id1,id2} с перечислением ID файлов.

Сущность пользователь - таблица CUsers:

Получение списка пользователей

GET /api/users/

Возвращает массив объектов User

Получение одной пользователя

GET /api/users/{id}

Возвращает объект User по id

Создание нового пользователя

POST /api/users/

Для создания пользователя необходимо передать объект User

Редактирование пользователя

PUT /api/users/{id}

Для редактирования пользователя по id, необходимо передать объект User

Удаление пользователя

DELETE /api/users/{id}

Удаляет пользователя по id

Описание полей таблицы CUsers доступных через API:

Обозначение	Тип данных (длина)	Описание	Пример
active	int(1)	Переключатель активности пользователя	1 - активен 0 - заблокирован
Username	varchar(50)	Логин пользователя	admin
fullname	varchar(100)	Полное имя пользователя	Администратор
Password	varchar(100)	Пароль пользователя	передается строка, хранится md5 хэш
Email	varchar(50)	Email пользователя	admin@email.com
Phone	varchar(50)	Телефон пользователя	+74955556677
intphone	varchar(50)	Внутренний телефон пользователя	109
mobile	ё(50)	Мобильный телефон пользователя	+79029992255
role	varchar(50)	Системная роль пользователя	vsdeskadmin
role_name	varchar(100)	Имя роли пользователя	Администратор
company_id	int(11)	ID компании из справочника Компании	3
company	varchar(100)	Название компании из справочника Компании	Компания А
room	varchar(50)	Комната пользователя	101
department	varchar(100)	Подразделение пользователя из справочника Подразделения	ИТ отдел
umanager	varchar(100)	Руководитель пользователя	Кузнецов А. С.
position	varchar(100)	Должность пользователя	Системный администратор
sendmail	int(1)	Флаг отправки уведомлений на Email	1 - отправлять 0 - не отправлять
sendsms	int(1)	Флаг отправки уведомлений через SMS и мессенджеры	1 - отправлять 0 - не отправлять
lang	varchar(50)	Язык системы	ru - Русский en - Английский
city	varchar(50)	Город пользователя	Москва
tbot	varchar(50)	ID чата Telegram	42938545783
vbot	varchar(50)	ID чата Viber	42938545784
msbot	varchar(50)	ID чата Microsoft Azure Bot Framework	42938545785
wbot	varchar(50)	ID чата WhatsApp	42938545786
send_wbot	int(1)	Флаг отправки уведомлений через WhatsApp	1 - отправлять 0 - не отправлять
send_tbot	int(1)	Флаг отправки уведомлений через Telegram	1 - отправлять 0 - не отправлять
send_vbot	int(1)	Флаг отправки уведомлений через Viber	1 - отправлять 0 - не отправлять
fontSize	int(2)	Размер шрифта в интерфейсе	12

Сущность актива - таблица assets:

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

GET /api/assets/

Возвращает массив объектовAsset

Получение одного актива

GET /api/assets/{id}

Возвращает объект Asset по id

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

POST /api/assets/

Для создания актива необходимо передать объектAsset

Редактирование актива

PUT /api/assets/{id}

Для редактирования актива по id, необходимо передать объект Asset

Удаление актива

DELETE /api/assets/{id}

Удаляет актив по id

Описание полей таблицы assets доступных через API:

Обозначение	Тип данных (длина)	Описание	Пример
uid	int(10)	Идентификтор КЕ, за которой закреплен актив.	1
date	varchar(50)	Дата создания актива	27.12.2014 14:03
name	varchar(50)	Наименование актива	ПК Кузнецова
location	varchar(50)	Местоположение актива	Склад №5
inventory	varchar(50)	Инвентарный номер актива	PC-125987-34
status	varchar(50)	Статус актива	Используется
slabel	varchar(400)	Статус актива оформленный html тегами	Пример можно посмотреть в БД
cost	varchar(50)	Стоимость актива	22500
asset_attrib_id	int(10)	Тип актива, id из справочника Типы актива	6
asset_attrib_name	varchar(50)	Тип актива, Имя из справочника Типы актива	Системный блок
cusers_id	int(10)	id пользователя из справочника Пользователи	1
cusers_name	varchar(50)	Логин пользователя из справочника Пользователи	user
cusers_fullname	varchar(50)	Имя пользователя из справочника Пользователи	Кузнецов А. С.
cusers_dept	varchar(50)	Подразделение пользователя из справочника Пользователи	Отдел продаж
items	array()	Массив характеристик актива	[...]

Сущность КЕ - таблица cunits:

Получение всех КЕ

GET /api/cunits/

Возвращает массив объектов Cunit

Получение одной КЕ

GET /api/cunits/{id}

Возвращает объект Cunit по id

Создание новойКЕ

POST /api/cunits/

Для создания КЕ необходимо передать объект Cunit

Редактирование КЕ

PUT /api/cunits/{id}

Для редактирования КЕ по id, необходимо передать объект Cunit

Удаление КЕ

DELETE /api/cunits/{id}

Удаляет КЕ по id

Описание полей таблицы cunits доступных через API:

Обозначение	Тип данных (длина)	Описание	Пример
name	varchar(100)	Наименование КЕ	ПК Кузнецова
type	varchar(50)	Тип КЕ из справочника Типы КЕ	Рабочая станция
status	varchar(50)	Статус КЕ из справочника Статусы активов и КЕ	Используется
slabel	varchar(400)	Статус КЕ оформленный html тегами	Лейбл можно посмотреть в БД
cost	varchar(50)	Стоимость КЕ	39800
user	varchar(50)	Логин пользователя из справочника Пользователи	user
fullname	varchar(70)	Полное имя пользователя из справочника Пользователи	Кузнецов А. С.
dept	varchar(100)	Подразделение пользователя	Отдел продаж
inventory	varchar(50)	Инвентарный № КЕ	WS-156798
date	varchar(50)	Дата создания КЕ	27.12.2014 14:05
datein	varchar(50)	Дата ввода в эксплуатацию	27.12.2014
dateout	varchar(50)	Дата вывода из эксплуатации	27.12.2044
company	varchar(70)	Компания пользователя	Компания А
assets	varchar(2000)	Активы закрепленные за КЕ (перечисление id активов)	3,4,5,1,2
location	varchar(100)	Местоположение КЕ	Склад №2

Сущность Компания - таблица companies:

Получение всех Компаний

GET /api/companies/

Возвращает массив объектов Company

Получение одной Компании

GET /api/companies/{id}

Возвращает объект Company по id

Создание новой Компании

POST /api/companies/

Для создания компании необходимо передать объект Company

Редактирование Компании

PUT /api/companies/{id}

Для редактирования компании по id, необходимо передать объект Company

Удаление компании

DELETE /api/companies/{id}

Удаляет компании по id

Описание полей таблицы companies доступных через API:

Обозначение	Тип данных (длина)	Описание	Пример
name	varchar(100)	Имя компании	Компания А
director	varchar(50)	Имя директора компании	Пупкин И. С.
head_position	varchar(100)	Должность директора в склонении	Генерального директора
head_name_writeable	varchar(100)	Имя директора в склонении	Пупкина Игоря Сергеевича
uraddress	varchar(200)	Юридический адрес	Москва, ул. Пупырина, д.6, кв.777
faddress	varchar(200)	Фактический адрес	Москва, ул. Пупырина, д.6, кв.777
contact_name	varchar(100)	Имя контактного лица	Кузнецов Алексей
phone	varchar(50)	Телефон контактного лица	+79999999999
email	varchar(50)	Email контактного лица	email@email.com
manager	varchar(50)	Менеджер компании, логин из справочника Пользователи	manager
inn	varchar(20)	ИНН компании	12345678910
kpp	varchar(20)	КПП компании	123456789
ogrn	varchar(20)	ОГРН компании	1234567891023
bank	varchar(100)	Название банка	ПАО ДверьБанк
bik	varchar(20)	Бик банка	045879524
korschet	varchar(50)	Корр. счет банка	45678912306547896514
schet	varchar(50)	Расчетный счет банка	25112555512658815252
domains	text	Почтовые домены компании (перечисление через запятую)	domain1.com, domain2.com
add1	text	Дополнительное поле 1	Дополнительное поле 1
add2	text	Дополнительное поле 2	Дополнительное поле 2