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

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

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

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

Список узлов

GET /v1/humanresources/nodes

Возвращает список узлов организационной структуры портала одного типа — отделов или команд — с постраничной выдачей.

Параметры

Параметр Тип Обяз. Описание
type (query) string да Тип узлов в выдаче: DEPARTMENT (отдел) или TEAM (команда). Без параметра возвращается 400 MISSING_REQUIRED_PARAMS
limit (query) number нет Количество записей на странице
offset (query) number нет Смещение от начала выборки для постраничной выдачи

Если под выбранный тип попадает больше записей, чем limit, в meta.hasMore приходит true. Чтобы получить следующую страницу, повторите запрос с увеличенным offset (offset = offset + limit), пока hasMore не станет false. meta.total присутствует только когда Битрикс24 сообщил общее количество. При неизвестном количестве ориентируйтесь на meta.hasMore.

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/humanresources/nodes?type=DEPARTMENT" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/humanresources/nodes?type=DEPARTMENT" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/humanresources/nodes?type=DEPARTMENT', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Найдено ${meta.total} отделов`)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/humanresources/nodes?type=DEPARTMENT', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data array Массив узлов
data[].id number Идентификатор узла
data[].name string Название узла
data[].type string Тип узла: DEPARTMENT или TEAM
data[].structureId number Идентификатор структуры, к которой относится узел
data[].parentId number Идентификатор родительского узла. У корневого узла равен 0
data[].description string | null Описание узла. null, если описание не задано
data[].accessCode string Код доступа узла, например D185 или SN23. Префикс не определяется типом узла, а числовая часть может не совпадать с id — берите значение из ответа
data[].userCount number Число сотрудников в узле
data[].colorName string | null Название цвета узла. null, если цвет не задан
data[].xmlId string | null Внешний идентификатор узла. null, если не задан
data[].createdAt string | null Дата создания (ISO 8601). null для узлов, созданных без отметки времени
data[].updatedAt string | null Дата последнего изменения (ISO 8601). null, если изменений не было
meta.total number (optional) Общее количество узлов выбранного типа. Поле отсутствует, если Битрикс24 не сообщил количество
meta.hasMore boolean Есть ли ещё записи за пределами limit

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

JSON 
{
  "success": true,
  "data": [
    {
      "id": 17,
      "name": "Головной офис",
      "type": "DEPARTMENT",
      "structureId": 1,
      "parentId": 0,
      "description": null,
      "accessCode": "D185",
      "userCount": 0,
      "colorName": null,
      "xmlId": null,
      "createdAt": null,
      "updatedAt": null
    },
    {
      "id": 23,
      "name": "Отдел продаж",
      "type": "DEPARTMENT",
      "structureId": 1,
      "parentId": 17,
      "description": "Прямые продажи",
      "accessCode": "SN23",
      "userCount": 2,
      "colorName": null,
      "xmlId": null,
      "createdAt": null,
      "updatedAt": null
    }
  ],
  "meta": {
    "total": 2,
    "hasMore": false
  }
}

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

400 — не передан обязательный параметр type:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_PARAMS",
    "message": "GET /v1/humanresources/nodes requires query parameters: type. Example: GET /v1/humanresources/nodes?type=..."
  }
}

Ошибки

HTTP Код Описание
400 MISSING_REQUIRED_PARAMS Не передан обязательный параметр type
422 BITRIX_ERROR Передан фильтр по полю узла — перечисление поддерживается только по type
403 SCOPE_DENIED Ключу не хватает скоупа humanresources
401 TOKEN_MISSING У API-ключа не настроены токены Битрикс24

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

Известные особенности

Перечисление только по типу. Выборку нельзя сузить по произвольному полю узла. Запрос с filter[name] или filter[parentId] возвращает 422 BITRIX_ERROR с пояснением о нераспознанном выражении фильтра. Единственный способ ограничить выдачу — указать type и листать страницы через limit и offset. Чтобы найти узлы по подстроке названия и при необходимости ограничить поиск поддеревом через parentId, используйте поиск узлов.

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