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

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

Действия над существующим узлом организационной структуры: получение дочерних узлов, общий счётчик, перемещение в дереве и управление связанными средствами коммуникации.

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

Дочерние узлы

GET /v1/humanresources/nodes/:id/children

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

Общий параметр filter этим эндпоинтом не применяется. По умолчанию API сохраняет прежний ответ HTTP 200 и прежние данные, добавляет заголовок Warning: 299 - "filter is not supported on this endpoint and was ignored", а сервер фиксирует использование неподдерживаемого фильтра в журнале.

Параметры

Параметр Тип Обяз. Описание
Параметрid (path) Типnumber Обяз.да ОписаниеИдентификатор родительского узла. Список узлов: GET /v1/humanresources/nodes?type=DEPARTMENT

Примеры

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

Terminal
curl "https://vibecode.bitrix24.tech/v1/humanresources/nodes/17/children" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal
curl "https://vibecode.bitrix24.tech/v1/humanresources/nodes/17/children" \
  -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/17/children', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log(`Дочерних узлов: ${data.items.length}`)

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

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

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

Поля ответа

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

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

JSON
{
  "success": true,
  "data": {
    "items": [
      {
        "id": 23,
        "name": "Отдел продаж",
        "type": "DEPARTMENT",
        "structureId": 1,
        "parentId": 17,
        "description": "Прямые продажи",
        "accessCode": "SN23",
        "userCount": 2,
        "colorName": null,
        "xmlId": null,
        "createdAt": null,
        "updatedAt": null
      }
    ]
  }
}

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

400 — :id не является положительным целым числом:

JSON
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "id must be a positive integer"
  }
}

Ошибки

HTTP Код Описание
HTTP200 КодWarning: 299 ОписаниеФильтр игнорируется по умолчанию; прежние данные сохраняются, предупреждение передаётся заголовком Warning.
HTTP400 только при включённом строгом режиме КодUNSUPPORTED_FILTER ОписаниеСерверный режим выключен по умолчанию; до его включения эндпоинт сохраняет HTTP 200 и прежние данные.
HTTP400 КодINVALID_PARAMS Описание:id не положительное целое число (0, отрицательное или нечисловое значение)
HTTP403 КодSCOPE_DENIED ОписаниеКлючу не хватает скоупа humanresources
HTTP401 КодTOKEN_MISSING ОписаниеУ API-ключа не настроены токены Битрикс24

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

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

Массив узлов вложен под data.items. В отличие от списка узлов, где записи лежат в плоском data, дочерние узлы находятся под data.items.

Возвращаются только прямые потомки. Ответ содержит узлы ровно на один уровень ниже родителя. Чтобы построить полное поддерево, вызывайте эндпоинт рекурсивно для каждого узла из data.items, у которого есть свои потомки.

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