## График работы

`GET /v1/workday/schedule`

Возвращает график работы по идентификатору. Параметр id обязателен. Если графика с указанным идентификатором не существует, возвращается пустой массив.

## Параметры

| Параметр | В | Тип | Обяз. | По умолч. | Описание |
|----------|---|-----|:-----:|-----------|---------|
| `id` | query | number | да | — | Идентификатор графика. Список графиков и их идентификаторы настраиваются в разделе учёта рабочего времени на портале Битрикс24 |

## Примеры

### curl — личный ключ

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.tech/v1/workday/schedule?id=1"
```

### curl — OAuth-приложение

```bash
curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  "https://vibecode.bitrix24.tech/v1/workday/schedule?id=1"
```

### JavaScript — личный ключ

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/workday/schedule?id=1',
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } },
)
const { data } = await res.json()
if (Array.isArray(data) && data.length === 0) {
  console.log('График не найден')
} else {
  console.log('График:', data.name)
  console.log('Тип:', data.scheduleType)
}
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch(
  'https://vibecode.bitrix24.tech/v1/workday/schedule?id=1',
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  },
)
const { data } = await res.json()
```

## Поля ответа

Когда график найден, `data` — объект со сведениями о графике. Когда график с указанным `id` отсутствует, `data` — пустой массив.

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | `true` при успешном ответе |
| `data` | object \| array | Объект графика или пустой массив `[]` для несуществующего идентификатора |
| `data.id` | number | Идентификатор графика |
| `data.name` | string | Название графика |
| `data.scheduleType` | string | Тип графика: `FIXED` (фиксированный), `SHIFT` (сменный), `FLEXTIME` (свободный) |
| `data.reportPeriod` | string | Периодичность отчётов: `MONTH`, `WEEK`, `TWO_WEEKS`, `QUARTER` |
| `data.reportPeriodOptions` | object | Дополнительные настройки периода отчётов (например, `startWeekDay`). Возвращается для всех значений `reportPeriod` |
| `data.calendarId` | number | Идентификатор календаря, связанного с графиком |
| `data.allowedDevices` | object | Разрешённые устройства учёта (`browser`, `mobile`). Каждое поле — boolean |
| `data.deleted` | string | `"0"` — график активен; `"1"` — график удалён |
| `data.isForAllUsers` | boolean | `true` — график применяется ко всем сотрудникам |
| `data.worktimeRestrictions` | array | Массив правил ограничений рабочего времени. Пустой массив — ограничений нет |
| `data.controlledActions` | number | Количество контролируемых действий по графику |
| `data.updatedBy` | number | Идентификатор пользователя, который последним обновил график. `0` — обновлений не было |
| `data.deletedBy` | number | Идентификатор пользователя, удалившего график. `0` — график не удалён |
| `data.deletedAt` | string | Дата и время удаления. Пустая строка — график не удалён |
| `data.createdBy` | number | Идентификатор пользователя, создавшего график. `0` — системное создание |
| `data.createdAt` | string | Дата и время создания (ISO 8601) |
| `data.shifts` | array | Массив объектов смен по графику |
| `data.shifts[].id` | number | Идентификатор смены |
| `data.shifts[].name` | string | Название смены |
| `data.shifts[].breakDuration` | number | Длительность перерыва в секундах (`3600` = 1 час) |
| `data.shifts[].workTimeStart` | number | Время начала смены в секундах от начала суток (`32400` = 09:00) |
| `data.shifts[].workTimeEnd` | number | Время завершения смены в секундах от начала суток (`64800` = 18:00) |
| `data.shifts[].workDays` | string | Дни недели цифрами 1–7, где 1 = понедельник, 7 = воскресенье. `"12345"` — будние дни |
| `data.shifts[].scheduleId` | number | Идентификатор графика, к которому привязана смена |
| `data.shifts[].deleted` | boolean | Признак удалённой смены (boolean, в отличие от строкового `data.deleted`) |
| `data.calendar` | object | Сведения о календаре графика |
| `data.calendar.id` | number | Идентификатор календаря |
| `data.calendar.name` | string | Название календаря |
| `data.calendar.parentCalendarId` | number | Идентификатор родительского календаря |
| `data.calendar.systemCode` | string | Системный код календаря |
| `data.calendar.exclusions` | array | Список исключений календаря |
| `data.scheduleViolationRules` | object | Правила нарушения графика. Поля со значением `-1` означают «параметр не задан» |

## Пример ответа

График с указанным идентификатором найден (тип `FIXED`, смена 09:00–18:00 пн-пт):

```json
{
  "success": true,
  "data": {
    "id": 9,
    "name": "Фиксированный график",
    "scheduleType": "FIXED",
    "reportPeriod": "MONTH",
    "reportPeriodOptions": { "startWeekDay": 0 },
    "calendarId": 37,
    "allowedDevices": { "browser": true, "mobile": true },
    "deleted": "0",
    "isForAllUsers": true,
    "worktimeRestrictions": [],
    "controlledActions": 3,
    "updatedBy": 0,
    "deletedBy": 0,
    "deletedAt": "",
    "createdBy": 1,
    "createdAt": "2026-05-05T11:50:40+03:00",
    "shifts": [
      {
        "id": 7,
        "name": "",
        "breakDuration": 3600,
        "workTimeStart": 32400,
        "workTimeEnd": 64800,
        "workDays": "12345",
        "scheduleId": 9,
        "deleted": false
      }
    ],
    "calendar": {
      "id": 37,
      "name": "",
      "parentCalendarId": 1,
      "systemCode": "",
      "exclusions": []
    },
    "scheduleViolationRules": {
      "id": 11,
      "scheduleId": 9,
      "entityCode": "UA",
      "maxExactStart": -1,
      "minExactEnd": -1,
      "maxOffsetStart": -1,
      "minOffsetEnd": -1,
      "relativeStartFrom": -1,
      "relativeStartTo": -1,
      "relativeEndFrom": -1,
      "relativeEndTo": -1,
      "minDayDuration": -1,
      "maxAllowedToEditWorkTime": -1,
      "maxWorkTimeLackForPeriod": -1,
      "periodTimeLackAgentId": 0,
      "maxShiftStartDelay": -1,
      "missedShiftStart": 0,
      "usersToNotify": {
        "fixedStartEnd": [],
        "fixedPerRecord": [],
        "fixedEditWorktime": [],
        "fixedPeriodic": [],
        "shiftDelay": [],
        "shiftMissedStart": []
      }
    }
  }
}
```

График с указанным идентификатором не найден:

```json
{
  "success": true,
  "data": []
}
```

## Пример ответа при ошибке

400 — параметр `id` не передан:

```json
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_PARAMS",
    "message": "id is required — the schedule id, not a user id. Bitrix24 refuses this method without it."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `MISSING_REQUIRED_PARAMS` | Не передан обязательный `id` графика |
| 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).

## Известные особенности

- **Тип поля `deleted` различается на разных уровнях ответа.** На уровне графика `data.deleted` — строка (`"0"`/`"1"`), внутри смены `data.shifts[].deleted` — boolean (`true`/`false`). При написании клиентского кода нельзя обрабатывать оба поля одинаково.

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

- [Настройки учёта](/docs/workday/settings)
- [Текущий статус](/docs/workday/status)
- [История рабочего дня](/docs/workday/records)
- [Рабочий день](/docs/workday)