Service Desk - API
НАЧАТЬ БЕСПЛАТНО Войти
+7 (499) 755-65-68 information@intradesk.ru support@intradesk.ru
Создание заявки
Копировать ссылку на статью

Задача

Создать заявку: «Не работает сервер X». Пометить её тегом “monitoring”

Полная документация по API (swagger)

Решение

Продемонстрируем решение в общеизвестной программе тестирования API - Postman.
Для начала в разделе Настройки -> Теги создайте тег “monitoring”. В нашем примере система присвоила ему ID=33290.


Post запрос будет вида:

POST https://apigw.intradesk.ru/changes/tasks?ApiKey=1B42B8691ABB40AA961451D9AC
Значение Apikey можно получить в системе в разделе: Настройки -> Интеграции -> Apikey

Тело запроса:


{
  "blocks": {
          "name": "{\"value\":\"Не работает сервер X1. Просьба починить.\"}",        
          "description": "{\"value\":\"Даже не запускается. Лампочки не горят.\"}",
          "tags": "{\"value\":[33290]}"
  },
  "Channel": "web"
}

Скопируйте тело запроса в программу Postman. Пункт меню: Body -> raw как на рисунке ниже:



Также на закладке Headers задайте Content-Type равным «application/json» как на рисунке ниже, и нажмите кнопку Send:



Всё! Заявка создана.

См. также изменение заявки.
Полная документация к методу в формате swagger (ChangeService API)


Изменение заявки
Копировать ссылку на статью

Задача

Поменять у заявки статус на «В работе», назначить сервис/тип: «Сервера, компьютеры (железо)” / ”инцидент”, назначить исполнителя «Первая линия поддержки»/«Мастерков А.А.», установить плановый срок выполнения «15.03.2022 18:00», установить теги, добавить комментарий «Постараемся сделать до обеда» (полный список полей, которых можно поменять одним запросом на заявке).

Полная документация по API (swagger)

Решение

Put запрос будет вида:

PUT https://apigw.intradesk.ru/changes/tasks/?ApiKey=65247DBDE14C45A6A275DC1FC0

Значение Apikey можно получить в системе в разделе: Настройки -> Интеграции -> Apikey
Установить Content-Type = «application/json»

Тело запроса: 

{
    "number": 272,
    "blocks": {
              "status": "{\"value\": 22058}",
              "service": "{\"value\": \"23097/\"}",
              "tasktype": "{\"value\": 7805}",
              "executor": "{\"value\":{\"userid\":109747,\"groupid\":31974}}",
              "resolutiondateplan": "{\"value\": \"2022-03-15T15:00:00.0000000Z\"}",
              "tags": "{\"value\": [32887,32893]}",
              "comment": "{\"value\":\"Постараемся сделать до обеда.\"}",
              "evaluation": "{\"value\":{\"value\":3,\"text\":\"Удовлетворительно\"}}"
    },  
    "Channel": "api"
}

status Статус заявки. См: Настройки->Справочники ->Статусы . см. поле ID на списке

service Сервис. См: Настройки->Сервисы см. поле «путь сервиса» на карточке сервиса

tasktype Тип заявки. См: Настройки->Заявки->Типы заявок . см. поле ID на списке

tags Теги по заявки. См: Настройки->Теги . см. поле ID на списке

executor Исполнители. Составное поле. Можно указать Группу исполнителей, можно конкретного Исполнителя, можно и Группу и Исполнителя из этой группы одновременно. Что и продемонстриовано. Смотри раздел Сотрудники-Люди и Сотрудники-Группы. см. поле ID на списке

comment Добавление комментария

evaluation Оценка заявки


Список всех полей, которых можно изменить одним запросом см. здесь.
Полная документация к методу в формате swagger (ChangeService API)

Получение списка заявок
Копировать ссылку на статью

Задача

Получить первые 5 заявок в статусах «открыта» и «в работе», с группой исполнителей «менеджеры», в сервисе «Программное обеспечение» (и дочерних сервисах). Отсортированные по дате изменения.

Полная документация по API (swagger)

Решение

Get запрос будет вида:

https://apigw.intradesk.ru/tasklist/odata/tasks?ApiKey=65247DBDE14C45A6A275DC1FC0&$filter=(status eq 22055 or status eq 22058) and executorgroup eq 31973 and servicepath eq '3974/'&$orderby=updatedat desc&$top=5

Значение Apikey можно получить в системе в разделе: Настройки -> Интеграции -> Apikey
status Статус «открыта» id: 22055 См: Настройки->Справочники->Статусы . см. поле ID на списке
Статус «в работе» id: 22058

executorgroup Группа исполнители «менеджеры» id: 31973. см. Сотрудники -> Группы

servicepath Сервис «Программное обеспечение» servicepath: 3974 см. Настройки -> Сервисы

Любое из условий фильтрации вы можете опустить (не использовать), а также добавить другие условия фильтрации. См. также Описание полей заявки.
Полная документация к методу в формате swagger (TaskList API)

Описание полей заявки
Копировать ссылку на статью

Задача

Понять какие поля есть у заявки, что они означают для использования в API.

Полная документация по API (swagger)

Решение

"id": 4702781, // Служебное. Общий идентификатор заявки
"tasknumber": 31, // номер заявки
"customerid": 19359, // Служебное. идентификатор “катомера»
"status": 120570, // ID Статуса.
// Можно посмотреть в разделе Настройки->Справочники->Статусы
"priority": 75708, //ID Приоритета.
// Можно посмотреть в разделе Настройки->Справочники->Приоритеты
"name": "Проблемы с принтером", //Название заявки
"description": “Зажевал бумагу», //Описание
"initiator", //Заявитель (инициатор заявки).

При создании и изменении (POST, PUT) можно указать одно из трех:

1) Пользователя-Сотрудника
"initiator": "{\"value\":{\"userid\":109747}}"
2) Клиента
"initiator": "{\"value\":{\"groupid\":109747}}"
3) Клиента и пользователя клиента одновременно
"initiator": "{\"value\":{\"groupid\":109747,\"userid\":31974}}"
При получении (GET) возвращается всегда либо Пользователь-сотрудник, либо Пользователь клиента.

"initiatorclient", // Клиент заявитель.
Только для получения данных. Возвращается Клиент. Для изменения см. поле initiator
"executor",: //Исполнители по заявки.

При создании и изменении (POST, PUT) можно указать одно из трех:
1) Пользователя-Сотрудника
"executor": "{\"value\":{\"userid\":109747}}"
2) Группу сотрудников
"executor": "{\"value\":{\"groupid\":109747}}"
3) Одновременно группу и сотрудника, входящего в эту группу
"executor": "{\"value\":{\"groupid\":109747,\"userid\":31974}}"
При получении (GET) возвращается всегда либо Пользователь-сотрудник, либо Пользователь клиента.

"executorgroup" // Группа исполнителей.
Только для получения данных. Возвращается группа исполнителей

"creator": 583427, //ID пользователя, создавшего заявку. Заполняется всегда автоматически. Может отличаться от Заявителя (инициатора). Например, если на форме создания заявки изменить поле «Заявитель» (По звонку оператор выставляет Заявителем, того кто звонит),

"createdby": "Супервизор участка №15 ", //имя пользователя, создавшего заявку, только чтение.

"createdat": "2021-03-17T09:04:31.1095880Z", //дата создания заявки, только чтение

"updatedat": "2021-04-09T13:16:40.8114620Z", //дата последнего изменения заявки, только чтение
"updatedby": "Супервизор участка №15 ", //имя последнего изменившего заявку пользователя, только чтение

"service": 115438, // ID cервиса к которому относится заявка. Заявка может быть только в одном сервисе. В ответе (метод GET) возвращается идентификатор сервиса. Для методов POST и PUT (создание и изменение заявки) надо передавать не ID, а путь к сервису, см. Настройки->Сервисы, поле «Путь сервиса» на карточке сервиса. См. пример Изменения заявки

"servicename": "Орг.техника", //имя сервиса, в котором создана заявка, только чтение

"tasktype": 36283, // идентификатор типа заявки

// Можно посмотреть в разделе Настройки->Заявки->Типы заявок

"evaluation": "{\"value\":{\"value\":3,\"text\":\"Удовлетворительно\"}}", //оценка заявки. Поле "Value" содержит объект с двумя полями, "Value", хранящий числовое значение оценки и "Text", хранящее текстовое значение оценки. Важно заполнять оба значения*


"clientid": // ID клиента к которому относится заявка.:

В интерфейсах Clientid будет заполняться автоматически значением Initiatorclient (заявитель) если заявку создает пользователь клиента (или сотрудник от имени клиента). Это заявка от клиента.
Если заявка создается на карточки клиента и заявителем выступает сотрудник, то Clientid будет соответствовать данному клиенту (а не заявителю). Это заявка по клиенту одного сотрудника другому.

"resolutiondateplan": // Плановое время решения. Пример «2021-03-17T09:04:00.0000000Z» //Дата. В формате IOS8601 “yyyy-MM-ddTHH:mm:ss.fffffffzzz” (UTC+0). Плановое время решения (срок выполнения заявки). Может быть задано на форме вручную, а может быть автоматически рассчитана на основе настроенного SLA.
см. пример Изменения заявки

"resolutiondatefact": // Фактическое время решения. Пример «2021-03-17T09:04:00.0000000Z»
//Дата. Фактическое время решения. Intradesk автоматически заполняет это поле когда заявка переходит в статус с признаком «Выполнено».

"reactiondateplan": // Плановое время реакции. Пример «2021-03-17T09:04:00.0000000Z»
//Дата. плановое время реагирования. Может быть рассчитано на основе SLA.

"reactiondatefact": // Фактическое время реакции. Пример «2021-03-17T09:04:00.0000000Z»
//Дата. Фактическое время решения. Intradesk автоматически заполняет это поле когда Сотрудник в заявке делает первый перевод статуса.

"tags": [ //массив идентификаторов тегов
279504,279508
], см. пример Изменения заявки
"servicepath": "115434/115438/", //полный путь к Сервису

"workflow": 26454, // идентификатор бизнес-процесса

"observerlist": [], //массив идентификаторов пользователей-наблюдателей

"observergrouplist": [], //массив идентификаторов пользовательских групп-наблюдателей

"closedat": "2021-03-17T09:04:00.0000000Z", //дата закрытия, когда заявка была переведена в статус с признаком "Статус конечный"

"notresponsibleexecutors": [], // массив идентификаторов не ответственных пользователей-исполнителей заявки (тех сотрудников, кто ранее был исполнителей на заявке)

"notresponsibleexecutorgroups": [], // массив идентификаторов не ответственных групп-исполнителей заявки (тех групп сотрудников, которые ранее были исполнителями на заявке)

"additionalfields": { //массив данных дополнительных полей заявки

"data": [
{
"alias": "addfield_stoimost", //алиас(псевдоним) доп.поля
"value": { //значения поля в зависимости от его типа
"numericvalue": 35, //если поле числового типа
"boolvalue": null, //если поле булева типа
"datevalue": null, //если поле типа дата
"stringvalue": null, //если поле строкового типа
"liststringvalue": null //если поле содержит несколько значений (выпадающий список)
}
}
],
"count": 1
},

"lifetime": null, //жизненный цикл заявки (не заполняется если в запросе передано excludelifetime=true)

"servicefullname": "Тех. проблемы>Орг.техника", //полное имя сервиса

"isserviceadmin": false, //признак, который указывает, является ли пользователь, от имени которого выполняется запрос, администратором сервиса заявки
"servicesettingadminid": 53035,

"attachments": //сериализованный массив данных о прикрепленных файлах

"createdchannel": строка //канал создания заявки. Например, "web"," api", "ios" и т.д..

"assets": {"value":[55,60]} //объект, содержащий массив идентификаторов активов


"[{\"Id\":\"611394333b320b000188066b\",\"Name\":\"page.html\",\"ContentType\":\"text/html\",\"Size\":1352,\"Target\":20,\"UploadedAt\":\"2021-08-11T09:11:15.9360000Z\",\"UploadedBy\":\"Супервизор участка №15 \"}]",

"weight": 0,
"filledfieldslist": null, //Служебное
"isreactionexpired": false, //признак того, что время реакции превышено
"isresolutionexpired": false, //признак того, что время решения превышено
"_searchhighlights": null, // Служебное, не используется.
"sla": null, // идентификатор SLA, см. Настройки->Справочники->SLA
"resolutionleftminutes": null, //оставшееся на выполнение время
"tasknumberpath": "31/", //путь номеров заявок в дереве (включая родительские заявки)
"taskbranchid": "ba8bc1cb-95f3-4d12-9829-66622ea57f1c", // идентификатор дерева заявок, заполнен только у заявок, которые являются частью дерева заявок, являются дочерней или родительской заявкой
"taskexpenses": null, //трудозатраты
"isvisited": false, //признак того, просмотрена ли заявка пользователем, от имени которого выполняется запрос
"isvisitedother": true, // Служебное
"privateattachments": "[]" //скрытые приложенные файлы

Описание фильтров заявки
Копировать ссылку на статью
Полная документация по API (swagger)

Для фильтрации списка заявок нужно использовать формат OData условий в параметре "$filter".

Доступны следующие возможности фильтрации по полям:

Сервис
- один из. Odata формат = (servicepath eq '{servicepathstring1}' or servicepath eq {servicepathstring2}' or .... or servicepath eq '{servicepathstringN}')
- кроме. Odata формат = (servicepath ne '{servicepathstring1}' and servicepath ne {servicepathstring2}' and .... and servicepath ne '{servicepathstringN}')

Тип заявки
- один из. Odata формат = (tasktype eq {id1} or tasktype eq {id2} or ....or tasktype eq {idN})
- кроме. Odata формат = (tasktype ne {id1} and tasktype ne {id2} and ....and tasktype ne {idN})

Заявитель
- один из. Odata формат = как тип заявки, только поле initiator
- кроме. Odata формат = как тип заявки, только поле initiator

Исполнитель
- один из. Odata формат = как тип заявки, только поле executor
- кроме. Odata формат = как тип заявки, только поле executor
- задан. Odata формат = (contains('_isfilled','executor'))
- не задан. Odata формат = (contains('_isnotfilled','executor'))

Группы исполнителей
- один из. Odata формат = как тип заявки, только поле executorgroup
- кроме. Odata формат = как тип заявки, только поле executorgroup
- задан. Odata формат = (contains('_isfilled','executorgroup'))
- не задан. Odata формат = (contains('_isnotfilled','executorgroup'))

Компания заявителя
- один из. Odata формат = как тип заявки, только поле initiatorgroup
- кроме. Odata формат = как тип заявки, только поле initiatorgroup

Наблюдатели (поиск по людям)
- один из. Odata формат = (observerlist/any(s: s eq {id1}) or observerlist/any(s: s eq {id2}) or .... observerlist/any(s: s eq {idN}))
- кроме. Odata формат = (observerlist/any(s: s ne {id1}) and observerlist/any(s: s ne {id2}) and .... observerlist/any(s: s ne {idN}))
- задан. Odata формат = (contains('_isfilled','observerlist'))
- не задан. Odata формат = (contains('_isnotfilled','observerlist'))

Название
- задан. Odata формат = (contains('_isfilled','name'))
- не задан. Odata формат = (contains('_isnotfilled','name'))

Описание
- задан. Odata формат = (contains('_isfilled','description'))
- не задан. Odata формат = (contains('_isnotfilled','description'))

Приоритет
- больше равно. Odata формат = (priority ge id1)
- меньше равно. Odata формат = (priority le id1)
- один из. Odata формат = (priority eq {id1} or priority eq {id2} or ....or priority eq {idN})
- кроме. Odata формат = (priority ne {id1} and priority ne {id2} and ....and priority ne {idN})

даты, примеры условий -
1) между: (({datefield} ge cast('{2019-11-01T21:00:00.000Z}', Edm.DateTimeOffset)) and ({datefield} le cast('{2019-12-01T21:00:00.000Z}', Edm.DateTimeOffset)))
2) равно - (({datefield} ge cast('{2019-12-01T21:00:00.000Z}', Edm.DateTimeOffset))
даты нужно указывать в формате iso - 2019-12-01T21:00:00.000Z

Статус
- один из. Odata формат = как тип заявки, только поле status
- кроме. Odata формат = как тип заявки, только поле status

Тег
- содержит любой из. Odata формат = (tags/any(s: s eq 3) or tags/any(s: s eq 7))
- не содержит любой из. Odata формат = (tags/any(s: s ne 3) or tags/any(s: s ne 7))
- содержат все из. Odata формат = (tags/any(s: s eq 3) and tags/any(s: s eq 7))
- не содержат все из. Odata формат = (tags/any(s: s ne 3) and tags/any(s: s ne 7))
- задан. Odata формат = (contains('_isfilled','tags'))
- не задан. Odata формат = (contains('_isnotfilled','tags'))

Вложения
- задан. Odata формат = (contains('_isfilled','attachments'))
- не задан. Odata формат = (contains('_isnotfilled','attachments'))

Доп. поле, дата - все как для дат, {datefield} - alias поля
- задан. Odata формат = (contains('_isfilled','alias_доп_поля'))
- не задан. Odata формат = (contains('_isnotfilled','alias_доп_поля'))

Доп. поле, многострочное поле (текст)
- задан. Odata формат = (contains('_isfilled','alias_доп_поля'))
- не задан. Odata формат = (contains('_isnotfilled','alias_доп_поля'))

Доп. поле, строка
- задан. Odata формат = (contains('_isfilled','alias_доп_поля'))
- не задан. Odata формат = (contains('_isnotfilled','alias_доп_поля'))

Доп. поле, Файл
- задан. Odata формат = (contains('_isfilled','alias_доп_поля'))
- не задан. Odata формат = (contains('_isnotfilled','alias_доп_поля'))

Доп. поле, чекбокс (да/нет)
- установлен. Odata формат = ({additionalFieldAlias} eq true)
- не установлен. Odata формат = ({additionalFieldAlias} eq false) - но это может быть не совсем верное условие, не учитывает Null

Доп. поле, число
- равно. Odata формат = {additionalFieldAlias} eq {numberValue}
- меньше или равно. Odata формат = {additionalFieldAlias} le {numberValue}
- больше или равно. Odata формат = {additionalFieldAlias} ge {numberValue}
- между. Odata формат = {additionalFieldAlias} eq {numberValue}
- задан. Odata формат = (contains('_isfilled','alias_доп_поля'))
- не задан. Odata формат = (contains('_isnotfilled','alias_доп_поля'))

Номер заявки
- между (интервал). Odata формат = (tasknumber ge {number1} and tasknumber le {number2})
- равно. Odata формат = tasknumber eq {number}

Sla
- один из - Odata = sla eq id1 or sla eq id2 or....or sla eq idN
- кроме - Odata = sla ne id1 and sla ne id2 and....and sla ne idN
- задан. Odata формат = (contains('_isfilled','sla'))
- не задан. Odata формат = (contains('_isnotfilled','sla'))

Канал создания
- любое из - Odata = createdchannel eq val1 or createdchannel eq val2 or...or createdchannel eq valN
- задан. Odata формат = (contains('_isfilled','createdchannel'))
- не задан. Odata формат = (contains('_isnotfilled','createdchannel'))

См. также Описание полей заявки, Получение списка заявок

Получение карточки заявки
Копировать ссылку на статью

Задача

Получить данные заявки c номером 31.

Полная документация по API (swagger)

Решение

Get запрос будет вида:
https://apigw.intradesk.ru/tasklist/odata/tasks?ApiKey=65247DBDE14C45A6A275DC1FC0&$filter=tasknumber eq 31

См. также Описание полей заявки.
Получить данные по заявке (или по заявкам) со всей основной информацией можно не только по номеру, но у путём фильтрации списка заявок. См пример Получение списка заявок.
Полная документация к методу в формате swagger (TaskList API)

Получение списка сервисов для создания заявки
Копировать ссылку на статью

Задача

Получим список сервисов.

Полная документация по API (swagger)

Решение

POST https://apigw.intradesk.ru/rules/api/rules?ApiKey=65247DBDE14C45A6A275DC1FC0

Тело запроса:


{
    "chainName":"ShowServiceListChainV2"
}

Ответ сервера:


{
    "r_servicelist":
{        "services":[	//массив сервисов
            {
                "id":4380,	// идентификатор сервиса
                "name":"IntraDesk",	//имя сервиса
                "fullname":"IntraDesk", 	//полное имя сервиса, включая родительские сервисы
                "description":null,	//описание сервиса
                "path":"4380/",		//путь сервиса, включая родительские сервисы
                "parentid":null,	//идентификатор родительского сервиса, если таковой существует
                "tasktypes":[	//идентификаторы типов заявок используемые в данном сервисе
                ],
                "sortorder":"03",	//значение для сортировки на списке сервисов
                "adminsettingid":1236,	//идентификатор настроек администратора
                "denied":true,
                "isarchived":false	//признак того, является ли сервис удаленным(в архиве)
            },
            {
                "id":4349,
                "name":"Поддержка",
                "fullname":"IntraDesk > Поддержка",
                "description":null,
                "path":"4380/4349/",
                "parentid":4380,
                "tasktypes":[
                    57
                ],
                "sortorder":"03/001",
                "adminsettingid":1236,
                "denied":false,
                "isarchived":false
            }
        ],
        "tasktypes":[		//массив типов заявок
            {
                "id":55,	//идентификатор типа завки
                "name":"Бронирование переговорных"	//название
            },
            {
                "id":57,
                "name":"Заявка"
            }
        ]
    }
}

Сервисы имеют древовидную структуру, каждый сервис имеет поле "path", в котором через "/" указаны id всех родительских сервисов этого сервиса.
Создание заявок доступно только в "конечных сервисах", в тех, которые не имеют дочерних сервисов.
Для каждого сервиса в поле "tasktypes" указаны id типов заявок в которых доступно создание заявки.
Полная документация к методу в формате swagger (Rules API)