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

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

"Workday" section endpoints

Switch between work time tracking methods. Each tab opens the corresponding endpoint page with its parameters, code examples, and real responses.

Bitrix24 API: timeman.* · Scope: timeman

Open workday

POST /v1/workday/open

Opens a new workday for the current user. For a day in the OPENED status, the current state is returned unchanged. A day in the PAUSED status is switched back to OPENED and tracking resumes. If Bitrix24 leaves the day in the EXPIRED status, no new day is opened: Vibecode returns a 409 WORKDAY_EXPIRED error with instructions for closing the expired day.

Request fields (body)

All parameters are optional. The body may be empty: {}.

Field Type Required Description
FielduserId Typenumber Requiredno DescriptionEmployee identifier. Defaults to the user who owns the key's tokens. Only Bitrix24 account administrators and the employee's direct managers can pass another employee's userId. Without those rights Bitrix24 does not return the employee's data
Fieldtime Typestring Requiredno DescriptionStart date and time in ISO 8601 format (for example 2026-05-05T09:00:00+02:00). The date must match the current date. Applied only when the day is in the CLOSED status. When this field is set, report becomes required
Fieldreport Typestring Requiredno DescriptionReason for the change. Required when time is set and for employees on a fixed work schedule
Fieldlat Typenumber Requiredno DescriptionGeographic latitude of the workday start point. Returned in the data.latOpen field of the response
Fieldlon Typenumber Requiredno DescriptionGeographic longitude of the workday start point. Returned in the data.lonOpen field of the response

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/workday/open \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/workday/open \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/open', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
const payload = await res.json()
if (!payload.success) {
  console.error('Workday was not opened:', payload.error)
} else {
  const { data } = payload
  console.log('Status:', data.status)
  console.log('Opened at:', data.timeStart)
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/open', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
const payload = await res.json()
if (!payload.success) {
  console.error('Workday was not opened:', payload.error)
} else {
  const { data } = payload
  console.log('Status:', data.status)
}

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when the opened state is successfully confirmed
Fielddata.status Typestring DescriptionOPENED for a successful response. An EXPIRED status that has not changed is returned as a 409 error
Fielddata.id Typenumber DescriptionWorkday record identifier. The same values appear in the workday history
Fielddata.timeStart Typestring DescriptionDay start date and time (ISO 8601, employee's time zone)
Fielddata.timeFinish Typestring | null DescriptionDay finish date and time. null for a day that is not closed
Fielddata.duration Typestring DescriptionDay duration in HH:MM:SS format. 00:00:00 for a newly opened day
Fielddata.timeLeaks Typestring DescriptionTotal duration of pauses for the day in HH:MM:SS format
Fielddata.active Typeboolean DescriptionWhether the workday record is active
Fielddata.ipOpen Typestring DescriptionIP address of the day start. Empty string if the day was started without recording an IP
Fielddata.ipClose Typestring DescriptionIP address of the day finish. Empty string for a day that is not closed
Fielddata.latOpen Typenumber DescriptionGeographic latitude of the start point. 0 if no coordinates were passed
Fielddata.lonOpen Typenumber DescriptionGeographic longitude of the start point. 0 if no coordinates were passed
Fielddata.latClose Typenumber DescriptionGeographic latitude of the finish point
Fielddata.lonClose Typenumber DescriptionGeographic longitude of the finish point
Fielddata.tzOffset Typenumber DescriptionEmployee's time zone offset in seconds. Depends on the employee's settings in the Bitrix24 account. The value 7200 corresponds to UTC+2

Response example

JSON 
{
  "success": true,
  "data": {
    "status": "OPENED",
    "id": 1,
    "timeStart": "2026-05-05T09:00:00+02:00",
    "timeFinish": null,
    "duration": "00:00:00",
    "timeLeaks": "00:00:00",
    "active": true,
    "ipOpen": "",
    "ipClose": "",
    "latOpen": 0,
    "lonOpen": 0,
    "latClose": 0,
    "lonClose": 0,
    "tzOffset": 7200
  }
}

Error response example

403 — the key lacks the timeman scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'timeman' scope"
  }
}

409 — the expired workday is not closed, so no new day is opened:

JSON 
{
  "success": false,
  "error": {
    "code": "WORKDAY_EXPIRED",
    "message": "The workday remains expired and a new workday was not opened.",
    "hint": "Read workday status for the same user, then close the expired workday with a time on its timeStart date and a report before retrying open."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionThe userId field is not a positive integer, or Bitrix24 rejected a request field as invalid
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP401 CodeKEY_EXPIRED DescriptionThe API key has expired
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no OAuth tokens configured for the Bitrix24 portal
HTTP402 CodeACCOUNT_FROZEN DescriptionThe portal balance is frozen
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the timeman scope
HTTP409 CodeTIMEMAN_MODULE_NOT_ENABLED DescriptionTime Management is not available on this portal: the module is not installed (not included in the plan), or the tool is switched off in portal settings. Ask a portal administrator to enable it — until then every timeman.* method answers the same way
HTTP409 CodeWORKDAY_EXPIRED DescriptionThe expired day remained EXPIRED, so no new day was opened. Get timeStart from current status, close the expired day with time on the same date and the required report, then retry opening the day
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request. The reason is in message. Possible causes: the time date does not match the current date, report is missing when time is set, the day is already in the required state
HTTP429 CodeRATE_LIMITED DescriptionThe rate limit for requests to Bitrix24 was exceeded
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionThe Bitrix24 portal is unavailable

For the full list of common API errors, see Errors.

See also