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

Поля секции календаря

GET /v1/calendar-sections/fields

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

Примеры

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

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

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

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

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/calendar-sections/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Полей:', Object.keys(data.fields).length)

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

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

const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.fields object Справочник полей секции. Ключ — имя поля в camelCase, значение — его описание
data.fields.<имя>.type string Тип значения поля: number, string, boolean, object или datetime
data.fields.<имя>.readonly boolean true — поле заполняется системой, при создании и обновлении отклоняется с 400 READONLY_FIELD
data.fields.<имя>.required boolean Присутствует у полей, обязательных при создании
data.fields.<имя>.enum array Список допустимых значений поля. Каждый элемент несёт value для передачи в запросе, английскую подпись label и русскую labelRu
data.batch array Операции секции, доступные в пакетном вызове: create, update, delete

Справочник описывает четырнадцать полей:

Поле Тип RO Описание
id number да Идентификатор секции
name string Название секции. Обязательно при создании
description string Описание секции
type string Тип календаря. Обязателен при создании. Допустимые значения перечислены в enum: user — календарь пользователя, group — календарь рабочей группы, company_calendar — календарь компании, location — календарь переговорной
ownerId number Идентификатор владельца календаря. Обязателен при создании. Для типа user — идентификатор сотрудника из GET /v1/users. Владелец остальных типов описан в разделе Секции календаря
color string Цвет секции в формате #RRGGBB
textColor string Цвет текста в формате #RRGGBB
export object Параметры экспорта в формате iCal. Ключи внутри объекта идут в верхнем регистре
access object да Карта прав доступа к секции
perm object да Карта разрешений текущего сотрудника
isCollab boolean да Принадлежит ли секция коллабе
createdBy number да Сотрудник, создавший секцию. Список: GET /v1/users
dateCreate datetime да Дата создания секции
updatedAt datetime да Дата последнего изменения секции

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

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true },
      "name": { "type": "string", "readonly": false, "required": true },
      "description": { "type": "string", "readonly": false },
      "type": {
        "type": "string",
        "readonly": false,
        "required": true,
        "enum": [
          { "value": "user", "label": "User calendar", "labelRu": "Календарь пользователя" },
          { "value": "group", "label": "Workgroup calendar", "labelRu": "Календарь рабочей группы" },
          { "value": "company_calendar", "label": "Company calendar", "labelRu": "Календарь компании" },
          { "value": "location", "label": "Location calendar", "labelRu": "Календарь переговорной" }
        ]
      },
      "ownerId": { "type": "number", "readonly": false, "required": true },
      "color": { "type": "string", "readonly": false },
      "textColor": { "type": "string", "readonly": false },
      "export": { "type": "object", "readonly": false },
      "access": { "type": "object", "readonly": true },
      "perm": { "type": "object", "readonly": true },
      "isCollab": { "type": "boolean", "readonly": true },
      "createdBy": { "type": "number", "readonly": true },
      "dateCreate": { "type": "datetime", "readonly": true },
      "updatedAt": { "type": "datetime", "readonly": true }
    },
    "batch": ["create", "update", "delete"]
  }
}

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

403 — нет скоупа:

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

Ошибки

HTTP Код Описание
403 SCOPE_DENIED Ключу не хватает скоупа calendar
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 TOKEN_MISSING У API-ключа не настроены токены Битрикс24
429 RATE_LIMITED Превышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Точное значение — в заголовке x-ratelimit-limit (потолок делится на реплики). Повторите после срока из заголовка Retry-After

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

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

Справочник одинаков на всех порталах. Ответ собирается из описания сущности на стороне платформы Вайбкод, у портала он не запрашивается. Поэтому набор полей, их типы и значения enum не зависят ни от настроек конкретного портала, ни от доступности Битрикс24, а пользовательские поля в справочнике не появляются.

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