Отделы

Управление организационной структурой портала: создание, получение, обновление, удаление и фильтрация отделов. Отделы образуют дерево — каждый отдел кроме корневого ссылается на родительский через 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) нельзя — портал поддерживает только один корневой отдел.

headId не проверяется на существование. Bitrix24 не валидирует пользователя в headId: несуществующий userId будет принят и сохранён как руководитель отдела (висячая ссылка), запрос вернёт 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()

Поля ответа

Поле Тип Описание
id number ID созданного отдела
name string Название
parentId number ID родительского отдела
headId number ID руководителя (если указан при создании)
sort number Порядок сортировки

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

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

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

422 — не указано обязательное поле name (при валидном parentId):

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

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

Ошибки

HTTP Код Описание
422 BITRIX_ERROR Не указан name, либо попытка создать второй корневой отдел, либо parentId ссылается на несуществующий отдел. headId НЕ проверяется (несуществующий пользователь принимается)
403 SCOPE_DENIED API-ключ не имеет скоупа department
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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