# Отделы

Управление организационной структурой портала: создание, получение, обновление, удаление и фильтрация отделов. Отделы образуют дерево — каждый отдел кроме корневого ссылается на родительский через `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) |
| `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 сотрудника, а не отдела, и НЕ проверяется на существование.** Назначить руководителем можно любого сотрудника портала. Bitrix24 не валидирует `headId`: несуществующий ID будет принят и сохранён как висячая ссылка (запрос вернёт `201`/`200`). Проверяется только `parentId`. Убедитесь, что пользователь существует — [`GET /v1/users`](/docs/entities/users).
4. **`sort` управляет порядком в списке.** Значение `sort` сравнивается между отделами одного уровня — внутри одного `parentId`. Меньшее значение — выше в списке.
5. **Удаление отдела с детьми не запрещено и перестраивает дерево.** Bitrix24 удаляет отдел даже при наличии дочерних отделов или сотрудников: прямые дочерние отделы переподвешиваются на родителя удалённого отдела с переназначением `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` | не применяется — порядок выдачи фиксирован |
| 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)
- [Справочник API](/docs/api-reference)