#Human Resources API

Управляйте оргструктурой Битрикс24 программно: создавайте отделы и команды, перемещайте сотрудников между узлами, управляйте коммуникациями узлов и ищите сотрудников.

#Обзор

Human Resources API предоставляет доступ к оргструктуре Битрикс24 (отделы и команды). Это обёртка над Bitrix24 REST 3.0 (humanresources.*) — Vibe транслирует вызовы через /v1/humanresources/* в эргономичные REST-пути, сохраняя семантику B24.

Базовый путь: /v1/humanresources

Скоуп: humanresources — включается на странице /keys в личном кабинете.

Авторизация: заголовок X-Api-Key с вашим API-ключом. Подробнее: Ключи и авторизация.

Формат ответа: { success: true, data: ..., total?: number }. При ошибке: { success: false, error: { code, message } }.

B24-транспорт: все вызовы маршрутизируются через V3 REST (/rest/api/<userId>/<token>/<method>); в URL Vibe используются стандартные HTTP-пути.

#Типичный сценарий использования

Список оргструктуры — GET /v1/humanresources/nodes?type=DEPARTMENT — получить все отделы на портале.
Детали узла — GET /v1/humanresources/nodes/:id — получить конкретный отдел с его участниками.
Дочерние узлы — GET /v1/humanresources/nodes/:id/children — получить дочерние подразделения.
Управление участниками — POST /v1/humanresources/nodes/:id/members/add|remove|set|move — добавить/убрать сотрудников.
Поиск сотрудника — POST /v1/humanresources/employees/search — найти сотрудника по имени.

Партиция типов: каждый узел является либо DEPARTMENT (отдел), либо TEAM (команда). Параметр type обязателен во всех list- и search-вызовах на уровне узлов.

#Лимиты и пагинация

Пагинация: limit-offset; поля page (1-based) и limit (1..500, по умолчанию 50).
Параметр total в корне ответа — общее количество записей.
Максимальный limit для авто-генерированных маршрутов: 500 (валидируется entity-роутером).

#Авторизация и ошибки

Все эндпоинты требуют заголовок X-Api-Key. Получить ключ: Ключи и авторизация. Расшифровку всех кодов ошибок смотри в разделе Коды ошибок ниже и в справочнике ошибок.

#Оргструктура (узлы) — CRUD

#GET /v1/humanresources/nodes

Получить список узлов оргструктуры (отделов или команд). Параметр type обязателен.

Bitrix24 метод: humanresources.node.list

Query-параметры:

Параметр	Тип	Обяз.	По умолч.	Описание
`type`	string	да	—	`DEPARTMENT` или `TEAM`
`limit`	integer	нет	50	Число записей на странице, 1..500
`page`	integer	нет	1	Номер страницы (1-based)
`select`	string[]	нет	все поля	Выборка полей: `?select=id&select=name`
`order`	object	нет	—	Сортировка: `?order[id]=asc`
`filter`	object	нет	—	Фильтрация: `?filter[parentId]=12`

Поля ответа:

Поле	Тип	Описание
`data`	Node[]	Массив узлов
`total`	integer	Всего записей

Node — поля:

Поле	Тип	Описание
`id`	integer	Уникальный ID узла
`type`	string	`DEPARTMENT` или `TEAM`
`name`	string	Название
`structureId`	integer	ID корневой структуры
`parentId`	integer\|null	ID родительского узла
`description`	string	Описание
`accessCode`	string	Код доступа, например `DR1`
`userCount`	integer	Количество участников
`colorName`	string\|null	Цвет: `blue`, `green`, `cyan`, `orange`, `purple`, `pink`
`xmlId`	string\|null	Внешний идентификатор
`createdAt`	string	ISO datetime создания
`updatedAt`	string	ISO datetime последнего изменения

curl:

Terminal

curl -s "https://api.vibecode.bitrix24.tech/v1/humanresources/nodes?type=DEPARTMENT&limit=10" \
  -H "X-Api-Key: $VIBE_KEY"

JavaScript:

JavaScript

const res = await fetch(
  'https://api.vibecode.bitrix24.tech/v1/humanresources/nodes?type=DEPARTMENT&limit=10',
  { headers: { 'X-Api-Key': process.env.VIBE_KEY } }
)
const { data, total } = await res.json()

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

JSON

{
  "success": true,
  "data": [
    {
      "id": 1,
      "type": "DEPARTMENT",
      "name": "Engineering",
      "structureId": 1,
      "parentId": null,
      "description": "Engineering division",
      "accessCode": "DR1",
      "userCount": 42,
      "colorName": "blue",
      "xmlId": "ENG",
      "createdAt": "2025-10-15T08:30:00+00:00",
      "updatedAt": "2026-03-20T14:00:00+00:00"
    },
    {
      "id": 2,
      "type": "DEPARTMENT",
      "name": "Sales",
      "structureId": 1,
      "parentId": 1,
      "description": null,
      "accessCode": "DR2",
      "userCount": 18,
      "colorName": "green",
      "xmlId": null,
      "createdAt": "2025-10-15T09:00:00+00:00",
      "updatedAt": "2026-01-10T11:20:00+00:00"
    }
  ],
  "total": 12
}