# Рабочий день

Учёт рабочего времени сотрудника: открытие и закрытие дня, пауза, текущий статус, настройки портала и график работы.

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

[Какой ключ выбрать](#какой-ключ-выбрать) | [Быстрый старт](#быстрый-старт) | [Полный пример](#полный-пример-автоматический-учёт-рабочего-дня) | [Справочник эндпоинтов](#справочник-эндпоинтов) | [Коды ошибок](#коды-ошибок)

## Какой ключ выбрать

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

| Сценарий | Ключ | Заголовки запроса |
|---------|------|-------------------|
| Личный учёт времени, скрипт на собственном сервере | Личный API-ключ `vibe_api_…` | `X-Api-Key: vibe_api_…` |
| OAuth-приложение из каталога Вайбкод — учёт времени для каждого пользователя, установившего приложение | Ключ авторизации `vibe_app_…` | `X-Api-Key: vibe_app_…` + `Authorization: Bearer <session_token>` |

Действия фиксируются от лица владельца ключа (для личного) или пользователя сессии (для OAuth). Подробное описание форматов и получение `session_token` — [Ключи и авторизация](/docs/keys-auth).

---

## Быстрый старт

### 1. Узнайте текущий статус

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

```json
{
  "success": true,
  "data": {
    "status": "CLOSED",
    "timeStart": "2026-05-04T09:00:00+03:00",
    "timeFinish": "2026-05-04T18:00:00+03: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. Откройте рабочий день

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

### 3. Закройте день с отчётом

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/workday/close \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "report": "Закрыл 5 сделок, обработал 12 лидов" }'
```

---

## Полный пример: автоматический учёт рабочего дня

Сценарий: скрипт открывает день в 9:00, отслеживает обеденный перерыв и закрывает день в 18:00 с автоматическим отчётом.

```javascript
const VIBE_KEY = process.env.VIBE_KEY
const BASE = 'https://vibecode.bitrix24.tech/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. Узнаём текущий статус — чтобы не открывать уже открытый день
const { data: current } = await api('GET', '/workday/status')
console.log('Текущий статус:', current.status)

// 2. Открываем рабочий день, если он закрыт
if (current.status === 'CLOSED' || !current.status) {
  const { data: opened } = await api('POST', '/workday/open', {})
  console.log('День открыт в', opened.timeStart)
} else {
  console.log('День уже открыт с', current.timeStart)
}

// 3. Получаем настройки учёта на портале
const { data: settings } = await api('GET', '/workday/settings')
console.log('Допустимое начало дня до:', settings.ufTmMaxStart)
console.log('Минимальная длительность дня:', settings.ufTmMinDuration)

// 4. Уход на обед — ставим паузу
const { data: paused } = await api('POST', '/workday/pause', {})
console.log('День на паузе с', paused.timeFinish)

// ...перерыв...

// 5. Возвращаемся с обеда — продолжаем день
const { data: resumed } = await api('POST', '/workday/open', {})
console.log('День продолжен, статус:', resumed.status)

// 6. Конец рабочего дня — закрываем с отчётом
const { data: closed } = await api('POST', '/workday/close', {
  report: 'Автоматическое закрытие'
})
console.log('День закрыт, отработано:', closed.duration)
console.log('Длительность перерыва:', closed.timeLeaks)
```

---

## Справочник эндпоинтов

| Метод | Путь | Bitrix24 метод | Описание |
|-------|------|---------------|---------|
| POST | [/v1/workday/open](/docs/workday/open) | timeman.open | Открыть или продолжить рабочий день |
| POST | [/v1/workday/close](/docs/workday/close) | timeman.close | Закрыть рабочий день |
| POST | [/v1/workday/pause](/docs/workday/pause) | timeman.pause | Приостановить рабочий день |
| GET | [/v1/workday/status](/docs/workday/status) | timeman.status | Текущий статус рабочего дня |
| GET | [/v1/workday/records](/docs/workday/records) | timeman.record.list | История записей рабочего дня сотрудника |
| GET | [/v1/workday/settings](/docs/workday/settings) | timeman.settings | Настройки учёта на портале |
| GET | [/v1/workday/schedule](/docs/workday/schedule) | timeman.schedule.get | Сведения о графике работы по `id` |

**Пустой успешный результат приходит как `data: null`.** Так отвечают `open`, `close`, `pause`, `status` и `settings`, когда Битрикс24 вернул успех без значения. Служебной оболочки с полями `result`, `total` и `next` в `data` не будет — доставать значение из неё не нужно.

Форму самого значения ответ сохраняет: пустой список приходит пустым массивом, а не `null`. Так устроен `schedule` — несуществующий идентификатор графика даёт `data: []`, см. [Сведения о графике](/docs/workday/schedule). Поэтому проверяйте пустоту по форме, которую описывает страница метода, а не одним сравнением с `null`. История записей (`records`) под правило не подпадает вовсе: у неё своя постраничная выдача с `meta`.

Интерактивный переключатель методов с примерами и таблицами полей — [Эндпоинты](/docs/workday/endpoints).

---

## Коды ошибок

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | Битрикс24 вернул `INVALID_PARAMS` — нарушена валидация полей запроса |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Неверный API-ключ |
| 401 | `KEY_EXPIRED` | Срок действия API-ключа истёк |
| 401 | `TOKEN_MISSING` | Ключу не настроены OAuth-токены для портала |
| 402 | `ACCOUNT_FROZEN` | Баланс портала заморожен — пополните баланс |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `timeman` |
| 422 | `BITRIX_ERROR` | Битрикс24 отклонил запрос — текст в `message` (например, попытка закрыть уже закрытый день) |
| 429 | `RATE_LIMITED` | Превышен лимит запросов к Битрикс24 |
| 502 | `BITRIX_UNAVAILABLE` | Портал Битрикс24 недоступен |

Полный список общих ошибок API — [Ошибки](/docs/errors).

---

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

- [Ключи и авторизация](/docs/keys-auth)
- [Лимиты и оптимизация](/docs/optimization)
- [Ошибки](/docs/errors)