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

`GET /v1/workday/time-control/users`

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

Требуется скоуп `timeman`. Приложению Битрикс24, от имени которого работает ключ приложения, нужны права `timeman` и `department`: метод дополнительно читает подразделение. Администратор получает сотрудников любого подразделения, руководитель — сотрудников своих подразделений, а по остальным пустой массив, сотрудник без подчинённых подразделений — только себя при любом существующем `departmentId`. Идентификаторы из ответа подходят для `userId` в [месячном отчёте](/docs/workday/time-control-reports). Ключ READONLY может читать список.

## Параметры

| Параметр | Тип | Обяз. | По умолч. | Описание |
|----------|-----|:-----:|-----------|----------|
| `departmentId` (query) | integer | да | — | ID подразделения, положительное целое. Список: [`GET /v1/departments`](/docs/entities/departments/list). Подразделения, которыми руководит владелец учётных данных, а для администратора все подразделения портала, — поле `departments` на странице [Получить настройки отчёта контроля времени](/docs/workday/time-control-report-settings) |

## Примеры

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

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

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

```bash
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` в отчёте на странице [Получить месячный отчёт об отсутствиях](/docs/workday/time-control-reports) |
| `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 — [Ошибки](/docs/errors).

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

- [Получить месячный отчёт об отсутствиях](/docs/workday/time-control-reports)
- [Настройки контроля времени](/docs/workday/time-control-settings)
- [Объяснить отсутствие](/docs/workday/time-control-explain)
- [Отделы](/docs/entities/departments)
- [Рабочий день](/docs/workday)