# Отделы

Управление организационной структурой портала: создание, получение, обновление, удаление и фильтрация отделов. Отделы образуют дерево — каждый отдел кроме корневого ссылается на родительский через `parentId`, а сотрудники назначаются в отделы через [справочник сотрудников](/docs/entities/users).

Битрикс24 API: `department.*`
Скоуп: `department`

## Операции

- [Создать отдел](./departments/create.md) — `POST /v1/departments`
- [Список отделов](./departments/list.md) — `GET /v1/departments`
- [Получить отдел](./departments/get.md) — `GET /v1/departments/:id`
- [Обновить отдел](./departments/update.md) — `PATCH /v1/departments/:id`
- [Удалить отдел](./departments/delete.md) — `DELETE /v1/departments/:id`
- [Поиск отделов](./departments/search.md) — `POST /v1/departments/search`
- [Поля отдела](./departments/fields.md) — `GET /v1/departments/fields`

## Ключевые поля

| Поле | Описание |
|------|---------|
| `id` | Идентификатор отдела |
| `name` | Название отдела |
| `parentId` | ID родительского отдела. У корневого отдела портала равен `1` |
| `headId` | ID руководителя отдела. Источник: [`GET /v1/users`](/docs/entities/users). Особенности — пункт 4 ниже |
| `sort` | Порядок сортировки отдела среди соседей (целое число, по возрастанию) |

Полный список полей — [`GET /v1/departments/fields`](./departments/fields.md).

## Что нужно знать перед работой

1. **Структура отделов — дерево с одним корнем.** Отделы верхнего уровня ссылаются на корневой узел через `parentId: 1`. Сам корневой узел не возвращается в [`GET /v1/departments`](./departments/list.md) и не доступен через `GET /v1/departments/:id` — это служебная вершина дерева. Попытка создать второй отдел верхнего уровня (без `parentId` либо с `parentId: 0`) возвращает HTTP 422 с сообщением «В структуре компании должен быть только один раздел верхнего уровня.».
2. **Минимум для создания одного отдела — два поля:** `name` и `parentId`. Если `parentId` опущен — запрос трактуется как попытка создать отдел верхнего уровня (см. пункт выше).
3. **`headId` — ID пользователя, а не отдела, и НЕ проверяется на существование.** Несуществующий ID принимается и сохраняется, запрос возвращает `201` или `200`. Проверяется только `parentId`. Убедитесь, что пользователь существует — [`GET /v1/users`](/docs/entities/users).
4. **`headId` может указывать на учётную запись, которой нет в справочнике сотрудников.** Руководителем отдела может быть назначена запись, которую [`GET /v1/users`](/docs/entities/users/list) не возвращает, например чат-бот. Тогда `GET /v1/users/:id` по значению `headId` отвечает `404 ENTITY_NOT_FOUND`. В оргструктуре руководитель такого отдела может не совпадать с `headId`: роль `MEMBER_HEAD` там принадлежит другому сотруднику либо не назначена. Текущего руководителя берите из оргструктуры, ключу нужен скоуп `humanresources`. Найдите узел отдела в [`GET /v1/humanresources/nodes?type=DEPARTMENT`](/docs/humanresources/nodes/list): у него `accessCode` состоит из буквы `D` и `id` отдела, а не узла, — отделу `107` соответствует `D107`. Узлы с другим префиксом, например `SN23`, созданы в оргструктуре и в `GET /v1/departments` не возвращаются. Фильтра по `accessCode` нет, поэтому обойдите список постранично. Затем запросите узел через [`GET /v1/humanresources/nodes/:id`](/docs/humanresources/nodes/get): руководитель — участник массива `members` с ролью `MEMBER_HEAD`. Нет такого участника — руководитель не назначен.
5. **`sort` управляет порядком в списке.** Значение `sort` сравнивается между отделами одного уровня — внутри одного `parentId`. Меньшее значение — выше в списке.
6. **Удаление отдела с детьми не запрещено и перестраивает дерево.** Отдел удаляется даже при наличии дочерних отделов или сотрудников, а прямые дочерние отделы переносятся под родителя удалённого отдела с новым `sort`. Чтобы контролировать итоговую структуру, перенесите дочерние отделы и сотрудников до удаления.

## Типичный сценарий

1. Получить текущую структуру: [`GET /v1/departments`](./departments/list.md) — увидеть дерево по `parentId`.
2. Найти руководителя для нового отдела: [`GET /v1/users?filter[name]=Иван`](/docs/entities/users).
3. Создать отдел: [`POST /v1/departments`](./departments/create.md) с `name`, `parentId`, `headId`.
4. Назначить сотрудников в отдел: через [`PATCH /v1/users/:id`](/docs/entities/users) с указанием поля `departmentId` (массив ID отделов).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Максимум записей на запрос | 5000 (`limit ≤ 5000`) |
| Авто-пагинация | включается при `limit > 50` |
| Параметр `offset` | применяется построчно (`offset=7` — с 8-й записи) |
| Параметры `order` и `sort` | не поддерживаются — `400 INVALID_SORT_FIELD`, порядок выдачи задаёт портал |
| Batch-запросы | до 50 операций в [`POST /v1/batch`](/docs/batch). Поддерживаются `create`, `update`, `delete` |
| Rate limit | общий для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

## Смотрите также

- [Entity API](/docs/entity-api)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Сотрудники](/docs/entities/users)
- [Узлы оргструктуры](/docs/humanresources/nodes)
- [Справочник API](/docs/api-reference)