В данной статье вы найдете примеры популярных API запросов, а также ответы на часто задаваемые вопросы. Напоминаем, API документация находится по адресу https://helpdeskeddy.com/api.html.
1) Пример запроса создания заявки
2) Пример запроса получения заявки и её данных
3) Пример запроса с отправкой файлов при создании заявки/отправке ответа
4) Как получить значение custom_fields конкретного пользователя?
5) Пример записи значения кастомного поля через API
6) Часто задаваемые вопросы (FAQ)
1) Пример запроса в Postman (POST /api/v2/tickets/) на создание заявки от имени пользователя
При успешной отправке запроса вы получите от сервера статус 200.
2) Пример запроса получения заявки и её данных с помощью метода GET /tickets/id:
3) Пример запроса с отправкой файлов при создании заявки/отправки ответа.
Передавать файлы можно стандартным способом через multipart/form-data. Для параметра files (массив файлов) необходимо указывать индекс, например, files[0]:
Аналогичный механизм при работе с методом для добавления ответов или комментариев.
Пример cURL запроса для добавления комментария с файлом:
curl -X POST -H "Authorization: Basic KEY -H "Cache-Control: no-cache" -F "text=Текст комментария" -F files[0]=@"d:\test.jpg" "https://domain.helpdeskeddy.com/api/v2/tickets/12345/comments/"
Для запросов в скриптах на разных языках программирования используются различные библиотеки. Во вложении к статье (вверху страницы) прикладываем примеры PHP для работы с API и передачи файлов.
4) Как получить значение custom_fields конкретного пользователя?
Чтобы получить значения дополнительных полей пользователя, необходимо выполнить запрос на получение пользователя https://адрес_системы/api/v2/users/{id}/ , где {id} - id пользователя. В результате в ответе будет массив полей custom_fields. Пример:
5) Пример записи значения кастомного поля через API
Для метода "Обновить заявку" /tickets/{id} используйте PUT запрос. Для работы с индивидуальными полями заявки передается параметр custom_fields с массивом ID поля => Значение. Например, для JSON и поля с типом "Выпадающий список" в таком формате:
{ "custom_fields": { "3": "2" } }
где 3 - ID индивидуального поля, 2 - ID одного из значений в выпадающем списке.
Соответственно, запрос будет выглядеть следующим образом:
curl -X PUT -H "Authorization: Basic KEY" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{ "custom_fields": { "11": "2" } }' "https://адрес_системы.com/api/v2/tickets/331/"
Часто задаваемые вопросы (FAQ):
В: Какое максимальное количество заявок возвращает метод: "Получить заявки"?
О: Максимальное количеств заявок в методе api/v2/tickets/ неограниченно, но запрос возвращает результат с пагинацией по 30 заявок на странице. Используя информацию о количестве страниц, вы можете автоматизировать процесс и получить необходимое количество заявок.
В: Есть ли ограничения на количество запросов в минуту (RPM)?
О: Ограничение на количество запросов в минуту (RPM) составляет 300 запросов в минуту. В случае превышения лимита доступ будет автоматически заблокирован на 20 минут.
В: Можно ли тянуть отчётность по API?
О: Нет. API, в целом, никакие отчеты/показатели не рассчитывает и не отдаёт. По API можно получить только фактические данные заявки (в т.ч. Аудит), контактов, базы знаний.
Вы можете получать данные и самостоятельно строить необходимую отчетность на своей стороне при помощи соответствующих сервисов (PowerBI, Tableau и т.д.).
В: При отправке запроса получаю ошибку:
{"errors":[{"code":"e-401","title":"Authorization error","details":"Username or api key is incorrect"}]}
О: Ошибка "Username or api key is incorrect" говорит о том, что введены неправильные данные API ключа.
Проверьте, что вы используете (и сохранили) правильные э-почту и пароль API ключа, который можно найти в разделе Управление -> Глобальные настройки -> Система -> API ключ, вот здесь:
API ключ отображается только у главного администратора системы (пользователя с ID 1).
В: При отправке PUT запроса для установки кастомного поля получаю ошибку:
{"errors":[{"code":"e-400","title":"Bad request","details":"Data lost"}]}
О: Для иерархии необходимо указывать значение на каждом уровне. Например:
{
"custom_fields": {
"78": {
"1":"146",
"2":"148",
"3":"149"
}
}
}
Пример связанных полей в системе:
Пример запроса в Postman:
где:
78 - ID кастом поля
1,2,3 - уровень 1, уровень 2, уровень 3.
146 - значение уровня 1
148 - значение уровня 2
149 - значение уровня 3
В: Можно ли работать с Оборудованием при помощи API?
О: На текущий момент такой возможности нет.
В: Происходит ли отправка письма-уведомления клиенту при отправке ответа в заявке при помощи API?
О: Нет, в этом случае добавится только ответ, письмо отправлено не будет. Для этого вы можете воспользоваться "Диспетчером" и настроить правила для отправки письма, привязав их к новому ответу в заявке. Пример:
Не забудьте указать в теме письма уникальный ID заявки в нужно формате (как на скриншоте), чтобы при ответе клиента на письмо, его ответ попадал в нужную заявку, а не создавал новую. Для тела письма Вы можете использовать код, взятый из стандартного шаблона уведомлений.