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

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

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

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

- [Узлы оргструктуры](/docs/humanresources/nodes) — создание, чтение, изменение, перечисление и поиск отделов и команд (5 эндпоинтов).
- [Операции над узлами](/docs/humanresources/node-operations) — дочерние узлы, счётчик, перемещение в дереве, средства коммуникации (5 эндпоинтов).
- [Участники узлов](/docs/humanresources/members) — добавление, удаление, перемещение и полная замена состава с ролями (4 эндпоинта).
- [Сотрудники](/docs/humanresources/employees) — поиск по имени, подчинённые, количество, вхождение в несколько подразделений (4 эндпоинта).

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

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

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

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

```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 эндпоинтов раздела. Ссылки ведут на страницы с параметрами, примерами и кодами ошибок.

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

| Метод | Путь | Bitrix24 метод | Описание |
|-------|------|---------------|---------|
| GET | [`/v1/humanresources/nodes`](/docs/humanresources/nodes/list) | humanresources.node.list | Список узлов выбранного типа |
| GET | [`/v1/humanresources/nodes/:id`](/docs/humanresources/nodes/get) | humanresources.node.get | Узел с составом участников |
| POST | [`/v1/humanresources/nodes`](/docs/humanresources/nodes/create) | humanresources.node.add | Создать отдел или команду |
| PATCH | [`/v1/humanresources/nodes/:id`](/docs/humanresources/nodes/update) | humanresources.node.edit | Изменить узел |
| POST | [`/v1/humanresources/nodes/search`](/docs/humanresources/nodes/search) | humanresources.node.search | Поиск узлов по названию |

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

| Метод | Путь | Bitrix24 метод | Описание |
|-------|------|---------------|---------|
| GET | [`/v1/humanresources/nodes/:id/children`](/docs/humanresources/node-operations/children) | humanresources.node.children | Дочерние узлы |
| GET | [`/v1/humanresources/nodes/count`](/docs/humanresources/node-operations/count) | humanresources.node.count | Количество узлов по типам |
| POST | [`/v1/humanresources/nodes/:id/move`](/docs/humanresources/node-operations/move) | humanresources.node.move | Переместить узел в дереве |
| GET | [`/v1/humanresources/nodes/:id/communications`](/docs/humanresources/node-operations/communications-get) | humanresources.node.communication.list | Средства коммуникации узла |
| PATCH | [`/v1/humanresources/nodes/:id/communications`](/docs/humanresources/node-operations/communications-set) | humanresources.node.communication.edit | Настроить средства коммуникации |

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

| Метод | Путь | Bitrix24 метод | Описание |
|-------|------|---------------|---------|
| POST | [`/v1/humanresources/nodes/:id/members/add`](/docs/humanresources/members/add) | humanresources.node.member.add | Добавить участников |
| POST | [`/v1/humanresources/nodes/:id/members/remove`](/docs/humanresources/members/remove) | humanresources.node.member.remove | Удалить участников |
| POST | [`/v1/humanresources/nodes/:id/members/move`](/docs/humanresources/members/move) | humanresources.node.member.move | Переместить участников |
| POST | [`/v1/humanresources/nodes/:id/members/set`](/docs/humanresources/members/set) | humanresources.node.member.set | Заменить состав |

**Сотрудники:**

| Метод | Путь | Bitrix24 метод | Описание |
|-------|------|---------------|---------|
| POST | [`/v1/humanresources/employees/search`](/docs/humanresources/employees/search) | humanresources.employee.search | Поиск сотрудников по имени |
| GET | [`/v1/humanresources/employees/:id/subordinates`](/docs/humanresources/employees/subordinates) | humanresources.employee.subordinates | Подчинённые сотрудника |
| GET | [`/v1/humanresources/employees/count`](/docs/humanresources/employees/count) | humanresources.employee.count | Количество сотрудников |
| POST | [`/v1/humanresources/employees/multidepartment`](/docs/humanresources/employees/multidepartment) | humanresources.employee.multidepartment | Сотрудники из нескольких отделов |

## Коды ошибок

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

| Код | HTTP | Описание |
|-----|------|----------|
| `MISSING_REQUIRED_PARAMS` | 400 | Не передан обязательный параметр `type` при перечислении узлов |
| `INVALID_PARAMS` | 400 | Невалидный `:id` в ручных операциях (`id must be a positive integer`) или нарушена валидация тела запроса |
| `ENTITY_NOT_FOUND` | 404 | Узел с указанным `id` не найден |
| `NOT_FOUND` | 404 | Неизвестная операция участника в пути (допустимы `add`, `remove`, `move`, `set`) |
| `BITRIX_ERROR` | 422 | Передан неподдерживаемый фильтр при перечислении узлов |

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

| Код | HTTP | Описание |
|-----|------|----------|
| `SCOPE_DENIED` | 403 | У ключа нет скоупа `humanresources` |
| `TOKEN_MISSING` | 401 | У API-ключа не настроены токены Битрикс24 |
| `BITRIX_ACCESS_DENIED` | 403 | Недостаточно прав на портале Битрикс24 |
| `BITRIX_UNAVAILABLE` | 502 | Портал Битрикс24 недоступен |

Полный справочник общих ошибок — [Ошибки](/docs/errors).

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

- [Лимиты и оптимизация](/docs/optimization)
- [Batch-запросы](/docs/batch)