Добавить Naumen api
parent
f4ee013088
commit
415f138676
229
Naumen-api.md
Normal file
229
Naumen-api.md
Normal file
@ -0,0 +1,229 @@
|
||||
Отлично, спасибо за предоставленный материал. Проанализировав его, я подготовил **нормализованное описание API в стиле современной документации (REST API)**.
|
||||
|
||||
Исходная документация содержит много внутренних технических деталей (например, описание событий шлюза), которые не нужны внешнему разработчику. Я их опустил, оставив только ключевую информацию для интеграции.
|
||||
|
||||
---
|
||||
|
||||
## **API внешней системы "Исполнитель" (Naumen Service Desk)**
|
||||
|
||||
**Базовый URL:** `<URL>/gateway/services/rest/`
|
||||
|
||||
**Общий формат ответа:** Для большинства методов, изменяющих состояние, возвращается HTTP `202 Accepted` и тело:
|
||||
```json
|
||||
{
|
||||
"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):**
|
||||
```http
|
||||
POST /gateway/services/rest/edit/serviceCall$328075504?accessKey=123 HTTP/1.1
|
||||
Content-Type: application/json
|
||||
|
||||
{ "descriptionInRTF" : "Новое описание запроса" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **2. Принятие запроса в работу**
|
||||
**Назначение:** Перевести запрос из статуса «Ожидает линии» (`waitLine`) в статус «В работе» (`wip`).
|
||||
|
||||
* **Метод:** `GET`
|
||||
* **Эндпоинт:** `takeSCResponsibility?accessKey=<key>¶ms='<uuid>',<user>`
|
||||
* **Параметры:**
|
||||
* `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=<key>¶ms='<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>¶ms='<uuid>',request,<user>`
|
||||
* **Параметры:**
|
||||
* `uuid` (string, обяз.) — ID запроса.
|
||||
* `user` (string, обяз.) — Логин пользователя.
|
||||
* **Body (form-data):**
|
||||
* `comment` (string, обяз.) — Текст уточнения.
|
||||
* `files` (file, опц.) — Вложение.
|
||||
|
||||
---
|
||||
|
||||
### **5. Добавление комментария**
|
||||
**Назначение:** Добавить внутренний или внешний комментарий к запросу.
|
||||
|
||||
* **Метод:** `POST`
|
||||
* **Эндпоинт:** `createComment?accessKey=<key>¶ms=requestContent,user`
|
||||
* **Body (JSON):**
|
||||
* `source` (string, обяз.) — ID запроса (`serviceCall$...`).
|
||||
* `text` (string, обяз.) — Текст комментария (можно с HTML-тегами).
|
||||
|
||||
**Пример:**
|
||||
```json
|
||||
{
|
||||
"source": "serviceCall$247562913",
|
||||
"text": "<b>Уточнение:</b> приеду завтра в 09:00"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **6. Добавление файлов к объекту**
|
||||
**Назначение:** Прикрепить файл к запросу (например, скриншот, документ).
|
||||
|
||||
* **Метод:** `POST`
|
||||
* **Формат данных:** `multipart/form-data`
|
||||
* **Эндпоинт (базовый):** `addFilesToObject?accessKey=<key>¶ms='<uuid>',request,<user>`
|
||||
* **Эндпоинт (с указанием атрибута):** `addFilesToObject?accessKey=<key>¶ms='<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 зависит от типа файла).
|
||||
|
||||
**Пример:**
|
||||
```http
|
||||
GET /gateway/services/rest/get-file/file$123123?accessKey=1111-1111-1111 HTTP/1.1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **8. Перевод запроса в статус «Ожидает подтверждения» (Решение)**
|
||||
**Назначение:** Предложить решение по запросу и отправить клиенту на подтверждение (основной метод для закрытия).
|
||||
|
||||
* **Метод:** `POST`
|
||||
* **Формат данных:** `multipart/form-data`
|
||||
* **Эндпоинт:** `waitingForAccept?accessKey=<key>¶ms='<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>¶ms='<uuid>',<user>,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=<key>¶ms=<pageStart>,<maxResult>,<user>`
|
||||
* **Параметры:**
|
||||
* `pageStart` (int, опц.) — С какого элемента начать (0-based).
|
||||
* `maxResult` (int, опц.) — Максимум элементов в ответе.
|
||||
* `user` (string, обяз.) — Логин пользователя.
|
||||
|
||||
**Пример ответа (асинхронно, через событие):**
|
||||
```json
|
||||
{
|
||||
"result": "[{\"UUID\":\"serviceCall$38507722\",\"title\":\"RP2158\"}, ...]"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **11. Получение ссылки на предзаполненную форму портала**
|
||||
**Назначение:** Сгенерировать ссылку на страницу создания запроса на портале с предзаполненными полями.
|
||||
|
||||
* **Метод:** `POST`
|
||||
* **Эндпоинт:** `serviceCallPrefilledForm?accessKey=<key>¶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-спецификации. Если нужны уточнения по какому-то конкретному методу — спрашивайте.
|
||||
Loading…
x
Reference in New Issue
Block a user