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

`GET /v1/calendar-events`

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

## Параметры

| Параметр | Тип | Обяз. | По умолч. | Описание |
|----------|-----|:-----:|-----------|---------|
| `type` (query) | string | да | — | Тип календаря: `user`, `group`, `company_calendar` |
| `ownerId` (query) | number | да | — | ID владельца календаря: сотрудник (`GET /v1/users`) или рабочая группа |
| `limit` (query) | number | нет | `50` | Размер окна выдачи — до 5000 вхождений |
| `offset` (query) | number | нет | `0` | Начало окна: пропустить первые N вхождений отсортированного набора |

## Примеры

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

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

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

```bash
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 — личный ключ

```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-приложение

```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_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data` | array | Массив событий (все поля — см. [Поля события](./fields.md)) |
| `meta.total` | number | Общее количество вхождений в наборе. Повторяющиеся события развёрнуты — по строке на вхождение |
| `meta.hasMore` | boolean | `true`, пока за пределами окна `offset + limit` остаются записи |

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

| `type` | URL |
|---|---|
| `user` | `https://<portal>.bitrix24.ru/company/personal/user/<ownerId>/calendar/?EVENT_ID=<id>&EVENT_DATE=<dd.mm.yyyy>` |
| `group` | `https://<portal>.bitrix24.ru/workgroups/group/<ownerId>/calendar/?EVENT_ID=<id>&EVENT_DATE=<dd.mm.yyyy>` |
| `company_calendar` | `https://<portal>.bitrix24.ru/calendar/?EVENT_ID=<id>&EVENT_DATE=<dd.mm.yyyy>` |

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

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

```json
{
  "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`:

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

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `MISSING_REQUIRED_PARAMS` | Не переданы `type` и (или) `ownerId` |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `calendar` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

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

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

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

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

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

- [Создать событие](./create.md)
- [Получить событие](./get.md)
- [Поля события](./fields.md)