## Настройки календаря `GET /v1/calendar/settings` Возвращает настройки календаря портала: начало и конец рабочего дня, выходные дни недели, праздники, рабочие субботы и первый день недели. Это те же значения, по которым интерфейс Битрикс24 размечает нерабочие дни. ## Параметры Параметров нет. ## Примеры ### curl — личный ключ ```bash curl -H "X-Api-Key: YOUR_API_KEY" \ https://vibecode.bitrix24.tech/v1/calendar/settings ``` ### curl — OAuth-приложение ```bash curl -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ https://vibecode.bitrix24.tech/v1/calendar/settings ``` ### JavaScript — личный ключ ```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-приложение ```javascript 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() ``` ## Поля ответа | Поле | Тип | Описание | |------|-----|---------| | `success` | boolean | `true` при успешном ответе | | `data.workTimeStart` | string \| number | Час начала рабочего дня | | `data.workTimeEnd` | string \| number | Час окончания рабочего дня. Дробное значение означает минуты — `23.3` читается как 23:30 | | `data.weekHolidays` | array | Выходные дни недели — `SU`, `MO`, `TU`, `WE`, `TH`, `FR`, `SA` | | `data.weekStart` | string | Первый день недели в том же формате, что `weekHolidays` | | `data.yearHolidays` | string | Праздничные дни через запятую в формате `Д.ММ` или `ДД.ММ` — `1.01,2.01,7.01` либо `01.01,02.01`. Ведущий ноль зависит от языка портала, поэтому разбирайте оба варианта. Пустая строка означает, что список не заполнен на портале | | `data.yearWorkdays` | string | Рабочие выходные через запятую в том же формате, что `yearHolidays` | | `data.userNameTemplate` | string | Шаблон отображения имени сотрудника — `#NAME# #LAST_NAME#` | | `data.userShowLogin` | string \| boolean | Показывать ли логин рядом с именем сотрудника | | `data.syncByPush` | string \| boolean | Включена ли синхронизация календаря через уведомления | | `data.depManagerSub` | string \| boolean | Видит ли руководитель подразделения календари подчинённых | | `data.deniedSuperposeTypes` | array | Типы календарей, запрещённые к наложению на личный календарь | | `data.pathToUser` | string | Шаблон адреса профиля сотрудника. Подстановка — `#user_id#` | | `data.pathToUserCalendar` | string | Шаблон адреса личного календаря сотрудника | | `data.pathToGroup` | string | Шаблон адреса рабочей группы. Подстановка — `#group_id#` | | `data.pathToGroupCalendar` | string | Шаблон адреса календаря рабочей группы | | `data.pathToVr` | string | Шаблон адреса переговорных | | `data.pathToRm` | string | Шаблон адреса бронирования ресурсов | | `data.rmIblockType` | string | Тип информационного блока переговорных | | `data.rmIblockId` | string | Идентификатор информационного блока переговорных | | `data.rmForSites` | string \| boolean | Общие ли переговорные для всех сайтов портала | | `data.pathes` | array | Адреса разделов для отдельных сайтов портала. Через этот эндпоинт всегда пустой | | `data.pathesForSites` | string \| boolean | Заданы ли адреса разделов отдельно для каждого сайта | | `data.forumId` | string | Идентификатор форума, к которому привязаны обсуждения событий | | `meta.warnings` | array | Появляется, только когда портал вернул сокращённый набор. Формат элемента — `code` и `message` | Кроме перечисленных полей ответ содержит адреса разделов для нестандартных типов календаря — по одному полю на тип, с именем вида `path_to_type_location`. Имена таких полей приходят в том виде, в каком их отдаёт портал, поэтому набор полей ответа не фиксирован. ## Пример ответа ```json { "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`: ```json { "success": false, "error": { "code": "SCOPE_DENIED", "message": "This endpoint requires 'calendar' scope" } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|---------| | 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` | | 401 | `INVALID_API_KEY` | Неверный API-ключ | | 401 | `KEY_EXPIRED` | Срок действия API-ключа истёк | | 401 | `TOKEN_MISSING` | Ключу не настроены токены для портала | | 402 | `ACCOUNT_FROZEN` | Баланс портала заморожен | | 403 | `SCOPE_DENIED` | У ключа нет скоупа `calendar` | | 422 | `BITRIX_ERROR` | Битрикс24 отклонил запрос — текст в `message` | | 429 | `RATE_LIMITED` | Превышено 120 запросов в минуту на портал к этому эндпоинту, либо лимит запросов к Битрикс24 | | 502 | `BITRIX_UNAVAILABLE` | Портал недоступен либо вернул ответ неожиданной структуры | Полный список общих ошибок API — [Ошибки](/docs/errors). ## Известные особенности - **Сокращённый ответ у ключа внешнего пользователя.** Владельцу ключа, который не является сотрудником портала, Битрикс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` — это часы, а не полное время, поэтому сравнение с меткой времени события требует приведения к часовому поясу портала. ## Смотрите также - [Эндпоинты раздела](/docs/calendar/endpoints) - [Календарь](/docs/calendar) - [События календаря](/docs/entities/calendar-events) - [Разделы календаря](/docs/entities/calendar-sections)