Настройки календаря

GET /v1/calendar/settings

Возвращает настройки календаря портала: начало и конец рабочего дня, выходные дни недели, праздники, рабочие субботы и первый день недели. Это те же значения, по которым интерфейс Битрикс24 размечает нерабочие дни.

Параметры

Параметров нет.

Примеры

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

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

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

curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.tech/v1/calendar/settings

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/calendar/settings', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data, meta } = await res.json()

if (meta?.warnings?.some((w) => w.code === 'calendar_settings_partial')) {
  throw new Error('Ключ принадлежит не сотруднику портала — настройки недоступны')
}

const weekends = data.weekHolidays
const holidays = data.yearHolidays ? data.yearHolidays.split(',') : []
console.log('Рабочий день:', data.workTimeStart, '—', data.workTimeEnd)
console.log('Выходные дни недели:', weekends.join(', '))
console.log('Праздников в списке:', holidays.length)

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/calendar/settings', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Поля ответа

Кроме перечисленных полей ответ содержит адреса разделов для нестандартных типов календаря — по одному полю на тип, с именем вида path_to_type_location. Имена таких полей приходят в том виде, в каком их отдаёт портал, поэтому набор полей ответа не фиксирован.

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

{
  "success": true,
  "data": {
    "workTimeStart": "10",
    "workTimeEnd": "22",
    "yearHolidays": "",
    "yearWorkdays": "",
    "weekHolidays": ["SA", "SU"],
    "weekStart": "MO",
    "userNameTemplate": "#NAME# #LAST_NAME#",
    "syncByPush": "",
    "userShowLogin": "1",
    "pathToUser": "/company/personal/user/#user_id#/",
    "pathToUserCalendar": "/company/personal/user/#user_id#/calendar/",
    "pathToGroup": "/workgroups/group/#group_id#/",
    "pathToGroupCalendar": "/workgroups/group/#group_id#/calendar/",
    "pathToVr": "",
    "pathToRm": "",
    "rmIblockType": "",
    "rmIblockId": "",
    "depManagerSub": "1",
    "deniedSuperposeTypes": [],
    "pathesForSites": "",
    "pathes": [],
    "forumId": "1",
    "rmForSites": "1",
    "path_to_type_company_calendar": "/calendar/",
    "path_to_type_events": "",
    "path_to_type_location": "",
    "path_to_type_resource": ""
  }
}

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

403 — у ключа нет скоупа calendar:

{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'calendar' scope"
  }
}

Ошибки

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

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

• Сокращённый ответ у ключа внешнего пользователя. Владельцу ключа, который не является сотрудником портала, Битрикс24 отдаёт два поля — workTimeStart и workTimeEnd — со значениями по умолчанию 9 и 19 вместо настроек портала. По самим значениям отличить такой ответ от настроенного портала нельзя, поэтому в ответ добавляется meta.warnings с кодом calendar_settings_partial. Проверяйте это поле до того, как использовать границы рабочего дня. Полный набор настроек читается ключом, который принадлежит сотруднику портала.

• Значения приходят строками, а незаполненное поле — пустой строкой. Включённая настройка приходит как "1", выключенная — как пустая строка. Значений Y и N эндпоинт не возвращает, поэтому сравнение с N даст неверный результат на любом настроенном портале. Проверяйте истинность значения, а не равенство конкретной строке. Настройка, которую на портале ни разу не сохраняли, приходит логическим значением, а не строкой — обработчик должен принимать оба варианта.

• Пустой список праздников не означает, что праздников нет. Пустая строка означает, что список на портале не заполнен, а не что в году нет праздничных дней.

• Непустой список не означает, что его заполнил администратор. У полей yearHolidays и yearWorkdays три состояния, а не два: список заполнил администратор портала; список пуст; либо администратор настройки не открывал, и пришёл локализованный набор по умолчанию. Третье состояние от первого по ответу неотличимо. Набор по умолчанию выбирается по языку портала, а не по стране, и у части языков он совпадает с русским — портал другой страны на языке из этой группы вернёт российские праздники. Не размечайте по нему календарь как по подтверждённым данным.

• День приходит с ведущим нулём и без него. Один и тот же праздник выглядит как 1.01 или 01.01 в зависимости от языка портала. Сравнение с одной из форм тихо не найдёт дату: ошибки не будет, день просто окажется рабочим. Приводите к одной форме и элементы списка, и ключ, по которому ищете.

• Лимит 120 запросов в минуту на портал. Отдельный лимит именно этого эндпоинта, помимо общего лимита обращений к Битрикс24. Он существует потому, что чтение настроек на стороне Битрикс24 может дописывать служебную настройку портала, поэтому частый опрос стоит дороже обычного чтения. Настройки меняются редко — кэшируйте ответ на своей стороне вместо повторного опроса.

• Настройки относятся ко всему порталу. Ответ не зависит от того, чей календарь читается, и не содержит персональных предпочтений сотрудника.

• Часы указаны в часовом поясе портала. Поля workTimeStart и workTimeEnd — это часы, а не полное время, поэтому сравнение с меткой времени события требует приведения к часовому поясу портала.

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

• Эндпоинты раздела
• Календарь
• События календаря
• Разделы календаря