# Календарь

Настройки календаря портала — рабочее время, выходные дни недели, праздники и рабочие субботы. Те же значения, по которым интерфейс Битрикс24 размечает нерабочие дни.

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

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

События и разделы календаря — это отдельные сущности со своим набором операций: [События календаря](/docs/entities/calendar-events) и [Разделы календаря](/docs/entities/calendar-sections). На этой странице — настройки, общие для всего портала.

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

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

Ответ содержит границы рабочего дня, выходные дни недели и списки праздников:

```json
{
  "success": true,
  "data": {
    "workTimeStart": "10",
    "workTimeEnd": "22",
    "weekHolidays": ["SA", "SU"],
    "weekStart": "MO",
    "yearHolidays": "1.01,2.01,7.01",
    "yearWorkdays": "31.12"
  }
}
```

Показаны основные поля. Полный список — [Настройки календаря](/docs/calendar/settings).

## Полный пример: рабочий ли это день

Задача, ради которой чаще всего читают настройки, — определить, рабочий ли конкретный день на портале. Ответ складывается из трёх правил: день недели, список праздников и список рабочих выходных.

```javascript
const VIBE_URL = 'https://vibecode.bitrix24.tech'
const VIBE_API_KEY = process.env.VIBE_API_KEY

// Шаг 1. Прочитать настройки портала.
const res = await fetch(`${VIBE_URL}/v1/calendar/settings`, {
  headers: { 'X-Api-Key': VIBE_API_KEY },
})
if (!res.ok) throw new Error(`Настройки недоступны: ${res.status}`)
const { data, meta } = await res.json()

// Шаг 2. Убедиться, что портал отдал полный набор, а не значения по умолчанию.
const partial = meta?.warnings?.some((w) => w.code === 'calendar_settings_partial')
if (partial) {
  throw new Error('Ключ принадлежит не сотруднику портала — читать настройки нечем')
}

// Шаг 3. Разобрать списки. День приходит и как `1.01`, и как `01.01`: формат
// зависит от языка портала, поэтому и список, и ключ приводим к одной форме.
const dayKey = (day, month) => `${Number(day)}.${Number(month)}`
const parseDays = (value) => new Set(
  value
    ? value.split(',').map((d) => {
        const [day, month] = d.trim().split('.')
        return dayKey(day, month)
      })
    : [],
)
const holidays = parseDays(data.yearHolidays)
const workdays = parseDays(data.yearWorkdays)
const weekends = new Set(data.weekHolidays)

const WEEK_CODES = ['SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA']

function isWorkingDay(date) {
  const key = dayKey(date.getDate(), date.getMonth() + 1)
  // Рабочий выходной перекрывает и выходной день недели, и праздник.
  if (workdays.has(key)) return true
  if (holidays.has(key)) return false
  return !weekends.has(WEEK_CODES[date.getDay()])
}

// Шаг 4. Применить к диапазону дат.
const start = new Date('2026-01-01')
for (let i = 0; i < 10; i += 1) {
  const day = new Date(start)
  day.setDate(start.getDate() + i)
  console.log(day.toISOString().slice(0, 10), isWorkingDay(day) ? 'рабочий' : 'нерабочий')
}

console.log('Рабочее время портала:', data.workTimeStart, '—', data.workTimeEnd)
```

Пустая строка в `yearHolidays` означает, что список праздников на портале не заполнен. В этом случае разметка опирается только на выходные дни недели.

Непустое значение, наоборот, не означает, что список заполнил администратор: у настройки есть локализованный набор по умолчанию, и на портале, где календарь ни разу не настраивали, приходит именно он. Набор по умолчанию привязан к языку портала, а не к его стране, поэтому проверяйте праздники по своим данным, а не считайте ответ подтверждённым администратором.

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

| Метод | Путь | Bitrix24 метод | Описание |
|-------|------|---------------|---------|
| GET | [`/v1/calendar/settings`](/docs/calendar/settings) | calendar.settings.get | Настройки календаря портала |

События и разделы календаря доступны как сущности — [События календаря](/docs/entities/calendar-events), [Разделы календаря](/docs/entities/calendar-sections).

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

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `WRONG_PATH` | Запрошен адрес, которого нет. В тексте ошибки указан рабочий адрес |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `calendar` |
| 422 | `BITRIX_ERROR` | Битрикс24 отклонил запрос — текст в `message` |
| 502 | `BITRIX_UNAVAILABLE` | Портал недоступен либо вернул ответ неожиданной структуры |

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

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

- [Эндпоинты раздела](/docs/calendar/endpoints)
- [События календаря](/docs/entities/calendar-events)
- [Разделы календаря](/docs/entities/calendar-sections)
- [Рабочий день](/docs/workday)