## Текущий статус `GET /v1/workday/status` Возвращает текущее состояние рабочего дня сотрудника: статус, время начала и завершения, длительность, перерывы. ## Параметры | Параметр | Тип | Обязательный | Описание | |----------|-----|--------------|---------| | `userId` | number | нет | Идентификатор сотрудника. По умолчанию — пользователь, которому принадлежат токены ключа. Чужие `userId` доступны только администраторам портала и непосредственным руководителям сотрудника — иначе Битрикс24 возвращает ошибку доступа | ## Примеры ### curl — личный ключ ```bash curl -H "X-Api-Key: YOUR_API_KEY" \ https://vibecode.bitrix24.tech/v1/workday/status ``` ### curl — статус другого сотрудника ```bash curl -H "X-Api-Key: YOUR_API_KEY" \ "https://vibecode.bitrix24.tech/v1/workday/status?userId=503" ``` ### curl — OAuth-приложение ```bash curl -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ https://vibecode.bitrix24.tech/v1/workday/status ``` ### JavaScript — личный ключ ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/workday/status', { headers: { 'X-Api-Key': 'YOUR_API_KEY' }, }) const { data } = await res.json() console.log('Статус:', data.status) console.log('Активный день:', data.active) console.log('Длительность:', data.duration) ``` ### JavaScript — статус другого сотрудника ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/workday/status?userId=503', { 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/status', { headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', }, }) const { data } = await res.json() ``` ## Поля ответа | Поле | Тип | Описание | |------|-----|---------| | `success` | boolean | `true` при успешном ответе | | `data.status` | string | Статус дня: `OPENED`, `CLOSED`, `PAUSED`, `EXPIRED` | | `data.timeStart` | string | Дата и время начала текущего или последнего дня (ISO 8601) | | `data.timeFinish` | string \| null | Дата и время завершения. `null` для незакрытого дня. Для дня в `PAUSED` — момент начала текущей паузы | | `data.duration` | string | Длительность дня в формате `HH:MM:SS` | | `data.timeLeaks` | string | Суммарная длительность пауз за день в формате `HH:MM:SS` | | `data.active` | boolean | Признак активной записи рабочего дня | | `data.ipOpen` | string | IP-адрес начала дня. Пустая строка, если день начат без фиксации IP | | `data.ipClose` | string | IP-адрес завершения дня. Пустая строка для незакрытого дня | | `data.latOpen` | number | Географическая широта точки начала. `0` — координаты не переданы | | `data.lonOpen` | number | Географическая долгота точки начала | | `data.latClose` | number | Географическая широта точки завершения | | `data.lonClose` | number | Географическая долгота точки завершения | | `data.tzOffset` | number | Смещение часового пояса сотрудника в секундах (зависит от настроек сотрудника на портале — пример `10800` соответствует UTC+3) | Когда у запрошенного сотрудника нет записи рабочего дня, в `data` присутствует только `status` — остальные поля отсутствуют. Подробнее — «Вырожденный ответ без записи дня» в «Известных особенностях». ## Возможные значения `status` | Статус | Описание | |--------|---------| | `OPENED` | Рабочий день открыт | | `CLOSED` | Рабочий день закрыт | | `PAUSED` | Рабочий день на паузе | | `EXPIRED` | Рабочий день не был закрыт до начала следующих календарных суток | ## Пример ответа ```json { "success": true, "data": { "status": "OPENED", "timeStart": "2026-05-05T09:00:00+03:00", "timeFinish": null, "duration": "04:00:00", "timeLeaks": "00:30:00", "active": true, "ipOpen": "203.0.113.10", "ipClose": "", "latOpen": 0, "lonOpen": 0, "latClose": 0, "lonClose": 0, "tzOffset": 10800 } } ``` Сотрудник без записи рабочего дня — ответ вырождается до одного поля `status`: ```json { "success": true, "data": { "status": "CLOSED" } } ``` ## Пример ответа при ошибке 403 — у ключа нет скоупа `timeman`: ```json { "success": false, "error": { "code": "SCOPE_DENIED", "message": "This endpoint requires 'timeman' scope" } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|---------| | 400 | `INVALID_PARAMS` | `userId` не является положительным целым числом | | 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` (например, нет прав на чужого `userId`) | | 429 | `RATE_LIMITED` | Превышен лимит запросов к Битрикс24 | | 502 | `BITRIX_UNAVAILABLE` | Портал Битрикс24 недоступен | Полный список общих ошибок API — [Ошибки](/docs/errors). ## Известные особенности - **Состояние после закрытия.** После закрытия дня эндпоинт продолжает возвращать сведения последнего дня (`CLOSED`, заполненный `timeFinish`) до открытия следующего — отчёт по закрытому дню доступен этим же запросом. - **Запись может быть любой давности — сверяйте `timeStart` с сегодняшней датой.** `status` и `timeStart` описывают *последнюю* запись рабочего дня сотрудника, а она может быть сколь угодно старой: Битрикс24 `timeman.status` возвращает последнюю запись независимо от её возраста. И день, `CLOSED` три года назад, и день, оставшийся `EXPIRED` (открытым и не закрытым) пять дней назад, отдаются как есть — ни один из них не означает «сегодня». У эндпоинта нет фильтра «только сегодня», поэтому, чтобы понять, относится ли день к текущей дате, сравните дату из `timeStart` с сегодняшней на своей стороне, прежде чем доверять `status`. Для командного дашборда считайте запись, у которой `timeStart` не сегодняшний, как «рабочий день сегодня не начат». - **Вырожденный ответ без записи дня.** Если у запрошенного сотрудника нет записи рабочего дня, `data` содержит только поле `status`. Остальные поля (`timeStart`, `timeFinish`, `duration` и прочие) в ответе отсутствуют, поэтому проверяйте наличие поля перед чтением. Запись отсутствует, например, у сотрудника, которому день ни разу не открывали. - **Закрытие просроченного дня.** В статусе `EXPIRED` день закрывается задним числом. Передайте в [`POST /v1/workday/close`](/docs/workday/close) параметр `time` с датой, равной дате открытия дня — это значение `timeStart` из ответа этого эндпоинта — вместе с обязательным `report`. Дата `time`, не равная дате открытия, возвращает `422`. ## Смотрите также - [Открыть рабочий день](/docs/workday/open) - [Закрыть рабочий день](/docs/workday/close) - [Поставить на паузу](/docs/workday/pause) - [Настройки учёта](/docs/workday/settings) - [История рабочего дня](/docs/workday/records) - [Рабочий день](/docs/workday)