Для AI-агентов: markdown этой страницы — /docs-content/entities/departments.md индекс документации — /llms.txt

Отделы

Управление организационной структурой портала: создание, получение, обновление, удаление и фильтрация отделов. Отделы образуют дерево — каждый отдел кроме корневого ссылается на родительский через parentId, а сотрудники назначаются в отделы через справочник сотрудников.

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

Создать отдел

POST /v1/departments

Создаёт новый отдел в дереве организационной структуры портала.

Поля запроса (body)

Поле Тип Обяз. Описание
name string да Название отдела
parentId number да ID родительского отдела. Список родителей: GET /v1/departments. Для отдела верхнего уровня используйте parentId: 1
headId number нет ID руководителя отдела. Источник: GET /v1/users
sort number нет Порядок отдела среди соседей: меньшее значение — выше в списке. По умолчанию 500

Второй отдел верхнего уровня создать нельзя: портал поддерживает только один корневой отдел. Запрос без parentId или с parentId: 0 вернёт 422 BITRIX_ERROR.

headId не проверяется на существование. Несуществующий userId в headId принимается и сохраняется как руководитель отдела, запрос возвращает 201. Проверяется только parentId: несуществующий родитель — 422 BITRIX_ERROR. Перед назначением убедитесь, что пользователь существует — GET /v1/users.

Примеры

curl — личный ключ

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/departments" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Коммерческий отдел",
    "parentId": 1,
    "headId": 99,
    "sort": 500
  }'

curl — OAuth-приложение

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/departments" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Коммерческий отдел",
    "parentId": 1,
    "headId": 99,
    "sort": 500
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/departments', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Коммерческий отдел',
    parentId: 1,
    headId: 99,
    sort: 500,
  }),
})

const { success, data } = await res.json()
console.log('Department ID:', data.id)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/departments', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Коммерческий отдел',
    parentId: 1,
    headId: 99,
    sort: 500,
  }),
})

const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data object Созданный отдел
data.id number ID созданного отдела
data.name string Название
data.parentId number ID родительского отдела
data.headId number ID руководителя. Приходит, только если headId передан при создании
data.sort number Порядок сортировки

Пример ответа

JSON 
{
  "success": true,
  "data": {
    "id": 189,
    "name": "Коммерческий отдел",
    "sort": 500,
    "parentId": 1,
    "headId": 99
  }
}

Пример ответа при ошибке

422 — передан parentId, но не указано обязательное поле name:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Не введено название раздела."
  }
}

Поля проверяются по порядку. Сначала наличие parentId: без него, в том числе при пустом теле, приходит ошибка единственного корневого отдела. Затем name, и последним — существует ли родительский отдел.

Ошибки

HTTP Код Описание
422 BITRIX_ERROR Не передан parentId или передан parentId: 0 — попытка создать второй корневой отдел. Сообщение: «В структуре компании должен быть только один раздел верхнего уровня.»
422 BITRIX_ERROR Не указан name. Сообщение: «Не введено название раздела.»
422 BITRIX_ERROR parentId ссылается на несуществующий отдел. Сообщение: «Неверный раздел-родитель!»
403 SCOPE_DENIED API-ключ не имеет скоупа department
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

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