Подразделения
Информация о разделе
Страница содержит сценарии использования API для работы с реестром "Подразделения".
Общая информация
Сервис предназначенный для работы с реестром "Подразделения" направлен на управление внутренней структурой компании. Набор методов API, позволяет интегратору работать с подразделениями компании.
При работе с подразделениями доступны следующие действия:
- Создать новое подразделение
- Получить информацию о реестре подразделений
- Получить подробную информацию о подразделении
- Обновить информацию о подразделении
Создание нового подразделения
Для cоздания нового подразделения, необходимо вызвать метод [POST]/api/v1/abonents/{abonentId}/departments. При успешном выполнении операции метод создаст новое подразделение в организации и вернет его идентификатор.
Важно Данный метод доступен пользователям с ролями Администратор/Владелец.
В качестве входных параметров необходимо передавать:
- идентификатор абонента,
- наименование подразделения (уникальное значение в рамках выбранной организации),
- (необязательно) краткое обозначение (код) подразделения,
- (необязательно) КПП подразделения (уникальное значение в рамках выбранной организации),
- идентификатор головного подразделения,
- (необязательно) адрес подразделения.
При успешной инициализации запроса, проверяется валидность входных параметров. Если проверка входных параметров не пройдена, то сервер вернет ошибки с текстовым описанием причины в теле ответа (См. таблицу 1).
Таблица 1. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Пользователь {userId} не имеет доступа к абоненту {abonentId} | Отказано в доступе: некорректно указан abonentId. Аккаунт пользователя не содержит абонента с указанным идентификатором |
| Некорректный формат данных | Переданы некорректные параметры запроса: один или несколько из указанных параметров не соответствуют их формату данных |
| Указанное головное подразделение не принадлежит выбранной организации | Переданы некорректные параметры запроса: указано несуществующее головное подразделение |
| Указан КПП, который уже используется в другом подразделении | Переданы некорректные параметры запроса: указано КПП, которое уже используется в рамках организации |
| Указанное значение наименования подразделения уже используется в другом подразделении | Переданы некорректные параметры запроса: указано наименование подразделения, которое уже используется в рамках организации |
(Описание ошибок будет систематически дополняться)
Если все проверки успешно пройдены, то сервер вернет положительный ответ с HTTP-кодом 200 и идентификатор созданного подразделения.
Получение информации о реестре подразделений
Для получения информации о реестре подразделений, необходимо вызвать метод [GET]/api/v1/abonents/{abonentId}/departments. При успешном выполнении операции метод вернет список подразделений организации, в модели DepartmentShortDto.
Примечание: Данный метод предназначен для получения реестра подразделений рекурсивным ленивым способом:
- Инициализация:
- При открытии страницы с реестром подразделений происходит загрузка данных первого и второго уровней (если есть) дерева подразделений (1 уровень = Головное подразделение).
- Отображение данных:
- Страница с реестром подразделений отображает головное подразделение (1 уровень) с информацией о наличии у него дочерних подразделений (плюсик).
- Раскрытие подразделения первого уровня:
- При пользовательском действии по раскрытию подразделения первого уровня, система отправляет запрос к API для получения информации о наличии дочерних подразделений у элементов второго уровня.
- API-запрос для загрузки данных:
- Приложение отправляет запрос к API, указывая идентификатор подразделения второго уровня (либо массив идентификаторов).
- API возвращает данные, включая информацию о наличии третьего уровня.
- Обновление модели данных:
- Полученные данные добавляются к модели данных второго уровня.
- Обновление интерфейса:
- Обновленные данные отображаются в интерфейсе приложения.
- Рекурсивная ленивая загрузка при необходимости:
- Если пользователь решает раскрыть дочерние элементы второго уровня, процесс повторяется: приложение отправляет запрос для загрузки данных третьего уровня и так далее.
В качестве входных параметров необходимо передавать:
- идентификатор абонента,
- (необязательно) идентификатор подразделения (относительно, которого нужно вернуть список дочерних подразделений):
- если не указан "идентификатор подразделения", то возвращается список относительно головного подразделения,
- если заполнен параметр "идентификатор подразделения", то данный параметр "строка поиска" - не заполняется,
- если заполнен параметр "строка поиска", то параметр "идентификатор подразделения" - не заполняется,
- если заполнен параметр "строка поиска" + параметр "идентификатор подразделения", то поиск осуществляется по двум параметрам. Если в комбинации поиска, один из параметров не валиден, будет возвращена ошибка,
- (необязательно) строка поиска (поиск осуществляется по наименованию подразделения):
- могут присутствовать символы, цифры, буквы,
- (необязательно) начальное смещение (указывается начальное значение списка),
- (необязательно) количество возвращаемых подразделений (по умолчанию: 50).
При успешной инициализации запроса, проверяется валидность входных параметров. Если проверка входных параметров не пройдена, то сервер вернет ошибки с текстовым описанием причины в теле ответа (См. таблицу 2).
Таблица 2. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Пользователь {userId} не имеет доступа к абоненту {abonentId} | Отказано в доступе: некорректно указан abonentId. Аккаунт пользователя не содержит абонента с указанным идентификатором |
| В указанной организации отсутствует запрашиваемое подразделение | Переданы некорректные параметры запроса: в указанной организации нет данных о запрашиваемом подразделении |
| Невалидные данные в запросе | Переданы некорректные параметры запроса: один или несколько из указанных параметров не соответствуют их формату данных |
(Описание ошибок будет систематически дополняться)
Если все проверки успешно пройдены, то сервер вернет положительный ответ с HTTP-кодом 200 и модель DepartmentShortDto, которая будет содержать список подразделений.
Получение подробной информации о подразделении
Для получения подробной информации о конкретном подразделении, необходимо вызвать метод [GET]/api/v1/abonents/{abonentId}/departments/{departmentId}. При успешном выполнении операции метод вернет информацию о конкретном подразделении организации, в модели DepartmentDto.
В качестве входных параметров необходимо передавать:
- идентификатор абонента,
- идентификатор подразделения.
При успешной инициализации запроса, проверяется валидность входных параметров. Если проверка входных параметров не пройдена, то сервер вернет ошибки с текстовым описанием причины в теле ответа (См. таблицу 3).
Таблица 3. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Пользователь {userId} не имеет доступа к абоненту {abonentId} | Отказано в доступе: некорректно указан abonentId. Аккаунт пользователя не содержит абонента с указанным идентификатором |
| В указанной организации отсутствует запрашиваемое подразделение | Переданы некорректные параметры запроса: в указанной организации нет данных о запрашиваемом подразделении |
| Невалидные данные в запросе | Переданы некорректные параметры запроса: один или несколько из указанных параметров не соответствуют их формату данных |
(Описание ошибок будет систематически дополняться)
Если все проверки успешно пройдены, то сервер вернет положительный ответ с HTTP-кодом 200 и модель DepartmentDto, которая будет содержать детальную информацию по подразделению.
Обновление информации о подразделении
Для изменения информации о подразделении, необходимо вызвать метод [PUT]/api/v1/abonents/{abonentId}/departments/{departmentId}. При успешном выполнении операции метод вернет обновленные данные по подразделению, в модели DepartmentDto.
В качестве входных параметров необходимо передавать:
- идентификатор абонента,
- идентификатор подразделения,
- наименование подразделения,
- (необязательно) краткое обозначение (код) подразделения,
- (необязательно) КПП подразделения,
- идентификатор головного подразделения (обеспечивает возможность перекрепления к другому головному подразделению)
- (необязательно) адрес подразделения.
При успешной инициализации запроса, проверяется валидность входных параметров. Если проверка входных параметров не пройдена, то сервер вернет ошибки с текстовым описанием причины в теле ответа (См. таблицу 4).
Таблица 4. Ошибки входных параметров
| Описание ошибки | Причина |
|---|---|
| Пользователь {userId} не имеет доступа к абоненту {abonentId} | Отказано в доступе: некорректно указан abonentId. Аккаунт пользователя не содержит абонента с указанным идентификатором |
| Некорректный формат данных | Переданы некорректные параметры запроса: один или несколько из указанных параметров не соответствуют их формату данных |
| Указанное головное подразделение не принадлежит выбранной организации | Переданы некорректные параметры запроса: указано несуществующее головное подразделение |
| Указан КПП, который уже используется в другом подразделении | Переданы некорректные параметры запроса: указано КПП, которое уже используется в рамках организации |
| Указано наименование подразделения, которое уже используется в другом подразделении | Переданы некорректные параметры запроса: указано наименование подразделения, которое уже используется в рамках организации |
| Указанный абонент не найден | Переданы некорректные параметры запроса: не найден абонент связанный с пользователем |
(Описание ошибок будет систематически дополняться)
Если все проверки успешно пройдены, то сервер вернет положительный ответ с HTTP-кодом 200 и модель DepartmentDto, которая будет содержать обновленную информацию по подразделению.