Список событий

GET /v1/calendar-events

Возвращает события календаря за фиксированный период вокруг текущей даты: с месяца назад по три месяца вперёд.

Параметры

Примеры

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

curl "https://vibecode.bitrix24.tech/v1/calendar-events?type=user&ownerId=1&limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

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

curl "https://vibecode.bitrix24.tech/v1/calendar-events?type=user&ownerId=1&limit=10" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

const params = new URLSearchParams({ type: 'user', ownerId: '1', limit: '10' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/calendar-events?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Найдено ${meta.total} событий`)

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

const params = new URLSearchParams({ type: 'user', ownerId: '1', limit: '10' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/calendar-events?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Поля ответа

URL карточки любого события из массива data зависит от типа календаря:

<dd.mm.yyyy> — дата начала события (поле from) в формате «день.месяц.год» через точку. <portal> — домен вашего портала. Доступ ограничен правами сотрудника в Битрикс24.

Связанные данные

Получить сотрудников, связанных с событиями, вместе со списком — параметр include в GET-запросе:

GET /v1/calendar-events?type=user&ownerId=1&include=owner,host

Доступные значения include — до трёх имён за запрос:

Карточка сотрудника та же, что в ответе GET /v1/users/:id. Связь читает сотрудника, поэтому ключу кроме calendar нужен скоуп user. Один сотрудник загружается один раз на весь ответ. Результат — в поле _included каждого элемента data:

{
  "success": true,
  "data": [
    {
      "id": 7773,
      "name": "Созвон с командой",
      "ownerId": 1,
      "meetingHost": 1,
      "_included": {
        "owner": { "id": 1, "name": "Иван", "lastName": "Петров", "email": "ivan.petrov@example.com", "active": true },
        "host": { "id": 1, "name": "Иван", "lastName": "Петров", "email": "ivan.petrov@example.com", "active": true }
      }
    }
  ],
  "meta": { "total": 1, "hasMore": false }
}

Показаны основные поля события и сотрудника. Полный состав карточки — Поля сотрудника. Если в ответе больше 200 вхождений, связи не загружаются, а в meta приходит includeSkipped: true — уменьшите limit.

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

{
  "success": true,
  "data": [
    {
      "id": 7773,
      "parentId": 7773,
      "active": true,
      "deleted": false,
      "type": "user",
      "ownerId": 1,
      "name": "Созвон с командой",
      "from": "2026-06-10T10:00:00+03:00",
      "to": "2026-06-10T11:00:00+03:00",
      "skipTime": false,
      "durationSeconds": 3600,
      "createdBy": 1,
      "dateCreate": "06/05/2026 09:12:00 am",
      "updatedAt": "06/05/2026 09:12:00 am",
      "description": "Еженедельная синхронизация",
      "accessibility": "busy",
      "importance": "normal",
      "isMeeting": false,
      "meetingStatus": "H",
      "meetingHost": 1,
      "sectionId": 3,
      "attendeeList": [
        { "id": 1, "entryId": "7773", "status": "H" }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "hasMore": false
  }
}

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

400 — не переданы обязательные type и ownerId:

{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_PARAMS",
    "message": "GET /v1/calendar-events requires query parameters: type, ownerId. Example: GET /v1/calendar-events?type=...&ownerId=..."
  }
}

Ошибки

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

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

Весь диапазон — одним набором. Запрошенный период приходит от Битрикс24 одним массивом без пагинации. Платформа сортирует его детерминированно — по началу события from, при равенстве по id, затем по occurrenceIndex — и отдаёт окно от offset до offset + limit. Порядок элементов воспроизводим от запроса к запросу, окна с разными offset не пересекаются и в объединении дают весь набор.

Регулярные события. Событие с полем rrule в списке возвращается отдельным элементом на каждое вхождение серии, попадающее в окно выборки. У всех элементов общий id и parentId, различаются from / to и occurrenceIndex — пара id + occurrenceIndex однозначно идентифицирует строку набора.

Смещение часового пояса в наборе. Момент времени в from и to каждой записи точен, а суффикс смещения одинаков не у всех записей ответа — у вхождений регулярной серии стоит смещение, действующее на начало серии. Разбирайте значения как моменты времени и переводите в нужный часовой пояс. Часы и минуты, прочитанные прямо из строки, могут отличаться от времени, которое сотрудник видит в календаре.

Отслеживание изменений. Поле version — монотонный счётчик изменений события, не зависящий от региональных настроек аккаунта. Запросите список с select=id,version, сравните пары со своим снимком и дочитайте изменённые события. Описания обоих полей — Поля события.

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

• Создать событие
• Получить событие
• Поля события
• Связанные данные