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

Настройки контроля времени

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

Скоуп: timeman | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

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

GET /v1/workday/time-control/settings

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

Требуется скоуп timeman. Права проверяются у владельца учётных данных: для личного ключа это владелец ключа, для ключа приложения — пользователь, чей токен сессии передан в Authorization. Настройки читает администратор портала, сотруднику без прав администратора приходит 403 BITRIX_ACCESS_DENIED. Приложению Битрикс24, от имени которого работает ключ приложения, достаточно права timeman. Ключ READONLY может читать настройки. Изменение настроек — на странице Изменить настройки контроля времени.

Примеры

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

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

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

Terminal 
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 сотруднику без подчинённых недоступны месячные отчёты на странице Получить месячный отчёт об отсутствиях, в том числе его собственный
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. Элементы приходят числами или строками, в зависимости от того, как сохранена настройка: сравнивайте их после приведения к числу. Список: Список сотрудников
data.reportSimpleType string Кому доступен простой отчёт — свой месячный отчёт контроля времени: all — всем сотрудникам, user — сотрудникам из reportSimpleUsers. none в ответе не приходит: такое значение хранится как user с пустым reportSimpleUsers
data.reportSimpleUsers integer[] | string[] ID сотрудников с простым отчётом. При reportSimpleType: "user" — список ID, пустой массив значит, что простой отчёт не назначен ни одному сотруднику. При all — пустой массив. Элементы — числа или строки, как в reportRequestUsers. Список: Список сотрудников
data.reportFullType string Кому доступен полный отчёт — месячные отчёты всех сотрудников: all — всем сотрудникам, user — сотрудникам из reportFullUsers. none в ответе не приходит: такое значение хранится как user с пустым reportFullUsers
data.reportFullUsers integer[] | string[] ID сотрудников с полным отчётом. При reportFullType: "user" — список ID, пустой массив значит, что полный отчёт не назначен ни одному сотруднику. При all — пустой массив. Элементы — числа или строки, как в reportRequestUsers. Список: Список сотрудников

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

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 — Ошибки.

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