Для 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 — личный ключ
curl "https://vibecode.bitrix24.tech/v1/humanresources/nodes/17/children" \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth-приложение
curl "https://vibecode.bitrix24.tech/v1/humanresources/nodes/17/children" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN"
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-приложение
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, если изменений не было |
Пример ответа
{
"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 не является положительным целым числом:
{
"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, у которого есть свои потомки.