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

Список сотрудников подразделения

GET /v1/workday/time-control/users

Возвращает список сотрудников подразделения для контроля рабочего времени. Состав списка зависит от роли владельца учётных данных в Битрикс24.

Требуется скоуп timeman. Приложению Битрикс24, от имени которого работает ключ приложения, нужны права timeman и department: метод дополнительно читает подразделение. Администратор получает сотрудников любого подразделения, руководитель — сотрудников своих подразделений, а по остальным пустой массив, сотрудник без подчинённых подразделений — только себя при любом существующем departmentId. Идентификаторы из ответа подходят для userId в месячном отчёте. Ключ READONLY может читать список.

Параметры

Параметр Тип Обяз. По умолч. Описание
departmentId (query) integer да — ID подразделения, положительное целое. Список: GET /v1/departments. Подразделения, которыми руководит владелец учётных данных, а для администратора все подразделения портала, — поле departments на странице Получить настройки отчёта контроля времени

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/workday/time-control/users?departmentId=12" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/workday/time-control/users?departmentId=12" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/workday/time-control/users?departmentId=12', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})
const { data } = await res.json()

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/workday/time-control/users?departmentId=12', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Поля ответа

Поле Тип Описание
success boolean true при успешном запросе
data array Сотрудники самого подразделения, без вложенных подразделений, по возрастанию id. Руководителю по подразделению, которым он не руководит, приходит пустой массив. Для сотрудника без подчинённых подразделений — один элемент, он сам
data[].id integer ID сотрудника. Подходит для userId в отчёте на странице Получить месячный отчёт об отсутствиях
data[].name string Имя и фамилия сотрудника
data[].firstName string | null Имя
data[].lastName string | null Фамилия
data[].workPosition string | null Должность
data[].avatar string | null Адрес фотографии профиля размером 100×100 пикселей
data[].personalGender string Пол: M или F. Если пол в профиле не указан, приходит F
data[].lastActivityDate string | null Время последней активности на портале в формате ISO 8601 с часовым поясом
data[].active boolean Активен ли сотрудник. Приходит только в ответе сотруднику без подчинённых подразделений

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

Ответ администратору или руководителю:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 103,
      "name": "Anna Smith",
      "firstName": "Anna",
      "lastName": "Smith",
      "workPosition": "Manager",
      "avatar": null,
      "personalGender": "F",
      "lastActivityDate": "2026-10-07T20:08:16+03:00"
    },
    {
      "id": 105,
      "name": "John Brown",
      "firstName": "John",
      "lastName": "Brown",
      "workPosition": null,
      "avatar": null,
      "personalGender": "M",
      "lastActivityDate": null
    }
  ]
}

Ответ сотруднику без подчинённых подразделений — один элемент с полем active:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 107,
      "active": true,
      "name": "Maria Lee",
      "firstName": "Maria",
      "lastName": "Lee",
      "workPosition": null,
      "avatar": null,
      "personalGender": "F",
      "lastActivityDate": "2026-10-07T23:45:08+03:00"
    }
  ]
}

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

404 — подразделения с таким departmentId нет:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Department not found"
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS departmentId не передан или не положительное целое число
404 ENTITY_NOT_FOUND Подразделения с таким departmentId нет
403 BITRIX_ACCESS_DENIED У приложения Битрикс24, от имени которого работает ключ приложения, нет права department
409 TIMEMAN_MODULE_NOT_ENABLED Учёт рабочего времени недоступен на портале: инструмент «Рабочее время и отчёты» выключен в настройках портала или модуль не входит в тариф
502 BITRIX_UNAVAILABLE Битрикс24 недоступен или вернул ответ неожиданной формы
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 TOKEN_MISSING Ключ приложения передан без токена сессии в Authorization: Bearer
401 INVALID_SESSION Токен сессии неверный или истёк
403 SCOPE_DENIED У ключа нет скоупа timeman
429 RATE_LIMITED Превышен общий лимит запросов, срок повтора — в заголовке Retry-After

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

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