From 415f138676d9b381cdebc53d716dd6760ee257d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=94=D0=BC=D0=B8=D1=82=D1=80=D0=B8=D0=B9=20=D0=A2=D0=BE?= =?UTF-8?q?=D1=80=D0=BE=D0=B2?= Date: Fri, 24 Apr 2026 15:18:11 +0000 Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8=D1=82?= =?UTF-8?q?=D1=8C=20Naumen=20api?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Naumen-api.md | 229 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100644 Naumen-api.md diff --git a/Naumen-api.md b/Naumen-api.md new file mode 100644 index 0000000..db17b7b --- /dev/null +++ b/Naumen-api.md @@ -0,0 +1,229 @@ +Отлично, спасибо за предоставленный материал. Проанализировав его, я подготовил **нормализованное описание API в стиле современной документации (REST API)**. + +Исходная документация содержит много внутренних технических деталей (например, описание событий шлюза), которые не нужны внешнему разработчику. Я их опустил, оставив только ключевую информацию для интеграции. + +--- + +## **API внешней системы "Исполнитель" (Naumen Service Desk)** + +**Базовый URL:** `/gateway/services/rest/` + +**Общий формат ответа:** Для большинства методов, изменяющих состояние, возвращается HTTP `202 Accepted` и тело: +```json +{ + "uuid": "data$11233" // ID события на шлюзе +} +``` +**Аутентификация:** Все запросы требуют параметр `accessKey=<ключ_доступа>`. + +--- + +### **1. Изменение параметров запроса** +**Назначение:** Изменить атрибуты существующего запроса (например, заголовок, описание). + +* **Метод:** `GET` или `POST` +* **Эндпоинт (GET):** `edit//{attributes}?accessKey=` +* **Эндпоинт (POST):** `edit/?accessKey=` +* **Параметры пути:** + * `uuid` (string, обяз.) — ID запроса. + * `attributes` (JSON, для GET) — объект с атрибутами. +* **Body (POST):** JSON `{ "код_атрибута": "значение" }` + +**Пример (POST):** +```http +POST /gateway/services/rest/edit/serviceCall$328075504?accessKey=123 HTTP/1.1 +Content-Type: application/json + +{ "descriptionInRTF" : "Новое описание запроса" } +``` + +--- + +### **2. Принятие запроса в работу** +**Назначение:** Перевести запрос из статуса «Ожидает линии» (`waitLine`) в статус «В работе» (`wip`). + +* **Метод:** `GET` +* **Эндпоинт:** `takeSCResponsibility?accessKey=¶ms='',` +* **Параметры:** + * `uuid` (string, обяз.) — ID запроса. + * `user` (string, обяз.) — Логин пользователя, берущего ответственность. + +**Пример:** +```http +GET /gateway/services/rest/takeSCResponsibility?accessKey=123¶ms='serviceCall$321',ivanov HTTP/1.1 +``` + +--- + +### **3. Перевод запроса в статус «В ожидании»** +**Назначение:** Приостановить работу по запросу с указанием причины (например, ждем ответа от смежников). + +* **Метод:** `POST` +* **Формат данных:** `multipart/form-data` +* **Эндпоинт:** `postponed?accessKey=¶ms='','',,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=¶ms='',request,` +* **Параметры:** + * `uuid` (string, обяз.) — ID запроса. + * `user` (string, обяз.) — Логин пользователя. + * **Body (form-data):** + * `comment` (string, обяз.) — Текст уточнения. + * `files` (file, опц.) — Вложение. + +--- + +### **5. Добавление комментария** +**Назначение:** Добавить внутренний или внешний комментарий к запросу. + +* **Метод:** `POST` +* **Эндпоинт:** `createComment?accessKey=¶ms=requestContent,user` +* **Body (JSON):** + * `source` (string, обяз.) — ID запроса (`serviceCall$...`). + * `text` (string, обяз.) — Текст комментария (можно с HTML-тегами). + +**Пример:** +```json +{ + "source": "serviceCall$247562913", + "text": "Уточнение: приеду завтра в 09:00" +} +``` + +--- + +### **6. Добавление файлов к объекту** +**Назначение:** Прикрепить файл к запросу (например, скриншот, документ). + +* **Метод:** `POST` +* **Формат данных:** `multipart/form-data` +* **Эндпоинт (базовый):** `addFilesToObject?accessKey=¶ms='',request,` +* **Эндпоинт (с указанием атрибута):** `addFilesToObject?accessKey=¶ms='','',request,` +* **Параметры:** + * `uuid` (string, обяз.) — ID запроса. + * `filesCode` (string, опц.) — Код атрибута для файлов (по умолчанию стандартный). + * `user` (string, обяз.) — Логин пользователя. + * **Body (form-data):** Поле `files` с одним или несколькими файлами. + +--- + +### **7. Получение файла** +**Назначение:** Скачать содержимое файла, прикрепленного к объекту. + +* **Метод:** `GET` +* **Эндпоинт:** `get-file/?accessKey=` +* **Ответ:** Бинарные данные файла (Content-Type зависит от типа файла). + +**Пример:** +```http +GET /gateway/services/rest/get-file/file$123123?accessKey=1111-1111-1111 HTTP/1.1 +``` + +--- + +### **8. Перевод запроса в статус «Ожидает подтверждения» (Решение)** +**Назначение:** Предложить решение по запросу и отправить клиенту на подтверждение (основной метод для закрытия). + +* **Метод:** `POST` +* **Формат данных:** `multipart/form-data` +* **Эндпоинт:** `waitingForAccept?accessKey=¶ms='','',request,` +* **Параметры:** + * `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=¶ms='',,requestContent` +* **Параметры:** + * `uuid` (string, обяз.) — ID запроса или его номер (например, `RP1010`). + * `user` (string, обяз.) — Логин пользователя. + * `rtfAttrsFormat` (опц.) — Формат RTF-полей (`plain`, `rtf` и др.). +* **Body (JSON):** Указывает, какие данные вернуть. + +**Пример тела запроса (POST):** +```json +{ + "fields": ["state", "responsible"], + "relatedObjects": [ + { "name": "comments", "onlyNewComments": true }, + { "name": "ConfigItems" }, + { "name": "totalValue" } + ] +} +``` +* `name` доступные: `comments`, `files`, `ConfigItems`, `totalValue`. +* `onlyNewComments`: `true` — вернуть только непросмотренные комментарии. + +--- + +### **10. Получение списка запросов** +**Назначение:** Получить список UUID и номеров запросов, где внешняя система является исполнителем. + +* **Метод:** `GET` +* **Эндпоинт:** `listServiceCalls?accessKey=¶ms=,,` +* **Параметры:** + * `pageStart` (int, опц.) — С какого элемента начать (0-based). + * `maxResult` (int, опц.) — Максимум элементов в ответе. + * `user` (string, обяз.) — Логин пользователя. + +**Пример ответа (асинхронно, через событие):** +```json +{ + "result": "[{\"UUID\":\"serviceCall$38507722\",\"title\":\"RP2158\"}, ...]" +} +``` + +--- + +### **11. Получение ссылки на предзаполненную форму портала** +**Назначение:** Сгенерировать ссылку на страницу создания запроса на портале с предзаполненными полями. + +* **Метод:** `POST` +* **Эндпоинт:** `serviceCallPrefilledForm?accessKey=¶ms=requestContent` +* **Body (JSON):** + * `slmService` (string, обяз.) — UUID услуги. + * `route` (string, обяз.) — UUID вида запроса. + * `descriptionInRTF` (string, опц.) — Описание. + * `fields` (object, опц.) — Доп. поля: `{"код_поля": "значение"}`. + +**Пример ответа:** +```json +{ + "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`) всегда передавайте обязательные текстовые поля, даже если вложение не отправляется. + +Это описание можно использовать как основу для создания клиентской библиотеки или Swagger-спецификации. Если нужны уточнения по какому-то конкретному методу — спрашивайте. \ No newline at end of file