API: примеры запросов, дополнительная информация

В данной статье вы найдете примеры популярных 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 заявки в нужно формате (как на скриншоте), чтобы при ответе клиента на письмо, его ответ попадал в нужную заявку, а не создавал новую. Для тела письма Вы можете использовать код, взятый из стандартного шаблона уведомлений.

Пример метода 'Получить заявки' с помощью GuzzleHttp.txt
Предпросмотр Загрузить
curl пример для создания заявки с файлом.txt
Предпросмотр Загрузить
php-api-post-clear.php
Загрузить