#Подчинённые сотрудника

GET /v1/humanresources/employees/:id/subordinates

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

#Параметры

Параметр Тип Обяз. Описание
id (path) number да Идентификатор сотрудника (userId). Поиск: POST /v1/humanresources/employees/search

#Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/humanresources/employees/1/subordinates" \
  -H "X-Api-Key: YOUR_API_KEY"

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

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

const { success, data } = await res.json()
console.log(`Руководит ${data.departments.length} узлами`)

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

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

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

#Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.userId number Идентификатор сотрудника, чьи подчинённые запрошены
data.departments array Узлы, где сотрудник назначен руководителем. Пустой, если таких узлов нет
data.departments[].nodeId number Идентификатор узла. Получить узел: GET /v1/humanresources/nodes/:id
data.departments[].name string Название узла
data.departments[].role string Роль сотрудника в узле в краткой форме: HEAD (руководитель), без префикса MEMBER_
data.departments[].subordinatesCount number Число подчинённых в этом узле

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

JSON 
{
  "success": true,
  "data": {
    "userId": 1,
    "departments": [
      {
        "nodeId": 9,
        "name": "Подразделение",
        "role": "HEAD",
        "subordinatesCount": 0
      },
      {
        "nodeId": 23,
        "name": "Отдел продаж",
        "role": "HEAD",
        "subordinatesCount": 1
      }
    ]
  }
}

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

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

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

#Ошибки

HTTP Код Описание
400 INVALID_PARAMS id не является положительным целым числом (нечисловой, 0 или отрицательный)
403 SCOPE_DENIED Ключу не хватает скоупа humanresources
401 TOKEN_MISSING У API-ключа не настроены токены Битрикс24

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

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

Имя поля в ответе отличается от параметра запроса. В пути запроса сотрудник задаётся сегментом :id, а в ответе тот же сотрудник возвращается под полем data.userId. На вход — id, на выход — userId.

В выдачу попадают только узлы, где сотрудник — руководитель. Массив data.departments содержит узлы, в которых у сотрудника роль HEAD. Если сотрудник не руководит ни одним узлом, массив приходит пустым. Узел остаётся в выдаче даже когда subordinatesCount равен 0 — то есть сотрудник назначен руководителем, но подчинённых в узле пока нет.

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