لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/workday/time-control-settings.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Time-control settings

Time-control settings shared by all employees of the Bitrix24 account: whether time control is on, who is asked for an absence report, and who can access monthly reports.

Scope: timeman | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

Get time-control settings

GET /v1/workday/time-control/settings

Returns the time-control settings shared by all employees of the Bitrix24 account. Call it before updating the settings to read the current values.

Requires the timeman scope. Bitrix24 checks the credential owner's permissions: for a personal key, that is the key owner; for an app key, the user whose session token is passed in Authorization. A Bitrix24 account administrator can read the settings; an employee without administrator permissions gets 403 BITRIX_ACCESS_DENIED. The Bitrix24 application behind an app key only needs the timeman permission. A READONLY key can read the settings. Updating the settings is described on the Update time-control settings page.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/workday/time-control/settings" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

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

JavaScript — OAuth application

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

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on a successful request
Fielddata Typeobject DescriptionTime-control settings shared by the entire Bitrix24 account
Fielddata.active Typeboolean DescriptionWhether time control is enabled. When false, an employee without subordinates cannot access monthly reports on the Get the monthly absence report page, including their own
Fielddata.minimumIdleForReport Typeinteger DescriptionMinimum absence, in minutes, for which an employee is asked for a report. At least 1
Fielddata.registerOffline Typeboolean DescriptionWhether to record when an employee is offline
Fielddata.registerIdle Typeboolean DescriptionWhether to record when an employee is away
Fielddata.registerDesktop Typeboolean DescriptionWhether to record work in the Bitrix24 desktop app
Fielddata.reportRequestType Typestring DescriptionWho is asked for an absence report: all — all employees, user — employees listed in reportRequestUsers, none — nobody
Fielddata.reportRequestUsers Typeinteger[] | string[] DescriptionIDs of employees who are asked for a report. With reportRequestType: "user" — a list of IDs. Elements arrive as numbers or strings, depending on how the setting was saved: compare them after converting to a number. List: List employees
Fielddata.reportSimpleType Typestring DescriptionWho has access to the simple report — their own monthly time-control report: all — all employees, user — employees listed in reportSimpleUsers. none never arrives in the response: that value is stored as user with an empty reportSimpleUsers
Fielddata.reportSimpleUsers Typeinteger[] | string[] DescriptionIDs of employees with the simple report. With reportSimpleType: "user" — a list of IDs; an empty array means the simple report is not assigned to any employee. With all — an empty array. Elements are numbers or strings, as in reportRequestUsers. List: List employees
Fielddata.reportFullType Typestring DescriptionWho has access to the full report — the monthly reports of all employees: all — all employees, user — employees listed in reportFullUsers. none never arrives in the response: that value is stored as user with an empty reportFullUsers
Fielddata.reportFullUsers Typeinteger[] | string[] DescriptionIDs of employees with the full report. With reportFullType: "user" — a list of IDs; an empty array means the full report is not assigned to any employee. With all — an empty array. Elements are numbers or strings, as in reportRequestUsers. List: List employees

Response example

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

Error response example

403 — the credential owner is not a Bitrix24 account administrator:

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

Errors

HTTP Code Description
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe credential owner is not a portal administrator
HTTP409 CodeTIMEMAN_MODULE_NOT_ENABLED DescriptionTime Management is not available on this portal: the Time Management tool is switched off in the portal settings, or the module is not included in the plan
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a response of an unexpected shape
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeTOKEN_MISSING DescriptionAn app key was sent without a session token in Authorization: Bearer
HTTP401 CodeINVALID_SESSION DescriptionThe session token is invalid or has expired
HTTP403 CodeSCOPE_DENIED DescriptionThe key does not have the timeman scope
HTTP429 CodeRATE_LIMITED DescriptionThe general request limit was exceeded; the retry delay is in the Retry-After header

The full list of common API errors — Errors.

See also