## Получить настройки контроля времени

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

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

Требуется скоуп `timeman`. Права проверяются у владельца учётных данных: для личного ключа это владелец ключа, для ключа приложения — пользователь, чей токен сессии передан в `Authorization`. Настройки читает администратор портала, сотруднику без прав администратора приходит `403 BITRIX_ACCESS_DENIED`. Приложению Битрикс24, от имени которого работает ключ приложения, достаточно права `timeman`. Ключ `READONLY` может читать настройки. Изменение настроек — на странице [Изменить настройки контроля времени](/docs/workday/time-control-settings-update).

## Примеры

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

```bash
curl "https://vibecode.bitrix24.tech/v1/workday/time-control/settings" \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl "https://vibecode.bitrix24.tech/v1/workday/time-control/settings" \
  -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/settings', {
  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/settings', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()
```

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

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | `true` при успешном запросе |
| `data` | object | Настройки контроля рабочего времени, общие для всего портала |
| `data.active` | boolean | Включён ли контроль рабочего времени. При `false` сотруднику без подчинённых недоступны месячные отчёты на странице [Получить месячный отчёт об отсутствиях](/docs/workday/time-control-reports), в том числе его собственный |
| `data.minimumIdleForReport` | integer | Отсутствие в минутах, начиная с которого у сотрудника запрашивается отчёт. Не меньше `1` |
| `data.registerOffline` | boolean | Фиксировать ли, когда сотрудник не в сети |
| `data.registerIdle` | boolean | Фиксировать ли, когда сотрудник отошёл |
| `data.registerDesktop` | boolean | Фиксировать ли работу в приложении Битрикс24 для компьютера |
| `data.reportRequestType` | string | У кого запрашивать отчёт об отсутствии: `all` — у всех сотрудников, `user` — у сотрудников из `reportRequestUsers`, `none` — ни у кого |
| `data.reportRequestUsers` | integer[] \| string[] | ID сотрудников, у которых запрашивается отчёт. При `reportRequestType: "user"` — список ID. Элементы приходят числами или строками, в зависимости от того, как сохранена настройка: сравнивайте их после приведения к числу. Список: [Список сотрудников](/docs/entities/users/list) |
| `data.reportSimpleType` | string | Кому доступен простой отчёт — свой месячный отчёт контроля времени: `all` — всем сотрудникам, `user` — сотрудникам из `reportSimpleUsers`. `none` в ответе не приходит: такое значение хранится как `user` с пустым `reportSimpleUsers` |
| `data.reportSimpleUsers` | integer[] \| string[] | ID сотрудников с простым отчётом. При `reportSimpleType: "user"` — список ID, пустой массив значит, что простой отчёт не назначен ни одному сотруднику. При `all` — пустой массив. Элементы — числа или строки, как в `reportRequestUsers`. Список: [Список сотрудников](/docs/entities/users/list) |
| `data.reportFullType` | string | Кому доступен полный отчёт — месячные отчёты всех сотрудников: `all` — всем сотрудникам, `user` — сотрудникам из `reportFullUsers`. `none` в ответе не приходит: такое значение хранится как `user` с пустым `reportFullUsers` |
| `data.reportFullUsers` | integer[] \| string[] | ID сотрудников с полным отчётом. При `reportFullType: "user"` — список ID, пустой массив значит, что полный отчёт не назначен ни одному сотруднику. При `all` — пустой массив. Элементы — числа или строки, как в `reportRequestUsers`. Список: [Список сотрудников](/docs/entities/users/list) |

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

```json
{
  "success": true,
  "data": {
    "active": false,
    "minimumIdleForReport": 15,
    "registerOffline": true,
    "registerIdle": true,
    "registerDesktop": true,
    "reportRequestType": "user",
    "reportRequestUsers": ["1"],
    "reportSimpleType": "all",
    "reportSimpleUsers": [],
    "reportFullType": "all",
    "reportFullUsers": []
  }
}
```

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

403 — владелец учётных данных не администратор портала:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ACCESS_DENIED",
    "message": "You don't have access to user this method"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 403 | `BITRIX_ACCESS_DENIED` | Владелец учётных данных не администратор портала |
| 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-settings-update)
- [Настройки контроля времени](/docs/workday/time-control-settings)
- [Получить месячный отчёт об отсутствиях](/docs/workday/time-control-reports)
- [Объяснить отсутствие](/docs/workday/time-control-explain)
- [Рабочий день](/docs/workday)