Категории

Список запросов

Общие моменты

POST https://api.usedesk.ru/tickets

Внимание. Если вы используете коробочную версию Юздеска на собственном сервере, URL методов у вас будет отличаться. Уточните URL для работы с API у поддержки — support@usedesk.ru.

Метод возвращает запросы, удовлетворяющие заданным условиям фильтров.

В методе реализована постраничная разбивка. В ответе максимум 100 записей, для смещения используется параметр offset.

* — обязательные поля

Параметры для работы с запросом

Параметр Тип данных Описание
api_token* varchar(255) Токен API канала
fchannel varchar(255)

Фильтрация по id канала.

Можно передать несколько значений через запятую
fassigned array

Фильтрация по assignee_id (id исполнителя) и group_id (id группы агентов).

Можно передать как по одному, так и массивом.

Возможные варианты использования:

  1. Указано только значение assignee_id
    Система отдаст все запросы, в которых в качестве Исполнителя указан агент, без учёта в рамках какой группы он добавлен.
  2. Указаны assignee_id и group_id
    Система отдаст все запросы, в которых в качестве Исполнителя указан агент в рамках определенной группы.
  3. Указано значение assignee_id = unassigned
    Система отдаст все запросы, в которых в качестве Исполнителя указана группа.
  4. Указано значение assignee_id = unassigned и group_id = unassigned
    Cистема отдаcт все запросы, в которых в качестве Исполнителя указано «Нет исполнителя»
fgroup varchar(255) Фильтрация по id группы
Можно передать несколько значений через запятую
fstatus varchar(255)

Фильтрация по id статуса

  • 1 (открыт)
  • 2 (выполнен)
  • 3 (закрыт)
  • 4 (удален)
  • 5 (на удержании)
  • 6 (в ожидании)
  • 7 (спам)
  • 8 (новый)
  • 9 (рассылка)
  • 10 (объединен)

Можно передать несколько значений через запятую
ftype

varchar(255)

Фильтрация по типу

  • question — вопрос
  • task — задача
  • problem — проблема
  • incident — инцидент

Можно передать несколько значений через запятую
fpriority varchar(255)

Фильтрация по приоритету

  • low — низкий
  • medium — средний
  • urgent — высокий
  • extreme — экстремальный

Можно передать несколько значений через запятую
accessible_for_agent_id integer

Фильтрация по id агента

Учитывает права сотрудника. Не принимает значение null. Сервер возвращает переменную rights:

  • write — если есть доступ работы с запросом в текущем канале;
  • read — если есть доступ просмотра запроса в текущем канале.
offset integer Смещение.

Не принимает значение null.

Смещение на 1 покажет следующие 100 записей
tag varchar(255)

Фильтрация по значению тега.

Можно передать несколько значений через запятую с пробелом. Не принимает значение null.

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

"tag": "тег1, тег2, тег3"
created_after timestamp

Фильтрация по дате и времени создания

В выдачу попадут запросы, созданные после указанной даты (включительно)

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

"created_after": "2022-01-01 00:00"

Важно! Наше API работает по нулевому часовому поясу (UTC+0) и не зависит от времени работы компании. Учитывайте это при создании фильтра.
created_before timestamp

Фильтрация по дате и времени создания

В выдачу попадут запросы, созданные до указанной даты (включительно)

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

"created_before": "2022-12-31 23:59"

Важно! Наше API работает по нулевому часовому поясу (UTC+0) и не зависит от времени работы компании. Учитывайте это при создании фильтра.
updated_after timestamp

Фильтрация по дате и времени изменения

В выдачу попадут запросы, измененные после указанной даты (включительно)

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

"updated_after": "2022-01-01 00:00"

Важно! Наше API работает по нулевому часовому поясу (UTC+0) и не зависит от времени работы компании. Учитывайте это при создании фильтра.
updated_before timestamp

Фильтрация по дате и времени изменения

В выдачу попадут запросы, измененные до указанной даты (включительно)

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

"updated_before": "2022-01-01 00:00"

Важно! Наше API работает по нулевому часовому поясу (UTC+0) и не зависит от времени работы компании. Учитывайте это при создании фильтра.
query varchar(255)

Поиск запросов по теме, значению дополнительного поля, почте и телефону клиента

Не принимает значение null

Для запросов, содержащих данный параметр установлено ограничение на 10 запросов в минуту
client_id integer Фильтрация по id клиента
fields array

Фильтрация по идентификатору и значению дополнительного поля

Массив содержит параметры:

  • id — айди дополнительного поля;
  • value — значение дополнительного поля

Дополнительные варианты использования:

а) empty — при указании данного значения система отфильтрует все запросы, в которых есть хотя бы одно не заполненное поле. Для полей с типом checkbox «не заполнено» — это значение «0» или пустое значение « »

b) not_empty — при указании данного значения система отфильтрует все запросы, в которых есть хотя бы одно заполненное поле. Для полей с типом checkbox «заполнено» — это значение «1»

c) value — при указании значения система отфильтрует все запросы, в которых в любом из дополнительных полей будет выбрано данное значение. Можно указать только одно значение
sort

varchar(255)

Идентификатор поля для сортировки

Параметры, по которым можно сортировать список запросов:

  • id,
  • status_id,
  • client_id,
  • assignee_id,
  • group,
  • last_updated_at,
  • published_at
По умолчанию: id
order

varchar(255)

Порядок сортировки запросов:

  • asc — по возрастанию
  • desc — по убыванию

По умолчанию: desc

properties

 array[varchar(255)]

Передача времени до наступления SLA

"properties": ["sla"]

Возможные параметры в ответе:

  • first_reply — время первого ответа;
  • next_reply — время следующего ответа;
  • close — время до выполнения.

Если SLA не заданы в запросе, то SLA не возвращается в ответе

Пример применения фильтров

{
    'fchannel':'123',
    'properties': ["sla"]
    'fassigned': 
    [
       {
            'assignee_id' : 17063,
            'group_id' : 6216
       },
       {
            'assignee_id' : 15023,
            'group_id' : 8294
       } 
    ]
    'fields': 
    [
        {'id': 4704,
         'value": 1
        },
        {'id': 2410,
         'value": 'empty'
        },
        {'id': 3570,
         'value": 'test'
        },
        {'id': 4267,
         'value': 'empty'
        }
    ] 
    'fgroup': '21',
    'ftype':'1',
    'accessible_for_agent_id':'6339',
    'updated_after':'2016-11-25 00:00'
}

Пример запроса на php

$data = array(
        'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
        'offset'=>0,
        'created_after' =>'2016-11-25 00:00',
        'created_before'=>'2016-11-25 15:08',
);
$mch_api = curl_init(); // initialize cURL connection
curl_setopt($mch_api, CURLOPT_URL, 'https://api.usedesk.ru/tickets');
curl_setopt($mch_api, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
curl_setopt($mch_api, CURLOPT_POST, true);
curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);
$result = curl_exec($mch_api); 
return $result;

Пример запроса c фильтрами на php

$data = array(
        'api_token'=> 'e1cbe1c1c9d910ef2ae975215644cb53dd555de4',
        'offset'=>0
        'tags'=> 'тег1,тег2',
        'fchannel'=>'123',
        'fgroup'=>'2'
);
$mch_api = curl_init();
curl_setopt($mch_api, CURLOPT_URL, 'https://api.usedesk.ru/tickets');
curl_setopt($mch_api, CURLOPT_USERAGENT, 'PHP-MCAPI/2.0');
curl_setopt($mch_api, CURLOPT_RETURNTRANSFER, true);
curl_setopt($mch_api, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($mch_api, CURLOPT_TIMEOUT, 10);
curl_setopt($mch_api, CURLOPT_POST, true);
curl_setopt($mch_api, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($mch_api, CURLOPT_POSTFIELDS, $data);
$result = curl_exec($mch_api);
return $result;

Пример ответа от сервера

[
    {
        "id": 2992803,
        "subject": "привет",
        "client_id": 15341,
        "client_name": "Лащук Василий",
        "assignee_id": 2,
        "channel_id": null,
        "group": 2,
        "created_at": "2021-04-29 11:31:23"
        "last_updated_at": "2021-04-29 12:47:30",
        "channel_email": null,
        "active_sla": [
            {
            "type": "close",
            "date": "2021-04-29 13:35:04"
            },
            {
            "type": "first_reply",
            "date": "2021-04-29 18:01:08"
            }
        ],
            "ticket_fields": [
            {
                "id": 25,
                "name": "Жалоба",
                "value": null
            },
              {
                "id": 37,
                "name": "Причина обращений",
                "value": "39"
            }
        ],
        "tags": [
            {
                "name": "Важный"
            },
            {
                "name": "Холодный"
            }
        ],
        "status": 2,
        "priority": "medium",
        "type": "question",
        "last_comment": "У меня появилась ошибка",
        "remind_at": null,
        "rights": "read"
    },
]

Параметры ответа от сервера

ПараметрЗначение
idID запроса
subjectТема запроса
client_idID клиента
client_nameИмя клиента
assignee_idID ответственного агента
channel_idID канала
groupID группы
created_atДата и время создания запроса


Часовая зона UTC+0

last_updated_atДата и время последнего обновления запроса


Часовая зона UTC+0

channel_emailEmail канала


Указан, если запрос создан в канале соответствующего типа

active_slaМассив текущих SLA у запроса
  • type — тип
    • close — SLA до закрытия
    • first_reply — SLA первого ответа
  • date — Дата и время истечения SLA
ticket_fieldsМассив со значениями дополнительных полей в запросе
  • id — id дополнительного поля;
  • name — название дополнительного поля;
  • value — значение дополнительного поля
tagsМассив тегов
  • name — значение тега
statusСтатус запроса
priorityПриоритет запроса
typeТип запроса
last_commentПоследний комментарий в запросе
remind_atДата и время напоминания
rightsПрава указанного сотрудника
  • write — если есть доступ работы с запросом в текущем канале;
  • read — если есть доступ просмотра запроса в текущем канале.