dtorov/projects
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Page: Naumen api
Pages
Ком предложение Трудозатраты Home Naumen api finnex
Clone
2
Naumen api
Дмитрий Торов edited this page 2026-04-24 15:22:38 +00:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

API внешней системы "Исполнитель" (Naumen Service Desk)

Базовый URL: <URL>/gateway/services/rest/

Общий формат ответа: Для большинства методов, изменяющих состояние, возвращается HTTP 202 Accepted и тело:

{
  "uuid": "data$11233" // ID события на шлюзе
}

Аутентификация: Все запросы требуют параметр accessKey=<ключ_доступа>.

1. Изменение параметров запроса

Назначение: Изменить атрибуты существующего запроса (например, заголовок, описание).

  • Метод: GET или POST
  • Эндпоинт (GET): edit/<uuid>/{attributes}?accessKey=<key>
  • Эндпоинт (POST): edit/<uuid>?accessKey=<key>
  • Параметры пути:
    • uuid (string, обяз.) — ID запроса.
    • attributes (JSON, для GET) — объект с атрибутами.
  • Body (POST): JSON { "код_атрибута": "значение" }

Пример (POST):

POST /gateway/services/rest/edit/serviceCall$328075504?accessKey=123 HTTP/1.1
Content-Type: application/json

{ "descriptionInRTF" : "Новое описание запроса" }

2. Принятие запроса в работу

Назначение: Перевести запрос из статуса «Ожидает линии» (waitLine) в статус «В работе» (wip).

  • Метод: GET
  • Эндпоинт: takeSCResponsibility?accessKey=<key>&params='<uuid>',<user>
  • Параметры:
    • uuid (string, обяз.) — ID запроса.
    • user (string, обяз.) — Логин пользователя, берущего ответственность.

Пример:

GET /gateway/services/rest/takeSCResponsibility?accessKey=123&params='serviceCall$321',ivanov HTTP/1.1

3. Перевод запроса в статус «В ожидании»

Назначение: Приостановить работу по запросу с указанием причины (например, ждем ответа от смежников).

  • Метод: POST
  • Формат данных: multipart/form-data
  • Эндпоинт: postponed?accessKey=<key>&params='<sc_uuid>','<delay_uuid>',<user>,request
  • Параметры:
    • sc_uuid (string, обяз.) — ID запроса.
    • delay_uuid (string, обяз.) — ID причины ожидания из справочника.
    • user (string, обяз.) — Логин пользователя.
    • Body (form-data):
      • comment (string, обяз.) — Текст комментария-обоснования.
      • files (file, опц.) — Вложение.

4. Отправка запроса на уточнение

Назначение: Запросить у клиента дополнительную информацию (статус «Ожидает уточнений»).

  • Метод: POST
  • Формат данных: multipart/form-data
  • Эндпоинт: waiting?accessKey=<key>&params='<uuid>',request,<user>
  • Параметры:
    • uuid (string, обяз.) — ID запроса.
    • user (string, обяз.) — Логин пользователя.
    • Body (form-data):
      • comment (string, обяз.) — Текст уточнения.
      • files (file, опц.) — Вложение.

5. Добавление комментария

Назначение: Добавить внутренний или внешний комментарий к запросу.

  • Метод: POST
  • Эндпоинт: createComment?accessKey=<key>&params=requestContent,user
  • Body (JSON):
    • source (string, обяз.) — ID запроса (serviceCall$...).
    • text (string, обяз.) — Текст комментария (можно с HTML-тегами).

Пример:

{
  "source": "serviceCall$247562913",
  "text": "<b>Уточнение:</b> приеду завтра в 09:00"
}

6. Добавление файлов к объекту

Назначение: Прикрепить файл к запросу (например, скриншот, документ).

  • Метод: POST
  • Формат данных: multipart/form-data
  • Эндпоинт (базовый): addFilesToObject?accessKey=<key>&params='<uuid>',request,<user>
  • Эндпоинт (с указанием атрибута): addFilesToObject?accessKey=<key>&params='<uuid>','<filesCode>',request,<user>
  • Параметры:
    • uuid (string, обяз.) — ID запроса.
    • filesCode (string, опц.) — Код атрибута для файлов (по умолчанию стандартный).
    • user (string, обяз.) — Логин пользователя.
    • Body (form-data): Поле files с одним или несколькими файлами.

7. Получение файла

Назначение: Скачать содержимое файла, прикрепленного к объекту.

  • Метод: GET
  • Эндпоинт: get-file/<file_uuid>?accessKey=<key>
  • Ответ: Бинарные данные файла (Content-Type зависит от типа файла).

Пример:

GET /gateway/services/rest/get-file/file$123123?accessKey=1111-1111-1111 HTTP/1.1

8. Перевод запроса в статус «Ожидает подтверждения» (Решение)

Назначение: Предложить решение по запросу и отправить клиенту на подтверждение (основной метод для закрытия).

  • Метод: POST
  • Формат данных: multipart/form-data
  • Эндпоинт: waitingForAccept?accessKey=<key>&params='<uuid>','<filesAttrCode>',request,<user>
  • Параметры:
    • uuid (string, обяз.) — ID запроса.
    • filesAttrCode (string, опц., по умолч. ContentFilesSolut) — Атрибут для файлов решения.
    • user (string, обяз.) — Логин пользователя.
    • Body (обязательные поля form-data):
      • procCodeClose (string, обяз.) — Код завершения (результата) из справочника.
      • solution (string, обяз.) — Текст решения.
      • files (file, опц.) — Вложение.
      • analyticalFeat — JSON с аналитическими признаками (если обязательны).

9. Получение данных запроса и связанных объектов

Назначение: Получить атрибуты запроса, динамические поля, комментарии, файлы, конфигурационные единицы (CI).

  • Метод: GET или POST
  • Эндпоинт: getSCData?accessKey=<key>&params='<uuid>',<user>,requestContent
  • Параметры:
    • uuid (string, обяз.) — ID запроса или его номер (например, RP1010).
    • user (string, обяз.) — Логин пользователя.
    • rtfAttrsFormat (опц.) — Формат RTF-полей (plain, rtf и др.).
  • Body (JSON): Указывает, какие данные вернуть.

Пример тела запроса (POST):

{
  "fields": ["state", "responsible"],
  "relatedObjects": [
    { "name": "comments", "onlyNewComments": true },
    { "name": "ConfigItems" },
    { "name": "totalValue" }
  ]
}
  • name доступные: comments, files, ConfigItems, totalValue.
  • onlyNewComments: true — вернуть только непросмотренные комментарии.

10. Получение списка запросов

Назначение: Получить список UUID и номеров запросов, где внешняя система является исполнителем.

  • Метод: GET
  • Эндпоинт: listServiceCalls?accessKey=<key>&params=<pageStart>,<maxResult>,<user>
  • Параметры:
    • pageStart (int, опц.) — С какого элемента начать (0-based).
    • maxResult (int, опц.) — Максимум элементов в ответе.
    • user (string, обяз.) — Логин пользователя.

Пример ответа (асинхронно, через событие):

{
  "result": "[{\"UUID\":\"serviceCall$38507722\",\"title\":\"RP2158\"}, ...]"
}

11. Получение ссылки на предзаполненную форму портала

Назначение: Сгенерировать ссылку на страницу создания запроса на портале с предзаполненными полями.

  • Метод: POST
  • Эндпоинт: serviceCallPrefilledForm?accessKey=<key>&params=requestContent
  • Body (JSON):
    • slmService (string, обяз.) — UUID услуги.
    • route (string, обяз.) — UUID вида запроса.
    • descriptionInRTF (string, опц.) — Описание.
    • fields (object, опц.) — Доп. поля: {"код_поля": "значение"}.

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

{
  "formLink": "/portal/navigator-fields.html?service=service$38507420&template=template$41594314"
}

Рекомендации по использованию

  1. Для изменения статусов используйте специализированные методы (takeSCResponsibility, postponed, waiting, waitingForAccept), а не универсальный edit.
  2. Ключевой метод решения запроса — waitingForAccept. Он отправляет решение на подтверждение клиенту.
  3. Пагинацию обязательно используйте при вызове listServiceCalls, чтобы избежать больших ответов.
  4. Для получения непросмотренных комментариев применяйте getSCData с параметром onlyNewComments: true. После просмотра комментарий автоматически перестанет считаться новым.
  5. В методах с multipart/form-data (waiting, addFilesToObject, waitingForAccept) всегда передавайте обязательные текстовые поля, даже если вложение не отправляется.