[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-entities\u002Fdepartments":3,"docs-tabs-entities\u002Fdepartments":6},{"content":4,"lastmod":5},"# Отделы\n\nУправление организационной структурой портала: создание, получение, обновление, удаление и фильтрация отделов. Отделы образуют дерево — каждый отдел кроме корневого ссылается на родительский через `parentId`, а сотрудники назначаются в отделы через [справочник сотрудников](\u002Fdocs\u002Fentities\u002Fusers).\n\nБитрикс24 API: `department.*`\nСкоуп: `department`\n\n## Операции\n\n- [Создать отдел](.\u002Fdepartments\u002Fcreate.md) — `POST \u002Fv1\u002Fdepartments`\n- [Список отделов](.\u002Fdepartments\u002Flist.md) — `GET \u002Fv1\u002Fdepartments`\n- [Получить отдел](.\u002Fdepartments\u002Fget.md) — `GET \u002Fv1\u002Fdepartments\u002F:id`\n- [Обновить отдел](.\u002Fdepartments\u002Fupdate.md) — `PATCH \u002Fv1\u002Fdepartments\u002F:id`\n- [Удалить отдел](.\u002Fdepartments\u002Fdelete.md) — `DELETE \u002Fv1\u002Fdepartments\u002F:id`\n- [Поиск отделов](.\u002Fdepartments\u002Fsearch.md) — `POST \u002Fv1\u002Fdepartments\u002Fsearch`\n- [Поля отдела](.\u002Fdepartments\u002Ffields.md) — `GET \u002Fv1\u002Fdepartments\u002Ffields`\n\n## Ключевые поля\n\n| Поле | Описание |\n|------|---------|\n| `id` | Идентификатор отдела |\n| `name` | Название отдела |\n| `parentId` | ID родительского отдела. У корневого отдела портала равен `1` |\n| `headId` | ID руководителя отдела. Источник: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) |\n| `sort` | Порядок сортировки отдела среди соседей (целое число, по возрастанию) |\n\nПолный список полей — [`GET \u002Fv1\u002Fdepartments\u002Ffields`](.\u002Fdepartments\u002Ffields.md).\n\n## Что нужно знать перед работой\n\n1. **Структура отделов — дерево с одним корнем.** Отделы верхнего уровня ссылаются на корневой узел через `parentId: 1`. Сам корневой узел не возвращается в [`GET \u002Fv1\u002Fdepartments`](.\u002Fdepartments\u002Flist.md) и не доступен через `GET \u002Fv1\u002Fdepartments\u002F:id` — это служебная вершина дерева. Попытка создать второй отдел верхнего уровня (без `parentId` либо с `parentId: 0`) возвращает HTTP 422 с сообщением «В структуре компании должен быть только один раздел верхнего уровня.».\n2. **Минимум для создания одного отдела — два поля:** `name` и `parentId`. Если `parentId` опущен — запрос трактуется как попытка создать отдел верхнего уровня (см. пункт выше).\n3. **`headId` — ID сотрудника, а не отдела, и НЕ проверяется на существование.** Назначить руководителем можно любого сотрудника портала. Bitrix24 не валидирует `headId`: несуществующий ID будет принят и сохранён как висячая ссылка (запрос вернёт `201`\u002F`200`). Проверяется только `parentId`. Убедитесь, что пользователь существует — [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers).\n4. **`sort` управляет порядком в списке.** Значение `sort` сравнивается между отделами одного уровня — внутри одного `parentId`. Меньшее значение — выше в списке.\n5. **Удаление отдела с детьми не запрещено и перестраивает дерево.** Bitrix24 удаляет отдел даже при наличии дочерних отделов или сотрудников: прямые дочерние отделы переподвешиваются на родителя удалённого отдела с переназначением `sort`. Чтобы контролировать итоговую структуру, перенесите дочерние отделы и сотрудников до удаления.\n\n## Типичный сценарий\n\n1. Получить текущую структуру: [`GET \u002Fv1\u002Fdepartments`](.\u002Fdepartments\u002Flist.md) — увидеть дерево по `parentId`.\n2. Найти руководителя для нового отдела: [`GET \u002Fv1\u002Fusers?filter[name]=Иван`](\u002Fdocs\u002Fentities\u002Fusers).\n3. Создать отдел: [`POST \u002Fv1\u002Fdepartments`](.\u002Fdepartments\u002Fcreate.md) с `name`, `parentId`, `headId`.\n4. Назначить сотрудников в отдел: через [`PATCH \u002Fv1\u002Fusers\u002F:id`](\u002Fdocs\u002Fentities\u002Fusers) с указанием поля `departmentId` (массив ID отделов).\n\n## Лимиты\n\n| Лимит | Значение |\n|-------|----------|\n| Максимум записей на запрос | 5000 (`limit ≤ 5000`) |\n| Авто-пагинация | включается при `limit > 50` |\n| Параметр `offset` | не применяется — возвращается вся выборка фильтра |\n| Параметр `order` | не применяется — порядок выдачи фиксирован |\n| Batch-запросы | до 50 операций в [`POST \u002Fv1\u002Fbatch`](\u002Fdocs\u002Fbatch). Поддерживаются `create`, `update`, `delete` |\n| Rate limit | общий для Vibe API — см. [Лимиты и оптимизация](\u002Fdocs\u002Foptimization) |\n\n## Смотрите также\n\n- [Entity API](\u002Fdocs\u002Fentity-api) — общие принципы работы с сущностями\n- [Синтаксис фильтрации](\u002Fdocs\u002Ffiltering)\n- [Batch](\u002Fdocs\u002Fbatch) — массовые операции\n- [Сотрудники](\u002Fdocs\u002Fentities\u002Fusers) — назначение в отделы и поиск руководителей\n- [Справочник сущностей](\u002Fdocs\u002Fentities-index)\n","2026-06-19",{"departments\u002Fcreate.md":7,"departments\u002Flist.md":8,"departments\u002Fget.md":9,"departments\u002Fupdate.md":10,"departments\u002Fdelete.md":11,"departments\u002Fsearch.md":12,"departments\u002Ffields.md":13},"\n## Создать отдел\n\n`POST \u002Fv1\u002Fdepartments`\n\nСоздаёт новый отдел в дереве организационной структуры портала.\n\n## Поля запроса (body)\n\n| Параметр | Тип | Обяз. | Описание |\n|----------|-----|:-----:|---------|\n| `name` | string | да | Название отдела |\n| `parentId` | number | да | ID родительского отдела. Список родителей: [`GET \u002Fv1\u002Fdepartments`](.\u002Flist.md). Для отдела верхнего уровня используйте `parentId: 1` |\n| `headId` | number | | ID руководителя отдела. Источник: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) |\n| `sort` | number | | Порядок отдела среди соседей (меньшее значение — выше в списке). По умолчанию `500` |\n\nСоздать второй отдел верхнего уровня (без `parentId` или с `parentId: 0`) нельзя — портал поддерживает только один корневой отдел.\n\n> **`headId` не проверяется на существование.** Bitrix24 не валидирует пользователя в `headId`: несуществующий `userId` будет принят и сохранён как руководитель отдела (висячая ссылка), запрос вернёт `201`. Валидируется только `parentId` (несуществующий родитель → `422 BITRIX_ERROR`). Перед назначением убедитесь, что пользователь существует — [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers).\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"name\": \"Коммерческий отдел\",\n    \"parentId\": 1,\n    \"headId\": 99,\n    \"sort\": 500\n  }'\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"name\": \"Коммерческий отдел\",\n    \"parentId\": 1,\n    \"headId\": 99,\n    \"sort\": 500\n  }'\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    name: 'Коммерческий отдел',\n    parentId: 1,\n    headId: 99,\n    sort: 500,\n  }),\n})\n\nconst { success, data } = await res.json()\nconsole.log('Department ID:', data.id)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    name: 'Коммерческий отдел',\n    parentId: 1,\n    headId: 99,\n    sort: 500,\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `id` | number | ID созданного отдела |\n| `name` | string | Название |\n| `parentId` | number | ID родительского отдела |\n| `headId` | number | ID руководителя (если указан при создании) |\n| `sort` | number | Порядок сортировки |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 189,\n    \"name\": \"Коммерческий отдел\",\n    \"sort\": 500,\n    \"parentId\": 1,\n    \"headId\": 99\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n422 — не указано обязательное поле `name` (при валидном `parentId`):\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"Не введено название раздела.\"\n  }\n}\n```\n\nПорядок валидации: сначала проверяется корректность `parentId` (для пустого тела или отсутствующего `parentId` сработает ошибка единственного корневого отдела), и только затем — обязательность `name`.\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 422 | `BITRIX_ERROR` | Не указан `name`, либо попытка создать второй корневой отдел, либо `parentId` ссылается на несуществующий отдел. `headId` НЕ проверяется (несуществующий пользователь принимается) |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `department` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Смотрите также\n\n- [Список отделов](\u002Fdocs\u002Fentities\u002Fdepartments\u002Flist) — посмотреть текущее дерево перед созданием\n- [Поля отдела](\u002Fdocs\u002Fentities\u002Fdepartments\u002Ffields) — какие поля можно передавать\n- [Сотрудники](\u002Fdocs\u002Fentities\u002Fusers) — найти руководителя\n- [Batch](\u002Fdocs\u002Fbatch) — массовое создание отделов\n","\n## Список отделов\n\n`GET \u002Fv1\u002Fdepartments`\n\nВозвращает список отделов портала с поддержкой фильтрации и выборки полей.\n\n## Параметры\n\n| Параметр | Тип | По умолч. | Описание |\n|----------|-----|-----------|---------|\n| `limit` | number | `50` | Количество записей (до 5000). При `limit > 50` Vibe автоматически собирает несколько страниц у Битрикс24 |\n| `select` | string | — | Выборка полей: `?select=id,name`. Возвращаются только перечисленные поля |\n| `filter` | object | — | Фильтрация по полям `GET \u002Fv1\u002Fdepartments\u002Ffields`.\u003Cbr>[Синтаксис фильтрации](\u002Fdocs\u002Ffiltering). Пример: `?filter[parentId]=1` |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments?filter[parentId]=1\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments?filter[parentId]=1\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments?filter[parentId]=1', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data, meta } = await res.json()\nconsole.log(`Найдено ${meta.total} отделов`)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments?filter[parentId]=1', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data, meta } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data` | array | Массив отделов (см. [Поля отдела](\u002Fdocs\u002Fentities\u002Fdepartments\u002Ffields)) |\n| `meta.total` | number | Общее количество записей, соответствующих фильтру |\n| `meta.hasMore` | boolean | Есть ли ещё записи за пределами `limit` |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 47,\n      \"name\": \"Коммерческий отдел\",\n      \"sort\": 500,\n      \"parentId\": 1,\n      \"headId\": 99\n    },\n    {\n      \"id\": 107,\n      \"name\": \"Отдел разработки\",\n      \"sort\": 600,\n      \"parentId\": 1,\n      \"headId\": 1\n    }\n  ],\n  \"meta\": {\n    \"total\": 2,\n    \"hasMore\": false\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n403 — нет скоупа:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"SCOPE_DENIED\",\n    \"message\": \"This endpoint requires 'department' scope\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `department` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Сортировка не поддерживается; `offset` работает постранично.** Параметр `order` \u002F `sort` отклоняется с ошибкой `400 INVALID_SORT_FIELD` — метод Битрикс24 `department.get` не принимает порядок сортировки; для упорядочивания отсортируйте выборку на стороне клиента. Параметр `offset` применяется постранично: Битрикс24 отдаёт результат страницами по 50 записей, поэтому `offset` округляется вниз до кратного 50 (значения меньше 50 не сдвигают выборку). При `limit > 50` Vibe сам собирает нужные страницы (см. параметр `limit` выше), поэтому весь список департаментов загружается одним запросом без ручной постраничной навигации.\n\n**Когда использовать search вместо list:** для сложных условий по нескольким полям удобнее [`POST \u002Fv1\u002Fdepartments\u002Fsearch`](.\u002Fsearch.md) — параметры передаются в теле запроса.\n\n## Смотрите также\n\n- [Поиск отделов](\u002Fdocs\u002Fentities\u002Fdepartments\u002Fsearch) — POST-запрос для сложных фильтров\n- [Получить отдел](\u002Fdocs\u002Fentities\u002Fdepartments\u002Fget) — получение одного отдела по ID\n- [Создать отдел](\u002Fdocs\u002Fentities\u002Fdepartments\u002Fcreate)\n- [Синтаксис фильтрации](\u002Fdocs\u002Ffiltering)\n- [Entity API](\u002Fdocs\u002Fentity-api) — общие принципы (select, фильтры)\n- [Batch](\u002Fdocs\u002Fbatch) — объединение нескольких запросов\n","\n## Получить отдел\n\n`GET \u002Fv1\u002Fdepartments\u002F:id`\n\nВозвращает один отдел по идентификатору со всеми полями.\n\n## Параметры\n\n| Параметр | Тип | Обяз. | Описание |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | да | ID отдела |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002F47\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002F47\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002F47', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data } = await res.json()\nconsole.log('Отдел:', data.name, '— руководитель ID', data.headId)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002F47', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data } = await res.json()\n```\n\n## Поля ответа\n\nОбъект отдела со всеми полями — см. [Поля отдела](\u002Fdocs\u002Fentities\u002Fdepartments\u002Ffields).\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 47,\n    \"name\": \"Коммерческий отдел\",\n    \"sort\": 500,\n    \"parentId\": 1,\n    \"headId\": 99\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n404 — отдел не найден:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"department 9999 not found\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 404 | `ENTITY_NOT_FOUND` | Отдел с таким ID не найден |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `department` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Смотрите также\n\n- [Поля отдела](\u002Fdocs\u002Fentities\u002Fdepartments\u002Ffields) — все поля\n- [Обновить отдел](\u002Fdocs\u002Fentities\u002Fdepartments\u002Fupdate) — изменение полей\n- [Список отделов](\u002Fdocs\u002Fentities\u002Fdepartments\u002Flist) — поиск с фильтрами\n- [Сотрудники](\u002Fdocs\u002Fentities\u002Fusers) — найти руководителя или сотрудников отдела\n","\n## Обновить отдел\n\n`PATCH \u002Fv1\u002Fdepartments\u002F:id`\n\nОбновляет поля существующего отдела. Передайте только изменяемые поля.\n\n## Поля запроса (body)\n\n| Параметр | Тип | Описание |\n|----------|-----|---------|\n| `name` | string | Название отдела |\n| `parentId` | number | ID нового родительского отдела — для перемещения отдела в дереве. Должен ссылаться на существующий отдел. Список: [`GET \u002Fv1\u002Fdepartments`](.\u002Flist.md) |\n| `headId` | number | Новый руководитель. Источник: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) |\n| `sort` | number | Порядок среди отделов того же уровня |\n\nПолный список полей — [Поля отдела](\u002Fdocs\u002Fentities\u002Fdepartments\u002Ffields).\n\n> **`headId` не проверяется на существование.** Bitrix24 не валидирует пользователя в `headId`: несуществующий `userId` будет принят и сохранён (висячая ссылка), запрос вернёт `200`. Валидируется только `parentId` (несуществующий родитель → `422 BITRIX_ERROR`). Перед назначением убедитесь, что пользователь существует — [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers).\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002F47\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"name\": \"Коммерческий отдел Запад\",\n    \"headId\": 101\n  }'\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X PATCH \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002F47\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"name\": \"Коммерческий отдел Запад\",\n    \"headId\": 101\n  }'\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002F47', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    name: 'Коммерческий отдел Запад',\n    headId: 101,\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002F47', {\n  method: 'PATCH',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    name: 'Коммерческий отдел Запад',\n    headId: 101,\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `data` | object | Обновлённый объект отдела со всеми полями — см. [Поля](\u002Fdocs\u002Fentities\u002Fdepartments\u002Ffields) |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 47,\n    \"name\": \"Коммерческий отдел Запад\",\n    \"sort\": 500,\n    \"parentId\": 1,\n    \"headId\": 101\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n404 — отдел не найден:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"department 9999 not found\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 404 | `ENTITY_NOT_FOUND` | Отдел не найден |\n| 422 | `BITRIX_ERROR` | `parentId` ссылается на несуществующий отдел. `headId` НЕ проверяется (несуществующий пользователь принимается) |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `department` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Смотрите также\n\n- [Получить отдел](\u002Fdocs\u002Fentities\u002Fdepartments\u002Fget) — текущие значения полей\n- [Поля отдела](\u002Fdocs\u002Fentities\u002Fdepartments\u002Ffields) — какие поля можно изменять\n- [Batch](\u002Fdocs\u002Fbatch) — массовое обновление отделов\n","\n## Удалить отдел\n\n`DELETE \u002Fv1\u002Fdepartments\u002F:id`\n\nУдаляет отдел по ID. **Удаление не блокируется** наличием дочерних отделов или закреплённых сотрудников: Bitrix24 удаляет отдел и автоматически переподвешивает его прямые дочерние отделы на родителя удаляемого отдела, переназначая им `sort` (их собственные поддеревья перемещаются вверх вместе с ними). Чтобы контролировать итоговую структуру, перенесите дочерние отделы и сотрудников вручную **до** удаления.\n\n## Параметры\n\n| Параметр | Тип | Обяз. | Описание |\n|----------|-----|:-----:|---------|\n| `id` (path) | number | да | ID отдела |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X DELETE \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002F189\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X DELETE \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002F189\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002F189', {\n  method: 'DELETE',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nif (res.status === 204) {\n  console.log('Отдел удалён')\n}\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002F189', {\n  method: 'DELETE',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nif (res.status === 204) {\n  console.log('Удалено')\n}\n```\n\n## Ответ\n\nПри успешном удалении возвращается HTTP-статус `204 No Content` с пустым телом — признак успеха проверяется по статусу.\n\n## Пример ответа\n\n```\nHTTP\u002F1.1 204 No Content\n```\n\n## Пример ответа при ошибке\n\n404 — отдел не найден:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"ENTITY_NOT_FOUND\",\n    \"message\": \"Department not found\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 404 | `ENTITY_NOT_FOUND` | Отдел не найден |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `department` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Удаление отдела с детьми не запрещено и молча перестраивает дерево.** При `DELETE` отдела, у которого есть дочерние отделы, Bitrix24 удаляет его (`204`) и переподвешивает прямые дочерние отделы на родителя удалённого отдела, переназначая им `sort`; их собственные поддеревья перемещаются вверх вместе с ними. Закреплённые сотрудники также не препятствуют удалению. Чтобы контролировать итоговую структуру, **до** удаления перенесите дочерние отделы через [`PATCH \u002Fv1\u002Fdepartments\u002F:id`](.\u002Fupdate.md) (новый `parentId`) и переназначьте сотрудников через [`PATCH \u002Fv1\u002Fusers\u002F:id`](\u002Fdocs\u002Fentities\u002Fusers) с новым `departmentId` (массив ID отделов).\n\n## Смотрите также\n\n- [Список отделов](\u002Fdocs\u002Fentities\u002Fdepartments\u002Flist) — посмотреть дочерние отделы перед удалением\n- [Обновить отдел](\u002Fdocs\u002Fentities\u002Fdepartments\u002Fupdate) — перенос дочерних отделов\n- [Сотрудники](\u002Fdocs\u002Fentities\u002Fusers) — переназначение сотрудников\n- [Batch](\u002Fdocs\u002Fbatch) — массовое удаление\n","\n## Поиск отделов\n\n`POST \u002Fv1\u002Fdepartments\u002Fsearch`\n\nПоиск отделов с фильтрами. Аналог `GET \u002Fv1\u002Fdepartments` с фильтрами, но через POST — удобнее для сложных запросов с несколькими условиями.\n\n## Поля запроса (body)\n\n| Параметр | Тип | По умолч. | Описание |\n|----------|-----|-----------|---------|\n| `filter` | object | — | Фильтрация по полям `GET \u002Fv1\u002Fdepartments\u002Ffields`.\u003Cbr>[Синтаксис фильтрации](\u002Fdocs\u002Ffiltering). Пример: `{ \"parentId\": 1 }` |\n| `limit` | number | `50` | Количество записей (до 5000) |\n| `select` | string[] | — | Выборка полей: `[\"id\", \"name\"]` |\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002Fsearch\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": { \"parentId\": 1 },\n    \"limit\": 10\n  }'\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002Fsearch\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": { \"parentId\": 1 },\n    \"limit\": 10\n  }'\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002Fsearch', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    filter: { parentId: 1 },\n    limit: 10,\n  }),\n})\n\nconst { success, data, meta } = await res.json()\nconsole.log('Найдено:', meta.total)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002Fsearch', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    filter: { parentId: 1 },\n    limit: 10,\n  }),\n})\n\nconst { success, data, meta } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data` | array | Массив отделов (см. [Поля отдела](\u002Fdocs\u002Fentities\u002Fdepartments\u002Ffields)) |\n| `meta.total` | number | Общее количество записей, соответствующих фильтру |\n| `meta.hasMore` | boolean | Есть ли ещё записи за пределами `limit` |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 47,\n      \"name\": \"Коммерческий отдел\",\n      \"sort\": 500,\n      \"parentId\": 1,\n      \"headId\": 99\n    },\n    {\n      \"id\": 107,\n      \"name\": \"Отдел разработки\",\n      \"sort\": 600,\n      \"parentId\": 1,\n      \"headId\": 1\n    }\n  ],\n  \"meta\": {\n    \"total\": 2,\n    \"hasMore\": false\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n403 — нет скоупа:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"SCOPE_DENIED\",\n    \"message\": \"This endpoint requires 'department' scope\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `department` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Параметры `order` и `offset` не применяются.** Поле `order` в теле запроса принимается без ошибки, но порядок результата не меняется. Поле `offset` тоже принимается, но всегда возвращается выборка с начала. Для больших порталов запрашивайте всю выборку фильтра и сортируйте на стороне клиента.\n\n## Смотрите также\n\n- [Список отделов](\u002Fdocs\u002Fentities\u002Fdepartments\u002Flist) — GET-запрос для простых фильтров через query-параметры\n- [Поля отдела](\u002Fdocs\u002Fentities\u002Fdepartments\u002Ffields) — какие поля доступны для фильтрации\n- [Синтаксис фильтрации](\u002Fdocs\u002Ffiltering)\n- [Batch](\u002Fdocs\u002Fbatch) — объединение нескольких запросов\n","\n## Поля отдела\n\n`GET \u002Fv1\u002Fdepartments\u002Ffields`\n\nВозвращает справочник полей отдела с типами и признаком «только для чтения», а также список операций, доступных в [`POST \u002Fv1\u002Fbatch`](\u002Fdocs\u002Fbatch).\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002Ffields\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002Ffields\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002Ffields', {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data } = await res.json()\nconsole.log('Полей:', Object.keys(data.fields).length)\nconsole.log('Доступные batch-операции:', data.batch)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdepartments\u002Ffields', {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | RO | Описание |\n|------|-----|:--:|---------|\n| `id` | number | да | Идентификатор отдела |\n| `name` | string | | Название отдела |\n| `parentId` | number | | ID родительского отдела. Для отдела верхнего уровня указывается `1` (виртуальный корень дерева). Источник: [`GET \u002Fv1\u002Fdepartments`](.\u002Flist.md) |\n| `headId` | number | | ID руководителя отдела. Источник: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers) |\n| `sort` | number | | Порядок отдела среди соседей (целое число, по возрастанию) |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"fields\": {\n      \"id\": { \"type\": \"number\", \"readonly\": true },\n      \"name\": { \"type\": \"string\", \"readonly\": false },\n      \"parentId\": { \"type\": \"number\", \"readonly\": false },\n      \"headId\": { \"type\": \"number\", \"readonly\": false },\n      \"sort\": { \"type\": \"number\", \"readonly\": false }\n    },\n    \"batch\": [\"create\", \"update\", \"delete\"]\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n403 — нет скоупа:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"SCOPE_DENIED\",\n    \"message\": \"This endpoint requires 'department' scope\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `department` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Смотрите также\n\n- [Создать отдел](\u002Fdocs\u002Fentities\u002Fdepartments\u002Fcreate) — какие поля передавать\n- [Обновить отдел](\u002Fdocs\u002Fentities\u002Fdepartments\u002Fupdate) — какие поля можно изменять\n- [Список отделов](\u002Fdocs\u002Fentities\u002Fdepartments\u002Flist) — фильтрация по этим полям\n- [Batch](\u002Fdocs\u002Fbatch) — массовые операции `create`, `update`, `delete`\n- [Entity API](\u002Fdocs\u002Fentity-api) — select для выборки нужных полей\n"]