## Создать узел

`POST /v1/humanresources/nodes`

Создаёт узел организационной структуры портала Битрикс24 — отдел или команду в дереве подразделений. Тип узла задаётся полем `type`, поля передаются плоско в корне JSON без обёртки `fields`.

## Поля запроса (body)

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|---------|
| `type` | string | да | Тип узла: `DEPARTMENT` (отдел) или `TEAM` (команда) |
| `name` | string | да | Название узла |
| `parentId` | number | нет | Идентификатор родительского узла в дереве. Список: `GET /v1/humanresources/nodes` |
| `description` | string | нет | Описание узла |
| `colorName` | string | нет | Код цвета узла, например `blue` или `AZURE` |
| `userIds` | object | нет | Участники по ролям сразу при создании: `{ "MEMBER_HEAD": [1], "MEMBER_EMPLOYEE": [2, 3] }`. Ключ — роль, значение — массив идентификаторов (не плоский массив, в отличие от [добавления участников](/docs/humanresources/members/add)) |
| `moveUsersToNode` | boolean | нет | Перенести сотрудников из `userIds` в новый узел из прежних. По умолчанию `false` |
| `createChat` | boolean | нет | Создать групповой чат для узла. По умолчанию `false` |
| `bindingChatIds` | number[] | нет | Идентификаторы существующих чатов для привязки к узлу |
| `createChannel` | boolean | нет | Создать канал для узла. По умолчанию `false` |
| `bindingChannelIds` | number[] | нет | Идентификаторы существующих каналов для привязки |
| `createCollab` | boolean | нет | Создать совместное пространство для узла. По умолчанию `false` |
| `bindingCollabIds` | number[] | нет | Идентификаторы существующих совместных пространств для привязки |
| `id` | number | RO | Идентификатор узла, присваивается при создании |
| `structureId` | number | RO | Идентификатор структуры, к которой относится узел |
| `accessCode` | string | RO | Код доступа узла, генерируется системой (например, `SN39`) |
| `userCount` | number | RO | Количество сотрудников в узле |
| `xmlId` | string | RO | Внешний идентификатор узла |
| `createdAt` | datetime | RO | Дата создания |
| `updatedAt` | datetime | RO | Дата последнего изменения |

## Примеры

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

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/humanresources/nodes" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "DEPARTMENT",
    "name": "Отдел продаж",
    "parentId": 1,
    "description": "Менеджеры активных продаж",
    "colorName": "blue"
  }'
```

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

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/humanresources/nodes" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "DEPARTMENT",
    "name": "Отдел продаж",
    "parentId": 1,
    "description": "Менеджеры активных продаж",
    "colorName": "blue"
  }'
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/humanresources/nodes', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'DEPARTMENT',
    name: 'Отдел продаж',
    parentId: 1,
    description: 'Менеджеры активных продаж',
    colorName: 'blue',
  }),
})

const { success, data } = await res.json()
console.log('Node ID:', data.id)
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/humanresources/nodes', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'DEPARTMENT',
    name: 'Отдел продаж',
    parentId: 1,
    description: 'Менеджеры активных продаж',
    colorName: 'blue',
  }),
})

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

## Поля ответа

Возвращается полная запись созданного узла.

| Поле | Тип | Описание |
|------|-----|---------|
| `id` | number | Идентификатор созданного узла |
| `name` | string | Название узла |
| `type` | string | Тип узла: `DEPARTMENT` или `TEAM` |
| `structureId` | number | Идентификатор структуры, к которой относится узел |
| `parentId` | number | Идентификатор родительского узла |
| `description` | string | Описание узла |
| `accessCode` | string | Код доступа узла, сгенерированный системой |
| `userCount` | number | Количество сотрудников в узле. У нового узла — `0` |
| `colorName` | string | Цвет узла |
| `xmlId` | string | Внешний идентификатор узла |
| `createdAt` | datetime | Дата создания |
| `updatedAt` | datetime | Дата последнего изменения |
| `members` | array | Список участников узла. У нового узла — пустой массив |

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

```json
{
  "success": true,
  "data": {
    "id": 39,
    "name": "Отдел продаж",
    "type": "DEPARTMENT",
    "structureId": 1,
    "parentId": 1,
    "description": "Менеджеры активных продаж",
    "accessCode": "SN39",
    "userCount": 0,
    "colorName": "blue",
    "xmlId": null,
    "createdAt": "2026-06-03T13:06:45.000Z",
    "updatedAt": "2026-06-03T13:06:45.000Z",
    "members": []
  }
}
```

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

400 — не передано обязательное поле `name`:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Ошибка при валидации объекта запроса",
    "validation": [
      {
        "field": "MISSING_NAME",
        "message": "Parameter \"name\" is required."
      }
    ]
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | Не передано обязательное поле. В `error.validation` — маркер `MISSING_NAME` (отсутствует `name`) или `MISSING_TYPE` (отсутствует `type`) |
| 403 | `SCOPE_DENIED` | Ключу не хватает скоупа `humanresources` |
| 401 | `TOKEN_MISSING` | У API-ключа не настроены токены Битрикс24 |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

**Начальная настройка узла одним запросом.** Кроме базовых полей, при создании можно сразу задать состав участников по ролям (`userIds`) и средства коммуникации: создать чат, канал или совместное пространство (`createChat` / `createChannel` / `createCollab`) либо привязать существующие по идентификаторам (`bindingChatIds` / `bindingChannelIds` / `bindingCollabIds`). Эти поля опциональны — без них создаётся пустой узел.

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

- [Список узлов](/docs/humanresources/nodes/list)
- [Получить узел](/docs/humanresources/nodes/get)
- [Обновить узел](/docs/humanresources/nodes/update)
- [Поиск узлов](/docs/humanresources/nodes/search)
- [Узлы оргструктуры](/docs/humanresources/nodes)