Для AI-агентов: markdown этой страницы — /docs-content/calendar.md индекс документации — /llms.txt

Календарь

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

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

Быстрый старт | Полный пример | Справочник эндпоинтов | Коды ошибок

События и разделы календаря — это отдельные сущности со своим набором операций: События календаря и Разделы календаря. На этой странице — настройки, общие для всего портала.

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

Terminal 
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"
  }
}

Показаны основные поля. Полный список — Настройки календаря.

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

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

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 calendar.settings.get Настройки календаря портала

События и разделы календаря доступны как сущности — События календаря, Разделы календаря.

Коды ошибок

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

Полный список общих ошибок API — Ошибки.

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