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

Поля узла оргструктуры

GET /v1/humanresources/nodes/fields

Возвращает справочник полей узла организационной структуры: тип значения, признак «только чтение», приём поля лишь при создании, обязательность и допустимые значения.

Примеры

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

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

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

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

const { success, data } = await res.json()
console.log('Полей:', Object.keys(data.fields).length)

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

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

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

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.fields object Справочник полей узла. Ключ — имя поля в camelCase, значение — его описание
data.fields.<имя>.type string Тип значения поля: number, string или datetime
data.fields.<имя>.readonly boolean true — поле заполняется системой, при создании и обновлении отклоняется с 400 READONLY_FIELD
data.fields.<имя>.createOnly boolean Присутствует у полей, которые принимаются только при создании узла. В запросе на обновление такое поле отклоняется с 400 READONLY_FIELD
data.fields.<имя>.required boolean Присутствует у полей, обязательных при создании
data.fields.<имя>.enum array Список допустимых значений поля. Каждый элемент несёт value для передачи в запросе, английскую подпись label и русскую labelRu
data.batch array Операции узла, доступные в пакетном вызове: create, update

Справочник описывает двенадцать полей:

Поле Тип RO Описание
id number да Идентификатор узла
type string Тип узла. Обязателен при создании и принимается только там. Допустимые значения перечислены в enum: DEPARTMENT — отдел, TEAM — команда
name string Название узла. Обязательно при создании
structureId number да Идентификатор структуры, к которой относится узел
parentId number Идентификатор родительского узла. Принимается только при создании. Список идентификаторов: GET /v1/humanresources/nodes?type=DEPARTMENT
description string Описание узла
accessCode string да Код доступа узла
userCount number да Число сотрудников в узле
colorName string Название цвета узла
xmlId string да Внешний идентификатор узла
createdAt datetime да Дата создания узла
updatedAt datetime да Дата последнего изменения узла

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

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true },
      "type": {
        "type": "string",
        "readonly": false,
        "createOnly": true,
        "required": true,
        "enum": [
          { "value": "DEPARTMENT", "label": "Department", "labelRu": "Отдел" },
          { "value": "TEAM", "label": "Team", "labelRu": "Команда" }
        ]
      },
      "name": { "type": "string", "readonly": false, "required": true },
      "structureId": { "type": "number", "readonly": true },
      "parentId": { "type": "number", "readonly": false, "createOnly": true },
      "description": { "type": "string", "readonly": false },
      "accessCode": { "type": "string", "readonly": true },
      "userCount": { "type": "number", "readonly": true },
      "colorName": { "type": "string", "readonly": false },
      "xmlId": { "type": "string", "readonly": true },
      "createdAt": { "type": "datetime", "readonly": true },
      "updatedAt": { "type": "datetime", "readonly": true }
    },
    "batch": ["create", "update"]
  }
}

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

403 — нет скоупа:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'humanresources' scope"
  }
}

Ошибки

HTTP Код Описание
403 SCOPE_DENIED Ключу не хватает скоупа humanresources
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 TOKEN_MISSING У API-ключа не настроены токены Битрикс24

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

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

Признак createOnly отличается от readonly. Отказ в обоих случаях приходит с одним кодом 400 READONLY_FIELD, поэтому отличить «поле нельзя менять после создания» от «поле нельзя задать вовсе» можно только по этому справочнику.

Набор полей не зависит от портала. Ответ собирается из описания сущности на стороне платформы Вайбкод, у портала он не запрашивается. Поэтому состав полей, их типы и значения enum одинаковы на всех порталах и не меняются при недоступности Битрикс24.

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