# Универсальные списки

Программный доступ к модулю «Списки» Битрикс24: сами списки, их поля, разделы и элементы.

**Скоуп:** `lists` | **Базовый URL:** `https://vibecode.bitrix24.tech/v1` | **Авторизация:** `X-Api-Key`

> **Модуль подключается на портале отдельно.** Универсальные списки — отдельный модуль Битрикс24. Если он не активирован на портале, вызовы возвращают `409 LISTS_MODULE_NOT_ENABLED`. Это не ошибка интеграции — попросите администратора портала включить модуль «Списки» и повторите запрос.

## Модель данных

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

**Тип инфоблока** — параметр `iblockTypeId`. Возможные значения:

- `lists` — обычные списки. Значение по умолчанию.
- `lists_socnet` — списки рабочих групп. Для них нужен `socnetGroupId`.
- `bitrix_processes` — служебные бизнес-процессы.
- `structure` — тип структуры компании. Здесь лежит штатный инфоблок графика отсутствий с кодом `absence`.

Тип передаётся в query для GET и DELETE, в теле для POST и PATCH.

**Список** — сегмент пути `:iblockId`. Одни цифры — это числовой `IBLOCK_ID`, строка — символьный код `IBLOCK_CODE`. Оба варианта равнозначны.

**Поле, раздел или элемент** — соответствующий вложенный сегмент пути.

Ответы приходят в форме Битрикс24. Ключи — в верхнем регистре через подчёркивание: `ID`, `NAME`, `IBLOCK_TYPE_ID`. Числовые идентификаторы возвращаются строками, например `"ID": "121"`. Пользовательские свойства элемента адресуются ключами вида `PROPERTY_<id>`. Эти ключи не приводятся к camelCase — часть из них динамическая.

## Разделы документации

- [Списки](/docs/lists/lists) — создание, чтение, изменение и удаление самих списков, а также тип инфоблока.
- [Поля списка](/docs/lists/fields) — набор полей списка и справочник допустимых типов поля.
- [Разделы](/docs/lists/sections) — группировка элементов по разделам с поддержкой вложенности.
- [Элементы](/docs/lists/elements) — строки списка и ссылки на файлы из свойств элемента.

## Быстрый старт

```bash
# Все списки типа lists
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.tech/v1/lists?iblockTypeId=lists"

# Элементы списка 23
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.tech/v1/lists/23/elements"
```

## Полный пример

Сценарий из пяти шагов: создать список, добавить поле, добавить элемент со значением этого поля, прочитать результат, удалить список.

```bash
KEY="YOUR_API_KEY"
BASE="https://vibecode.bitrix24.tech/v1"

# 1. Создать список → { "success": true, "data": { "id": 135 } }
curl -s -X POST -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"iblockCode":"demo_orders","fields":{"NAME":"Демо: заявки","SORT":100}}' \
  "$BASE/lists"

# 2. Добавить поле → { "success": true, "data": { "id": "PROPERTY_1179" } }
curl -s -X POST -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"fields":{"NAME":"Статус","TYPE":"S","CODE":"STATUS"}}' \
  "$BASE/lists/135/fields"

# 3. Добавить элемент со значением свойства → { "success": true, "data": { "id": 7043 } }
curl -s -X POST -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"elementCode":"row-1","fields":{"NAME":"Заявка №1","PROPERTY_1179":"новая"}}' \
  "$BASE/lists/135/elements"

# 4. Прочитать элементы → data[0] = { "ID": "7043", "NAME": "Заявка №1", "PROPERTY_1179": { "3811": "новая" } }
curl -s -H "X-Api-Key: $KEY" \
  "$BASE/lists/135/elements?select=ID,NAME,PROPERTY_1179"

# 5. Удалить список → HTTP 204 No Content (поля, разделы и элементы удаляются вместе с ним)
curl -s -X DELETE -H "X-Api-Key: $KEY" "$BASE/lists/135"
```

Поле создаётся с обязательным `CODE`. Значение свойства при создании передаётся строкой (`"PROPERTY_1179": "новая"`), а при чтении возвращается в форме `{ id_значения: значение }`.

## Справочник эндпоинтов

| Метод | Путь | Bitrix24 метод | Описание |
|-------|------|----------------|----------|
| GET | [`/v1/lists`](/docs/lists/lists/list) | lists.get | Список списков заданного типа |
| POST | [`/v1/lists`](/docs/lists/lists/create) | lists.add | Создать список |
| GET | [`/v1/lists/:iblockId`](/docs/lists/lists/get) | lists.get | Один список |
| PATCH | [`/v1/lists/:iblockId`](/docs/lists/lists/update) | lists.update | Изменить список |
| DELETE | [`/v1/lists/:iblockId`](/docs/lists/lists/delete) | lists.delete | Удалить список |
| GET | [`/v1/lists/:iblockId/type`](/docs/lists/lists/type) | lists.get.iblock.type.id | Тип инфоблока по id или коду |
| GET | [`/v1/lists/:iblockId/fields`](/docs/lists/fields/list) | lists.field.get | Все поля списка |
| GET | [`/v1/lists/:iblockId/fields/:fieldId`](/docs/lists/fields/get) | lists.field.get | Одно поле |
| POST | [`/v1/lists/:iblockId/fields`](/docs/lists/fields/create) | lists.field.add | Создать поле |
| PATCH | [`/v1/lists/:iblockId/fields/:fieldId`](/docs/lists/fields/update) | lists.field.update | Изменить поле |
| DELETE | [`/v1/lists/:iblockId/fields/:fieldId`](/docs/lists/fields/delete) | lists.field.delete | Удалить поле |
| GET | [`/v1/lists/:iblockId/field-types`](/docs/lists/fields/field-types) | lists.field.type.get | Справочник типов поля |
| GET | [`/v1/lists/:iblockId/sections`](/docs/lists/sections/list) | lists.section.get | Разделы списка |
| GET | [`/v1/lists/:iblockId/sections/:sectionId`](/docs/lists/sections/get) | lists.section.get | Один раздел |
| POST | [`/v1/lists/:iblockId/sections`](/docs/lists/sections/create) | lists.section.add | Создать раздел |
| PATCH | [`/v1/lists/:iblockId/sections/:sectionId`](/docs/lists/sections/update) | lists.section.update | Изменить раздел |
| DELETE | [`/v1/lists/:iblockId/sections/:sectionId`](/docs/lists/sections/delete) | lists.section.delete | Удалить раздел |
| GET | [`/v1/lists/:iblockId/elements`](/docs/lists/elements/list) | lists.element.get | Элементы списка |
| GET | [`/v1/lists/:iblockId/elements/:elementId`](/docs/lists/elements/get) | lists.element.get | Один элемент |
| POST | [`/v1/lists/:iblockId/elements`](/docs/lists/elements/create) | lists.element.add | Создать элемент |
| PATCH | [`/v1/lists/:iblockId/elements/:elementId`](/docs/lists/elements/update) | lists.element.update | Изменить элемент |
| DELETE | [`/v1/lists/:iblockId/elements/:elementId`](/docs/lists/elements/delete) | lists.element.delete | Удалить элемент |
| GET | [`/v1/lists/:iblockId/elements/:elementId/files/:fieldId`](/docs/lists/elements/files) | lists.element.get.file.url | Ссылки на файлы свойства |

## Коды ошибок

| HTTP | Код | Когда |
|------|-----|-------|
| 409 | `LISTS_MODULE_NOT_ENABLED` | Модуль «Списки» не подключён на портале |
| 400 | `INVALID_IBLOCK_TYPE` | `iblockTypeId` не из набора `lists`, `lists_socnet`, `bitrix_processes`, `structure` |
| 400 | `MISSING_REQUIRED_FIELDS` | Не передан обязательный `iblockCode`, `sectionCode`, `elementCode` или `fields` |
| 400 | `INVALID_PARAMS` | Нечисловой `:sectionId` или `:elementId`, либо `fieldId` с префиксом `PROPERTY_` в маршруте файлов |
| 400 | `INVALID_FILTER` | Параметр `filter` не является корректным JSON |
| 400 | `INVALID_SORT_FIELD` | Параметр `sort` ссылается на неподдерживаемое поле или направление |
| 422 | `BITRIX_ERROR` | Битрикс24 отклонил запрос. Например, поле создаётся без `CODE` или обновляется без `TYPE` |
| 403 | `BITRIX_ACCESS_DENIED` | Нет прав на список, либо список с таким `:iblockId` не существует |
| 404 | `LIST_NOT_FOUND` / `SECTION_NOT_FOUND` / `ELEMENT_NOT_FOUND` / `FIELD_NOT_FOUND` | Объект не найден |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ в режиме «только чтение» |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `lists` |
| 401 | `TOKEN_MISSING` | Не передан `X-Api-Key` или у ключа нет токенов |

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

## Лимиты

| Лимит | Значение |
|-------|----------|
| Пагинация списков и элементов | Смещение выборки у `GET /v1/lists` и `GET /v1/lists/:iblockId/elements` задаётся параметром `start` либо его синонимом `offset`. Если переданы оба, применяется `start`. Ответ отдаётся страницами, следующую страницу берите, увеличивая смещение. Автоматического обхода всех страниц нет |
| Rate limit | Общий для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Списки](/docs/lists/lists)
- [Поля списка](/docs/lists/fields)
- [Разделы](/docs/lists/sections)
- [Элементы](/docs/lists/elements)