#Поиск узлов

POST /v1/humanresources/nodes/search

Возвращает узлы организационной структуры по фильтру с сортировкой, выбором полей и ограничением выдачи. Тип узлов задаётся внутри filter и обязателен: DEPARTMENT или TEAM.

В отличие от списка узлов, поиск принимает в теле запроса сортировку order, проекцию полей select и ограничение limit. Список перечисляет узлы простой выборкой по type через параметры строки запроса, поиск задаёт условия отбора телом запроса.

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

Поле Тип Обяз. Описание
filter object да Условия отбора. Поле filter.type обязательно: DEPARTMENT или TEAM
filter.type string да Тип узлов в выдаче: DEPARTMENT (отдел) или TEAM (команда)
order object нет Сортировка по полям узла, например { "id": "desc" }. Направления: asc, desc
limit number нет Максимальное число узлов в ответе
select array нет Список возвращаемых полей, например ["id", "name"]. Без параметра возвращаются все поля узла

#Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/humanresources/nodes/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "type": "DEPARTMENT" },
    "order": { "id": "desc" },
    "limit": 50
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/humanresources/nodes/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "type": "DEPARTMENT" },
    "order": { "id": "desc" },
    "limit": 50
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/humanresources/nodes/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { type: 'DEPARTMENT' },
    order: { id: 'desc' },
    limit: 50,
  }),
})

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/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { type: 'DEPARTMENT' },
    order: { id: 'desc' },
    limit: 50,
  }),
})

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 для команды)
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 Общее количество узлов, соответствующих фильтру
meta.hasMore boolean Есть ли ещё записи за пределами limit
meta.durationMs number Длительность обработки запроса в миллисекундах

При наличии select в ответе остаются только перечисленные поля узла.

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

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,
    "durationMs": 1609
  }
}

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

400 — поле type передано вне filter или отсутствует:

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

#Ошибки

HTTP Код Описание
400 INVALID_PARAMS Поле type отсутствует или передано вне объекта filter — в error.validation приходит запись MISSING_TYPE
403 SCOPE_DENIED Ключу не хватает скоупа humanresources
401 TOKEN_MISSING У API-ключа не настроены токены Битрикс24

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

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

Тип задаётся внутри filter. Поле type обязательно и принимается только внутри объекта filter. Если передать type на верхнем уровне тела запроса или опустить его, ответ — 400 INVALID_PARAMS, а в error.validation приходит запись с полем MISSING_TYPE. Это отличается от списка узлов, где type передаётся параметром строки запроса.

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