#Управление персоналом

Организационная структура портала Битрикс24: отделы и команды, их участники и сотрудники. Через API можно строить и менять дерево подразделений, управлять составом узлов и искать сотрудников — без обращения к интерфейсу портала.

Скоуп: humanresources | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

#Разделы документации

• Узлы оргструктуры — создание, чтение, изменение, перечисление и поиск отделов и команд (5 эндпоинтов).
• Операции над узлами — дочерние узлы, счётчик, перемещение в дереве, средства коммуникации (5 эндпоинтов).
• Участники узлов — добавление, удаление, перемещение и полная замена состава с ролями (4 эндпоинта).
• Сотрудники — поиск по имени, подчинённые, количество, вхождение в несколько подразделений (4 эндпоинта).

#Что важно знать сразу

1. Узел — это отдел или команда. Тип задаётся значением type: DEPARTMENT (отдел) или TEAM (команда). Параметр type обязателен при перечислении (список узлов) и при создании.
2. Удаление узлов через API не выполняется. В разделе нет эндпоинта удаления узла — дерево меняется созданием, изменением и перемещением узлов.
3. Роли участников зависят от типа узла. Для отдела — MEMBER_HEAD, MEMBER_DEPUTY_HEAD, MEMBER_EMPLOYEE. Для команды — MEMBER_TEAM_HEAD, MEMBER_TEAM_DEPUTY_HEAD, MEMBER_TEAM_EMPLOYEE. Полный перечень — в разделе Участники узлов.
4. Состав участников возвращается только при получении одного узла. Список узлов и поиск отдают сводные поля без участников — состав приходит в ответе получения узла.
5. Перечисление узлов — только по типу. Сужение выдачи по произвольному полю узла не поддерживается. Для отбора по значениям полей с сортировкой используйте поиск узлов.
6. Форма ответа зависит от эндпоинта. Перечисление узлов и поиск отдают массив в плоском data плюс meta (total, hasMore). Дочерние узлы и поиск сотрудников вкладывают массив в data.items. Счётчики и одиночные узлы возвращают объект в data. Точная форма — в секции «Поля ответа» каждого эндпоинта.

#Полный пример

Сценарий на JavaScript: создать отдел, вложить в него подотдел, назначить руководителя, посмотреть дерево и перенести подотдел на верхний уровень.

const VIBE_KEY = process.env.VIBE_KEY
const BASE = 'https://vibecode.bitrix24.tech/v1'

async function api(method, path, body = null) {
  const opts = { method, headers: { 'X-Api-Key': VIBE_KEY } }
  if (body) {
    opts.headers['Content-Type'] = 'application/json'
    opts.body = JSON.stringify(body)
  }
  const res = await fetch(`${BASE}${path}`, opts)
  if (!res.ok) throw new Error(`${method} ${path} → ${res.status}`)
  return res.json()
}

// 1. Создать отдел на верхнем уровне
const { data: parent } = await api('POST', '/humanresources/nodes', {
  type: 'DEPARTMENT',
  name: 'Отдел разработки',
  parentId: 1,
})
console.log(`Создан отдел: ${parent.id}`)

// 2. Создать подотдел внутри него
const { data: child } = await api('POST', '/humanresources/nodes', {
  type: 'DEPARTMENT',
  name: 'Группа тестирования',
  parentId: parent.id,
})

// 3. Назначить руководителя отдела
await api('POST', `/humanresources/nodes/${parent.id}/members/add`, {
  userIds: [42],
  role: 'MEMBER_HEAD',
})

// 4. Посмотреть дочерние узлы отдела
const { data: children } = await api('GET', `/humanresources/nodes/${parent.id}/children`)
console.log(`Дочерних узлов: ${children.items.length}`)

// 5. Перенести подотдел на верхний уровень
await api('POST', `/humanresources/nodes/${child.id}/move`, { parentId: 1 })
console.log('Подотдел перенесён на верхний уровень')

#Справочник эндпоинтов

Все 18 эндпоинтов раздела. Ссылки ведут на страницы с параметрами, примерами и кодами ошибок.

Узлы оргструктуры:

Операции над узлами:

Участники узлов:

Сотрудники:

#Коды ошибок

#Ошибки раздела

#Системные ошибки

Полный справочник общих ошибок — Ошибки.

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

• Лимиты и оптимизация
• Batch-запросы