## Изменить настройки контроля времени

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

Меняет настройки контроля рабочего времени для всего портала: переданные поля перезаписываются, остальные сохраняют прежние значения.

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

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

Все поля необязательные, но в теле должно быть хотя бы одно. Поля идут парами: `reportRequestType` и `reportRequestUsers`, `reportSimpleType` и `reportSimpleUsers`, `reportFullType` и `reportFullUsers`. Тип `user` передаётся вместе со своим списком в том же запросе, а список — только вместе с типом `user`.

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

## Примеры

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

```bash
curl -X PATCH "https://vibecode.bitrix24.tech/v1/workday/time-control/settings" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reportSimpleType": "user", "reportSimpleUsers": [103, 107]}'
```

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

```bash
curl -X PATCH "https://vibecode.bitrix24.tech/v1/workday/time-control/settings" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reportSimpleType": "user", "reportSimpleUsers": [103, 107]}'
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/workday/time-control/settings', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ reportSimpleType: 'user', reportSimpleUsers: [103, 107] }),
})
const { data } = await res.json()
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/workday/time-control/settings', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ reportSimpleType: 'user', reportSimpleUsers: [103, 107] }),
})
const { data } = await res.json()
```

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

Ответ — все настройки портала после записи, а не только изменённые поля. Подробное описание каждого поля — [Получить настройки контроля времени](/docs/workday/time-control-settings-list).

| Поле | Тип | Описание |
|------|-----|----------|
| `success` | boolean | `true` при успешной записи |
| `data` | object | Настройки контроля рабочего времени после записи |
| `data.active` | boolean | Включён ли контроль рабочего времени |
| `data.minimumIdleForReport` | integer | Отсутствие в минутах, начиная с которого запрашивается отчёт |
| `data.registerOffline` | boolean | Фиксировать ли, когда сотрудник не в сети |
| `data.registerIdle` | boolean | Фиксировать ли, когда сотрудник отошёл |
| `data.registerDesktop` | boolean | Фиксировать ли работу в приложении Битрикс24 для компьютера |
| `data.reportRequestType` | string | `all`, `user` или `none` |
| `data.reportRequestUsers` | integer[] \| string[] | ID сотрудников, у которых запрашивается отчёт |
| `data.reportSimpleType` | string | `all` или `user`. Записанное `none` приходит как `user` с пустым `reportSimpleUsers` |
| `data.reportSimpleUsers` | integer[] \| string[] | ID сотрудников с простым отчётом |
| `data.reportFullType` | string | `all` или `user`. Записанное `none` приходит как `user` с пустым `reportFullUsers` |
| `data.reportFullUsers` | integer[] \| string[] | ID сотрудников с полным отчётом |

ID, записанные этим методом, приходят числами. ID, сохранённые раньше другим способом, могут прийти строками, как `reportRequestUsers` в примере ниже. Сравнивайте ID после приведения к числу.

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

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

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

400 — список `reportRequestUsers` передан без `reportRequestType: "user"`:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "reportRequestUsers requires the matching type user"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | Тело пустое или не объект: `Provide at least one setting` |
| 400 | `INVALID_PARAMS` | Неизвестное поле: `Unknown setting: <поле>` |
| 400 | `INVALID_PARAMS` | Неверный тип значения: `active` и `register*` не `true` или `false`, `minimumIdleForReport` не целое число, `*Type` не `all`, `user` или `none`, `*Users` не массив положительных целых чисел |
| 400 | `INVALID_PARAMS` | Тип `user` передан без своего списка или список передан без типа `user`: `reportRequestType requires the matching users array`, `reportRequestUsers requires the matching type user` |
| 403 | `BITRIX_ACCESS_DENIED` | Владелец учётных данных не администратор портала |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ в режиме `READONLY` |
| 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).

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

- Тело проверяется целиком до записи: при ошибке в любом поле не меняется ни одна настройка, в том числе корректные поля из того же запроса.
- ID сотрудников в `*Users` не проверяются на существование: несуществующий ID сохраняется без ошибки.

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

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