API эндпоинты — help-backend

Документация по REST API сервиса технической поддержки.

Общая информация

• Базовый префикс: /help (задаётся через app.setGlobalPrefix('help') в src/main.ts)
• Swagger UI: /api
• Полный путь к любому эндпоинту: http://<host>:<HELP_BACKEND_PORT>/help/<route>
• CORS: включён для всех источников

Заголовки аутентификации

Идентификация пользователя выполняется через HTTP-заголовки (не через JWT). Константы определены в src/request/request.constant.ts:

Заголовок	Назначение
X-TS-USER	ID текущего пользователя
X-TS-SYSTEM	Код системы (организации), к которой относится запрос

Ниже у каждого эндпоинта указано, какие заголовки он использует.

---

1. App (/)

src/app.controller.ts

Метод	Путь	Описание
GET	/help	Hello-эндпоинт (smoke-проверка)

---

2. Health (/health)

src/health/health.controller.ts

Метод	Путь	Описание
GET	/help/health	Проверка работоспособности (MongoDB + RabbitMQ через Terminus)

---

3. Debug (/debug)

src/debug/debug.controller.ts

Метод	Путь	Описание
GET	/help/debug/memory	Статистика по памяти процесса и V8 heap
GET	/help/debug/heap-snapshot	Снимок V8 heap (.heapsnapshot), отдаётся как файл

---

4. User (/user)

src/user/controller/user.controller.ts

Метод	Путь	Headers	Body	Описание
POST	/help/user	—	CreateTechSupportUserDto	Создать нового пользователя
POST	/help/user/:id/check	—	UpdateTechSupportUserDto	Проверить пользователя по id и обновить, если данные отличаются
POST	/help/user/:id	—	UpdateTechSupportUserDto	Обновить пользователя
DELETE	/help/user/:id	—	—	Удалить пользователя
GET	/help/user/all	—	—	Список всех пользователей
GET	/help/user/current-user	X-TS-USER	—	Реквизиты текущего пользователя
GET	/help/user/settings/:type	X-TS-USER	—	Получить настройки пользователя по типу
POST	/help/user/settings/:type	X-TS-USER	TechSupportUserCommandDto	Сохранить настройки пользователя по типу
GET	/help/user/from-external-system/:systemCode	—	—	Список пользователей из внешней системы
GET	/help/user/:id	—	—	Получить пользователя по id

---

5. System (/system)

src/system/controller/system.controller.ts

Метод	Путь	Body	Описание
POST	/help/system	CreateTechSupportSystemDto	Создать систему
POST	/help/system/:id	UpdateTechSupportSystemDto	Обновить систему
DELETE	/help/system/:id	—	Удалить систему
GET	/help/system/all	—	Получить список всех систем

---

6. Status (/status)

src/status/controller/status.controller.ts

:code — текстовый код статуса (например, OPENED).

Метод	Путь	Body	Описание
POST	/help/status	CreateTechSupportStatusDto	Создать статус
POST	/help/status/:code	UpdateTechSupportStatusDto	Обновить статус
DELETE	/help/status/:code	—	Удалить статус
GET	/help/status/all	—	Список всех статусов

---

7. Status Relation (/status-relation)

src/status-relation/controller/status-relation.controller.ts

Описывает разрешённые переходы между статусами заявок.

Метод	Путь	Body	Описание
POST	/help/status-relation	CreateTechSupportStatusRelationDto[]	Массовое создание переходов
POST	/help/status-relation/:id	UpdateTechSupportStatusRelationDto	Обновить переход
DELETE	/help/status-relation/:id	—	Удалить переход
GET	/help/status-relation/all	—	Список всех переходов

---

8. Request Type (/request-type)

src/request-type/controller/request-type.controller.ts

Категории (типы) обращений в ТП.

Метод	Путь	Body	Описание
GET	/help/request-type	—	Список всех типов
GET	/help/request-type/:id	—	Получить тип по id
POST	/help/request-type	CreateRequestTypeDto	Создать тип
PATCH	/help/request-type/:id	TechSupportRequestTypeResponseDto	Обновить тип
DELETE	/help/request-type/:id	—	Удалить тип (204)

---

9. Request Priority (/request-priority)

src/request-priority/controller/request-priority.controller.ts

Приоритеты заявок.

Метод	Путь	Body	Описание
GET	/help/request-priority	—	Список приоритетов
GET	/help/request-priority/:id	—	Получить приоритет по id
POST	/help/request-priority	CreateRequestPriorityDto	Создать приоритет
PATCH	/help/request-priority/:id	UpdateRequestPriorityDto	Обновить приоритет
DELETE	/help/request-priority/:id	—	Удалить приоритет (204)

---

10. Service / Task (/task)

src/task/controller/task.controller.ts

Услуга — это справочник значений, которые можно привязать к заявке через поле task.

Метод	Путь	Body	Описание
GET	/help/task	—	Список услуг
GET	/help/task/:id	—	Получить услугу по id
POST	/help/task	CreateTaskDto	Создать услугу
PATCH	/help/task/:id	UpdateTaskDto	Обновить услугу
DELETE	/help/task/:id	—	Удалить услугу (204)

Формат услуги:

Поле	Тип	Описание
_id	string	Id услуги
code	string	Код услуги
description	string	Наименование / описание услуги
system	string	Код системы, в рамках которой доступна услуга

Пример услуги:

{
  "_id": "682eeb7f1f2a8f6b1c123456",
  "code": "CLIENT_CARD",
  "description": "Работа с карточкой клиента",
  "system": "CRM"
}

Связь услуги и заявки:

• При создании и редактировании заявки в поле task передаётся code услуги.
• Услуга выбирается в рамках системы system.
• Для одной заявки передаётся одна услуга.
• В ответе по заявке услуга возвращается полями task и taskText.

---

11. Request (/request) — основной домен

src/request/controller/request.controller.ts

Тикеты ТП: списки, фильтры, комментарии, статусы, линии поддержки и исполнители. Большинство методов читают X-TS-USER и часть — X-TS-SYSTEM.

Списки и агрегаты

Метод	Путь	Headers	Body	Описание
POST	/help/request/all	X-TS-USER, X-TS-SYSTEM	PaginatedParams	Пагинированный список заявок по роли пользователя
POST	/help/request/fieldValues/:field	X-TS-USER, X-TS-SYSTEM	FiltratedParams	Получить уникальные значения поля :field с учётом фильтров
GET	/help/request/history-count	X-TS-USER, X-TS-SYSTEM	—	Количество непрочитанных сообщений истории
GET	/help/request/read-all-history	X-TS-USER, X-TS-SYSTEM	—	Пометить всю историю пользователя прочитанной (204)
POST	/help/request/overdue	X-TS-USER	—	Запустить проверку просроченных заявок (204)

CRUD заявки

Метод	Путь	Headers	Body	Описание
POST	/help/request	X-TS-USER, X-TS-SYSTEM	multipart/form-data + CreateTechSupportRequestDto	Создать заявку (с вложениями)
POST	/help/request/:id	X-TS-USER	multipart/form-data + UpdateTechSupportRequestDto	Обновить заявку (с вложениями)
DELETE	/help/request/:id	X-TS-USER	—	Удалить заявку
GET	/help/request/:id	X-TS-USER	—	Получить заявку по id

Комментарии

Метод	Путь	Headers	Body	Описание
POST	/help/request/:id/comment	X-TS-USER	multipart/form-data + CreateTechSupportCommentDto	Добавить комментарий (с вложениями)
POST	/help/request/:id/comment/:commentId	X-TS-USER	multipart/form-data + UpdateTechSupportCommentDto	Обновить комментарий
DELETE	/help/request/:id/comment/:commentId	X-TS-USER	—	Удалить комментарий

Статус, линия поддержки, исполнитель

Метод	Путь	Headers	Body	Описание
POST	/help/request/:id/changeStatus	X-TS-USER	ChangeStatusTechSupportRequestDto	Изменить статус заявки
POST	/help/request/:id/changeLine	X-TS-USER	ChangeLineTechSupportRequestDto	Изменить линию ТП
GET	/help/request/:id/performer/list	X-TS-USER, X-TS-SYSTEM	—	Список доступных исполнителей текущей линии ТП
POST	/help/request/:id/performer	X-TS-USER	SetSupportLinePerformerTechSupportRequestDto	Назначить исполнителя

Входные и выходные данные по созданию/изменению заявок, статусов, комментариев и файлов

POST /help/request — создание заявки

Контент-тип: multipart/form-data

Поле	Тип	Обязательность	Описание
subject	string	да	Тема заявки
text	string	да	Текст заявки
additionalInfo	Array<{ name: string; value: string }>	нет	Дополнительные поля
user	object | null	нет	Пользователь, от имени которого создаётся заявка
requestType	string	да	Код типа заявки
system	string	нет	Код системы; если не передан, берётся из X-TS-SYSTEM
email	string	нет	Email отправителя
requestPriority	string	нет	Код приоритета; если не передан, используется LOW
task	string	нет	Код услуги из справочника /help/task
files	binary[]	нет	Новые вложения заявки

Перед созданием заявки код услуги рекомендуется получать через GET /help/task.

Услуга в заявке:

Поле	Тип	Описание
task	string	Код услуги (code) из /help/task
связь с системой	string	Услуга должна относиться к той же системе, что и заявка (system)

Поля объекта user:

Поле	Тип	Описание
externalId	string	Идентификатор пользователя во внешней системе
fullName	string	ФИО
companyName	string	Организация
eMail	string[]	Email-адреса
phoneNumber	string[]	Телефоны
telegram	string[]	Telegram id
position	string	Должность
role	string	Роль
fullThumbUrl	string	Ссылка на фото
isAdmin	boolean	Признак администратора
isTechnicalSupportAdmin	boolean	Признак администратора техподдержки
additionalInfo	Array<{ name: string; value: string }>	Дополнительные данные
systems	string[]	Системы пользователя
uniqueIdentifier	string	Уникальный идентификатор
isActive	boolean	Активность пользователя
comment	string	Комментарий

Ответ: полная созданная заявка.

Услуга в ответе:

• Заявка создаётся с привязкой к услуге, переданной в поле task.
• В ответе по заявке возвращаются поля task и taskText.

Пример полей multipart/form-data:

subject=Не открывается карточка клиента
text=При переходе в карточку клиента отображается пустая страница.
requestType=INCIDENT
system=CRM
requestPriority=MEDIUM
task=CLIENT_CARD
additionalInfo=[{"name":"clientId","value":"CL-100245"},{"name":"environment","value":"prod"}]
user={"externalId":"usr-1001","fullName":"Иван Иванов","companyName":"Компания А","eMail":["user@example.com"],"phoneNumber":["+79990000000"],"uniqueIdentifier":"crm_usr_1001"}
files=<binary>

Здесь task=CLIENT_CARD означает привязку заявки к услуге с кодом CLIENT_CARD из справочника /help/task для системы CRM.

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

{
  "id": "682c6d9f5a3e7d1c2b123456",
  "createdAt": "2026-05-20T08:15:10.000Z",
  "updatedAt": "2026-05-20T08:15:10.000Z",
  "code": "000321",
  "subject": "Не открывается карточка клиента",
  "text": "При переходе в карточку клиента отображается пустая страница.",
  "statusCode": "OPENED",
  "statusName": "Заявка создана",
  "authorId": "681111111111111111111111",
  "authorFullName": "Иван Иванов",
  "authorCompanyName": "Компания А",
  "creatorId": null,
  "creatorFullName": null,
  "system": "CRM",
  "systemText": "CRM",
  "supportLineNum": 0,
  "supportLineName": "Первая линия",
  "performer": [],
  "performerFullName": null,
  "requestTypeCode": "INCIDENT",
  "requestTypeName": "Инцидент",
  "task": "CLIENT_CARD",
  "taskText": "Работа с карточкой клиента",
  "requestPriorityCode": "MEDIUM",
  "requestPriorityName": "Средний",
  "additionalInfo": [
    { "name": "clientId", "value": "CL-100245" },
    { "name": "environment", "value": "prod" }
  ],
  "files": [
    {
      "id": "682c6d9f5a3e7d1c2b999001",
      "fullUrl": "https://files.example.com/help/682c6d9f5a3e7d1c2b999001",
      "name": "screenshot.png",
      "mimeType": "image/png",
      "size": 248231
    }
  ],
  "comments": [],
  "nextStatuses": [
    {
      "code": "IN_PROGRESS",
      "name": "В работе",
      "text": "Взять в работу",
      "isCommentNeeded": false,
      "params": {}
    }
  ],
  "nextSupportLine": {
    "num": 1,
    "name": "Вторая линия"
  },
  "prevSupportLine": [],
  "trackerId": "HELP-321"
}

POST /help/request/:id — изменение заявки

Контент-тип: multipart/form-data

Поле	Тип	Обязательность	Описание
type	string	да по DTO	Поле есть в DTO, но в текущей реализации не сохраняется
subject	string	да	Новая тема
text	string	да	Новый текст
statusCode	string	да по DTO	Код статуса
additionalInfo	Array<{ name: string; value: string }>	нет	Новые дополнительные поля
files	Array<{ id: string; name: string }>	нет	Файлы заявки, которые нужно оставить после обновления
requestPriority	string	нет	Новый код приоритета
user	object | null	нет	Новый автор заявки
system	string	нет	Новый код системы
task	string	нет	Новый код услуги из справочника /help/task
files (multipart)	binary[]	нет	Новые файлы, которые нужно добавить к заявке

Перед обновлением заявки код услуги рекомендуется получать через GET /help/task.

Услуга в заявке:

Поле	Тип	Описание
task	string	Новый код услуги (code) из /help/task
связь с системой	string	Услуга должна относиться к системе, переданной в поле system

Поля объекта user совпадают с POST /help/request.

Ответ: полная обновлённая заявка.

Услуга в ответе:

• Заявка обновляется с новой привязкой к услуге, переданной в поле task.
• В ответе по заявке возвращаются поля task и taskText.

Пример полей multipart/form-data:

subject=Не открывается карточка клиента в CRM
text=Проблема воспроизводится у нескольких сотрудников.
statusCode=OPENED
system=CRM
requestPriority=HIGH
task=CLIENT_CARD
additionalInfo=[{"name":"clientId","value":"CL-100245"},{"name":"environment","value":"prod"},{"name":"browser","value":"Chrome"}]
files=[{"id":"682c6d9f5a3e7d1c2b999001","name":"screenshot.png"}]
files=<binary>

Здесь task=CLIENT_CARD означает, что после обновления заявка должна быть связана с услугой CLIENT_CARD в системе CRM.

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

{
  "id": "682c6d9f5a3e7d1c2b123456",
  "createdAt": "2026-05-20T08:15:10.000Z",
  "updatedAt": "2026-05-20T08:32:44.000Z",
  "code": "000321",
  "subject": "Не открывается карточка клиента в CRM",
  "text": "Проблема воспроизводится у нескольких сотрудников.",
  "statusCode": "OPENED",
  "statusName": "Заявка создана",
  "system": "CRM",
  "systemText": "CRM",
  "task": "CLIENT_CARD",
  "taskText": "Работа с карточкой клиента",
  "requestPriorityCode": "HIGH",
  "requestPriorityName": "Высокий",
  "additionalInfo": [
    { "name": "clientId", "value": "CL-100245" },
    { "name": "environment", "value": "prod" },
    { "name": "browser", "value": "Chrome" }
  ],
  "files": [
    {
      "id": "682c6d9f5a3e7d1c2b999001",
      "fullUrl": "https://files.example.com/help/682c6d9f5a3e7d1c2b999001",
      "name": "screenshot.png",
      "mimeType": "image/png",
      "size": 248231
    },
    {
      "id": "682c71a15a3e7d1c2b999002",
      "fullUrl": "https://files.example.com/help/682c71a15a3e7d1c2b999002",
      "name": "console-log.txt",
      "mimeType": "text/plain",
      "size": 1462
    }
  ]
}

POST /help/request/:id/changeStatus — изменение статуса заявки

Контент-тип: application/json

Поле	Тип	Обязательность	Описание
statusCode	string	да	Код целевого статуса
commentText	string	условно	Комментарий к смене статуса

Ответ: полная заявка после смены статуса.

Пример запроса:

{
  "statusCode": "IN_PROGRESS",
  "commentText": "Заявка взята в работу, выполняем диагностику."
}

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

{
  "id": "682c6d9f5a3e7d1c2b123456",
  "code": "000321",
  "statusCode": "IN_PROGRESS",
  "statusName": "В работе",
  "updatedAt": "2026-05-20T08:40:12.000Z",
  "comments": [
    {
      "id": "682c73925a3e7d1c2b777001",
      "createdAt": "2026-05-20T08:40:12.000Z",
      "updatedAt": "2026-05-20T08:40:12.000Z",
      "text": "Заявка взята в работу, выполняем диагностику.",
      "isAdminComment": false,
      "author": {
        "id": "681222222222222222222222",
        "externalId": "support-01",
        "fullName": "Специалист поддержки"
      },
      "files": []
    }
  ]
}

POST /help/request/:id/comment — добавление комментария

Контент-тип: multipart/form-data

Поле	Тип	Обязательность	Описание
text	string	да	Текст комментария
isAdminComment	boolean	да	Признак комментария только для администраторов
files	binary[]	нет	Новые вложения комментария

Ответ: полная заявка с добавленным комментарием.

Пример полей multipart/form-data:

text=Нужны дополнительные данные: укажите точное время ошибки и приложите новый скриншот.
isAdminComment=false
files=<binary>

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

{
  "id": "682c6d9f5a3e7d1c2b123456",
  "code": "000321",
  "updatedAt": "2026-05-20T08:48:03.000Z",
  "comments": [
    {
      "id": "682c75435a3e7d1c2b777002",
      "createdAt": "2026-05-20T08:48:03.000Z",
      "updatedAt": "2026-05-20T08:48:03.000Z",
      "text": "Нужны дополнительные данные: укажите точное время ошибки и приложите новый скриншот.",
      "isAdminComment": false,
      "author": {
        "id": "681222222222222222222222",
        "externalId": "support-01",
        "fullName": "Специалист поддержки"
      },
      "files": [
        {
          "id": "682c75435a3e7d1c2b999003",
          "fullUrl": "https://files.example.com/help/682c75435a3e7d1c2b999003",
          "name": "request-details.pdf",
          "mimeType": "application/pdf",
          "size": 87321
        }
      ]
    }
  ]
}

Добавление файлов

Файлы прикрепляются только в этих ручках:

Где добавляются файлы	Как передаются	Что возвращается
POST /help/request	multipart-вложения вместе с созданием заявки	Полная заявка с заполненным files[]
POST /help/request/:id	multipart-вложения вместе с обновлением заявки	Полная заявка с обновлённым files[]
POST /help/request/:id/comment	multipart-вложения вместе с комментарием	Полная заявка с новым элементом в comments[].files[]

Формат файла в ответе:

Поле	Тип	Описание
id	string	Id файла
fullUrl	string	Полный URL файла
name	string	Имя файла
mimeType	string	MIME-тип
size	number	Размер в байтах

Пример объекта файла:

{
  "id": "682c75435a3e7d1c2b999003",
  "fullUrl": "https://files.example.com/help/682c75435a3e7d1c2b999003",
  "name": "request-details.pdf",
  "mimeType": "application/pdf",
  "size": 87321
}

Формат комментария в ответе:

Поле	Тип	Описание
id	string	Id комментария
createdAt	Date	Дата создания
updatedAt	Date	Дата обновления
text	string	Текст комментария
isAdminComment	boolean	Признак админского комментария
author	object	Автор комментария
files	Array<{ id: string; fullUrl: string; name: string; mimeType: string; size: number }>	Файлы комментария

Ключевые поля заявки в ответе:

Поле	Тип	Описание
id	string	Id заявки
createdAt	Date	Дата создания
updatedAt	Date	Дата обновления
code	string	Номер заявки
subject	string	Тема
text	string	Текст
statusCode	string	Код статуса
statusName	string	Наименование статуса
authorId	string	Id автора
authorFullName	string	ФИО автора
authorCompanyName	string	Организация автора
creatorId	string | null	Id создателя
creatorFullName	string | null	ФИО создателя
system	string	Код системы
systemText	string	Наименование системы
supportLineNum	number	Номер активной линии поддержки
supportLineName	string	Название активной линии поддержки
performer	Array<{ id: string; fullName: string }>	Исполнители по линиям
performerFullName	string	Исполнитель активной линии
requestTypeCode	string | null	Код типа заявки
requestTypeName	string | null	Название типа заявки
requestPriorityCode	string | null	Код приоритета
requestPriorityName	string | null	Название приоритета
task	string | null	Код услуги
taskText	string | null	Наименование услуги
additionalInfo	Array<{ name: string; value: string }>	Дополнительные поля
files	Array<{ id: string; fullUrl: string; name: string; mimeType: string; size: number }>	Файлы заявки
comments	Array<object>	Комментарии
nextStatuses	Array<object>	Доступные следующие статусы
nextSupportLine	object	Следующая линия поддержки
prevSupportLine	object[]	Предыдущие линии поддержки
trackerId	string	Id заявки во внешнем трекере

---

12. History (/history)

src/history/controller/history.controller.ts

Журнал изменений заявок.

Метод	Путь	Headers	Описание
GET	/help/history/request/all	X-TS-USER	Вся история по всем доступным заявкам
GET	/help/history/request/:id	X-TS-USER	История по конкретной заявке

---

13. Email (/email)

src/email/controller/email.controller.ts

Метод	Путь	Описание
POST	/help/email/read	Прочитать непрочитанные письма IMAP-ящика и создать на их основе заявки

---

14. Email Rule (/email-rule)

src/email-rules/controller/email-rule.controller.ts

Правила маршрутизации входящих писем. Отдельные ресурсы — для самих правил (/), их видов (/kind) и типов (/type).

Виды правил (rule kinds)

Метод	Путь	Body	Описание
POST	/help/email-rule/kind	CreateTechSupportEmailRuleKindDto	Создать вид правила
GET	/help/email-rule/kind	—	Список видов
GET	/help/email-rule/kind/:id	—	Получить вид по id
PUT	/help/email-rule/kind/:id	UpdateTechSupportEmailRuleKindDto	Обновить вид
DELETE	/help/email-rule/kind/:id	—	Удалить вид

Типы правил (rule types)

Метод	Путь	Body	Описание
POST	/help/email-rule/type	CreateTechSupportEmailRuleTypeDto	Создать тип правила
GET	/help/email-rule/type	—	Список типов
GET	/help/email-rule/type/:id	—	Получить тип по id
PUT	/help/email-rule/type/:id	UpdateTechSupportEmailRuleTypeDto	Обновить тип
DELETE	/help/email-rule/type/:id	—	Удалить тип

Правила

Метод	Путь	Body	Описание
POST	/help/email-rule	CreateTechSupportEmailRuleDto	Создать правило
GET	/help/email-rule	—	Список правил
GET	/help/email-rule/:id	—	Получить правило по id
PUT	/help/email-rule/:id	UpdateTechSupportEmailRuleDto	Обновить правило
DELETE	/help/email-rule/:id	—	Удалить правило

---

Загрузка файлов

Эндпоинты заявок и комментариев, которые принимают вложения, используют multipart/form-data (NestJS AnyFilesInterceptor). Имена файлов проходят через MulterFilenamePipe из src/utils/multer-filename.pipe.ts. В тело запроса можно передавать обычные DTO-поля параллельно с файлами.

Источник

Документация автоматически собрана из контроллеров проекта (src/**/*.controller.ts) на основе декораторов @Controller, @Get/@Post/@Patch/@Put/@Delete, @ApiOperation и используемых заголовков. Актуальная интерактивная версия с DTO-схемами доступна в Swagger UI по адресу /api.