# Workday

Employee time tracking: opening and closing the day, pause, current status, Bitrix24 account settings, and work schedule.

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

[Which key to choose](#which-key-to-choose) | [Quick start](#quick-start) | [Full example](#full-example-automatic-workday-tracking) | [Endpoint reference](#endpoint-reference) | [Error codes](#error-codes)

## Which key to choose

This section works with two key types. The choice determines whose workday the action is recorded against.

| Scenario | Key | Request headers |
|---------|------|-------------------|
| Personal time tracking, a script on your own server | Personal API key `vibe_api_…` | `X-Api-Key: vibe_api_…` |
| OAuth application from the Vibecode catalog — time tracking for each user who installed the app | Authorization key `vibe_app_…` | `X-Api-Key: vibe_app_…` + `Authorization: Bearer <session_token>` |

Actions are recorded on behalf of the key owner (for a personal key) or the session user (for OAuth). For a detailed description of the formats and how to obtain a `session_token`, see [Keys and authorization](/docs/keys-auth).

---

## Quick start

### 1. Check the current status

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/workday/status
```

```json
{
  "success": true,
  "data": {
    "status": "CLOSED",
    "timeStart": "2026-05-04T09:00:00+00:00",
    "timeFinish": "2026-05-04T18:00:00+00:00",
    "duration": "08:00:00",
    "timeLeaks": "00:30:00",
    "active": true,
    "ipOpen": "203.0.113.10",
    "ipClose": "203.0.113.10",
    "latOpen": 0,
    "lonOpen": 0,
    "latClose": 0,
    "lonClose": 0,
    "tzOffset": 10800
  }
}
```

### 2. Open the workday

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

### 3. Close the day with a report

```bash
curl -X POST https://vibecode.bitrix24.com/v1/workday/close \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "report": "Closed 5 deals, processed 12 leads" }'
```

---

## Full example: automatic workday tracking

Scenario: a script opens the day at 9:00, tracks the lunch break, and closes the day at 18:00 with an automatic report.

```javascript
const VIBE_KEY = process.env.VIBE_KEY
const BASE = 'https://vibecode.bitrix24.com/v1'

async function api(method, path, body = null) {
  const opts = {
    method,
    headers: { 'X-Api-Key': VIBE_KEY }
  }
  if (body) {
    opts.headers['Content-Type'] = 'application/json'
    opts.body = JSON.stringify(body)
  }
  const res = await fetch(`${BASE}${path}`, opts)
  return res.json()
}

// 1. Check the current status — so we don't open an already-open day
const { data: current } = await api('GET', '/workday/status')
console.log('Current status:', current.status)

// 2. Open the workday if it is closed
if (current.status === 'CLOSED' || !current.status) {
  const { data: opened } = await api('POST', '/workday/open', {})
  console.log('Day opened at', opened.timeStart)
} else {
  console.log('Day already open since', current.timeStart)
}

// 3. Get the time-tracking settings on the portal
const { data: settings } = await api('GET', '/workday/settings')
console.log('Latest allowed start of day:', settings.ufTmMaxStart)
console.log('Minimum day duration:', settings.ufTmMinDuration)

// 4. Going to lunch — set a pause
const { data: paused } = await api('POST', '/workday/pause', {})
console.log('Day paused since', paused.timeFinish)

// ...break...

// 5. Back from lunch — resume the day
const { data: resumed } = await api('POST', '/workday/open', {})
console.log('Day resumed, status:', resumed.status)

// 6. End of the workday — close it with a report
const { data: closed } = await api('POST', '/workday/close', {
  report: 'Automatic closing'
})
console.log('Day closed, worked:', closed.duration)
console.log('Break duration:', closed.timeLeaks)
```

---

## Endpoint reference

| Method | Path | Bitrix24 method | Description |
|-------|------|---------------|---------|
| POST | [/v1/workday/open](/docs/workday/open) | timeman.open | Open or resume the workday |
| POST | [/v1/workday/close](/docs/workday/close) | timeman.close | Close the workday |
| POST | [/v1/workday/pause](/docs/workday/pause) | timeman.pause | Pause the workday |
| GET | [/v1/workday/status](/docs/workday/status) | timeman.status | Current workday status |
| GET | [/v1/workday/settings](/docs/workday/settings) | timeman.settings | Time-tracking settings on the portal |
| GET | [/v1/workday/schedule](/docs/workday/schedule) | timeman.schedule.get | Work schedule details by `id` |

For an interactive method switcher with examples and field tables, see [Endpoints](/docs/workday/endpoints).

---

## Error codes

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | Bitrix24 returned `INVALID_PARAMS` — request field validation failed |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not provided |
| 401 | `INVALID_API_KEY` | Invalid API key |
| 401 | `KEY_EXPIRED` | The API key has expired |
| 401 | `TOKEN_MISSING` | The key has no OAuth tokens configured for the portal |
| 402 | `ACCOUNT_FROZEN` | The portal balance is frozen — top up the balance |
| 403 | `SCOPE_DENIED` | The key lacks the `timeman` scope |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the request — text in `message` (for example, an attempt to close an already-closed day) |
| 429 | `RATE_LIMITED` | The request limit to Bitrix24 was exceeded |
| 502 | `BITRIX_UNAVAILABLE` | The Bitrix24 portal is unavailable |

For the full list of common API errors, see [Errors](/docs/errors).

---

## See also

- [Keys and authorization](/docs/keys-auth) — key types, scopes, `session_token` format.
- [Limits and optimization](/docs/optimization) — general API limits.
- [Errors](/docs/errors) — code reference and handling strategies.