REST API модуля «Helpdesk»

Справочник REST-методов модуля ithive.helpdesk для интеграций, входящих вебхуков и AI-агентов.

Базовый URL

https://{портал}/rest/{user_id}/{webhook_code}/{method}.json

Пример:

https://76575.dev.wehive.digital/rest/1/lus1tijk9ll7mg7h/helpdesk.ticket.list.json

Scope и аутентификация

  • Scope: helpdesk
  • Аутентификация: входящий вебхук Bitrix24 или OAuth/сессия авторизованного пользователя
  • Все методы helpdesk.* требуют авторизованного пользователя REST. Без авторизации — UNAUTHORIZED.
  • Отдельного метода helpdesk.schema в текущем коде нет.

Авторизация ≠ право на операцию: вебхук даёт доступ к scope, но каждый метод дополнительно проверяет роли техподдержки Bitrix (CTicket::IsAdmin, IsSupportTeam, IsResponsible) и ACL обращений (TicketAccessHelper).

Права доступа

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

Сводка по группам методов

Группа методов Кто может (как в коде)
ticket.list, get, search, getMy, getOverdue Авторизованный; списки фильтруются по ACL (не админ видит только «свои» обращения, категории группы, наблюдение)
ticket.add Авторизованный (создание через CAllTicketHelpdesk::SetTicket)
ticket.update, close, reopen Автор / ответственный / команда поддержки; наблюдатели не могут (FORBIDDEN / PERMISSION_DENIED)
ticket.delete Только админ техподдержки (CTicket::IsAdmin)
ticket.assign Админ / команда поддержки / текущий ответственный / потенциальный ответственный по категории
message.* Доступ к обращению; скрытые сообщения — admin/support/responsible; изменение — автор сообщения / admin / support
observer.* Просмотр — доступ к обращению; add/delete — admin, ответственный; автор может управлять только собой как наблюдателем
category.list, get Любой авторизованный
category.add, update, delete Админ портала (UserService::isAdmin) или админ техподдержки
category.responsible.list Admin / support team
enum.*.list Любой авторизованный

Формат ответа

Внутренний конверт модуля попадает в result обёртки Bitrix REST:

Поле (внутри result) Описание
result Данные или null при ошибке
error null или { code, message, details }

Для list-методов с пагинацией Bitrix выносит служебные поля на верхний уровень HTTP-ответа (рядом с result / time):

Поле (верхний уровень) Описание
total Общее число записей
next Смещение следующей страницы. Ключ есть только если есть ещё данные (offset + count < total). На последней странице, при пустом списке и при fetchAll=true ключ next отсутствует (модуль не отдаёт next: null)

Пример (есть следующая страница, limit=2, total=11):

{
          "result": {
            "result": [ /* … */ ],
            "error": null
          },
          "total": 11,
          "next": 2
        }

Пример (последняя / единственная страница — без next):

{
          "result": {
            "result": [ /* … */ ],
            "error": null
          },
          "total": 1
        }

Методы enum.*.list пагинацию не используют: только массив в result.result и total (без next).

Пагинация

Для list-методов:

Параметр По умолчанию Описание
limit 50 Размер страницы, максимум 500
offset 0 Смещение
fetchAll false Вернуть все записи одним ответом. Защитный лимит 5000; при превышении — FETCHALL_LIMIT_EXCEEDED
filter — Mongo-style фильтр ($eq, $in, $gte, …)

Приоритет и критичность

В REST-полях priority и criticalityId эквивалентны — оба мапятся на CRITICALITY_ID справочника (C_TYPE = K). В ответах API возвращаются оба ключа с одинаковым значением.

Пакетные вызовы

Отдельного метода helpdesk.batch нет. Несколько helpdesk.* за один HTTP-запрос — штатный batch Битрикс24 (/rest/{user_id}/{webhook_code}/batch.json).

Разделы справочника

Раздел Описание
Обращения ticket.* — 11 методов
Сообщения message.* — 5 методов
Наблюдатели observer.* — 3 метода
Категории category.* — 6 методов
Справочники enum.* — 4 метода
Коды ошибок Полный перечень

Всего методов в текущем коде: 29.

Предыдущая
Установка, обновление и удаление модуля
Следующая
Коды ошибок