REST: оргструктура и департаменты

Семейство department.* открывает REST-доступ к организационной структуре Битрикс24: дереву отделов, их руководителям и вложенности. Вместе с полем UF_DEPARTMENT у сотрудников оно позволяет полностью воспроизвести оргструктуру из внешней системы.

Как устроена оргструктура

Структура компании в Битрикс24 — это дерево отделов. Каждый отдел имеет родителя (кроме корневого), название, порядок сортировки и, опционально, руководителя. Сотрудник привязывается к одному или нескольким отделам через множественное поле UF_DEPARTMENT.

За отделы отвечает скоуп department. Методы семейства:

• department.get — список/чтение отделов;
• department.add — создать отдел;
• department.update — изменить;
• department.delete — удалить;
• department.fields — доступные поля.

Поля отдела

Набор полей отдела компактный:

Поле UF_HEAD хранит ID пользователя-руководителя. Именно оно определяет, кто в отделе «начальник» — это влияет на маршруты согласований и права руководителя в задачах и CRM.

Чтение структуры: department.get

Без параметров метод вернёт все отделы. Обычно фильтруют по родителю, чтобы получить ветку:

POST /rest/1/xxxx/department.get.json
{"PARENT":1,"SORT":"SORT","ORDER":"ASC"}

Параметры: ID (конкретный отдел), NAME, PARENT, UF_HEAD, а также SORT/ORDER и листание start. Чтобы построить полное дерево, забирают все отделы и восстанавливают иерархию по связке ID → PARENT на своей стороне.

Построение дерева: add и update

Создание отдела требует имени и, как правило, родителя:

POST /rest/1/xxxx/department.add.json
{"NAME":"Отдел продаж","PARENT":1,"UF_HEAD":17,"SORT":100}

Метод вернёт ID нового отдела. При загрузке многоуровневой структуры важен порядок: сначала создаём родителей, получаем их ID, затем — детей с корректным PARENT.

Отделы и сотрудники

Само семейство department.* не возвращает список сотрудников отдела — эта связь хранится на стороне пользователя. Чтобы получить людей отдела, используйте метод user.get:

{"FILTER":{"UF_DEPARTMENT":5,"ACTIVE":true}}

Логика проста:

1. department.get даёт дерево и UF_HEAD каждого отдела;
2. user.get с фильтром UF_DEPARTMENT — состав конкретного отдела;
3. руководитель определяется полем UF_HEAD отдела.

Так связка двух семейств полностью описывает «кто где работает и кто кем руководит».

Сценарии синхронизации

Оргструктура — типовой объект обмена с кадровыми системами и 1С:ЗУП:

• Первичная загрузка. Разворачиваем дерево отделов из учётной системы, соблюдая порядок уровней.
• Поддержание в актуальном виде. При кадровых изменениях правим UF_HEAD и переносим сотрудников между отделами через user.update.
• Права и маршруты. Корректная структура — основа для автоматических согласований и прав руководителей в задачах и CRM.

Итог

Семейство department.* описывает дерево компании, а состав отделов и руководители раскрываются в связке с user.get и полем UF_DEPARTMENT. При импорте соблюдайте порядок уровней и ведите карту внешних идентификаторов.

Мы настраиваем двустороннюю синхронизацию оргструктуры Битрикс24 с 1С и кадровыми системами: отделы, руководители, перемещения сотрудников — всё поддерживается автоматически и без «висящих» связей. Поможем спроектировать обмен и сопровождать его.