[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-entity-api":3,"docs-tabs-entity-api":6},{"content":4,"lastmod":5},"# Обзор API\n\nВайбкод предоставляет единый REST-интерфейс для работы с сущностями Битрикс24: CRM, задачи, пользователи, календарь, диск, каталог, документооборот и другие. Все сущности имеют одинаковый набор операций.\n\n> Базовый URL: `https:\u002F\u002Fvibecode.bitrix24.tech`\n> Авторизация: заголовок `X-Api-Key: ваш_ключ`\n> Ключи `vibe_app_…` дополнительно требуют заголовок `Authorization: Bearer` с токеном сессии на каждый запрос к сущностям. Для фоновых задач (cron, планировщик) без пользователя у экрана берите ключ `vibe_api_…`. Подробнее — [Создание и использование ключа](.\u002Fkeys-auth.md).\n\n## Доступные операции\n\nКаждая сущность поддерживает стандартный набор операций. Путь строится по шаблону `\u002Fv1\u002F{entity}`.\n\n### Список — `GET \u002Fv1\u002F{entity}`\n\nПолучить записи с пагинацией, сортировкой и выборкой полей.\n\n```bash\ncurl -H \"X-Api-Key: $KEY\" \\\n  \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdeals?limit=100&offset=0\"\n```\n\nПараметры:\n\n| Параметр | Тип | Описание |\n|----------|-----|---------|\n| `limit` | number | Количество записей (по умолчанию 50, максимум 5000) |\n| `offset` | number | Пропустить N записей |\n| `select` | string[] | Выборка полей: `?select=id,title,amount` |\n| `order` | object | Сортировка: `?order[createdAt]=desc` |\n\n**Авто-пагинация:** при `limit > 50` Вайбкод автоматически запрашивает несколько страниц у Битрикс24 и возвращает все записи в одном ответе.\n\n### Получить по ID — `GET \u002Fv1\u002F{entity}\u002F{id}`\n\n```bash\ncurl -H \"X-Api-Key: $KEY\" \\\n  \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdeals\u002F123\"\n```\n\nОтвет: `{ success: true, data: { id: 123, title: \"...\", ... } }`\n\n### Создать — `POST \u002Fv1\u002F{entity}`\n\n```bash\ncurl -X POST -H \"X-Api-Key: $KEY\" -H \"Content-Type: application\u002Fjson\" \\\n  \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdeals\" \\\n  -d '{\"title\": \"Новая сделка\", \"stageId\": \"NEW\", \"amount\": 150000}'\n```\n\nОтвет: `{ success: true, data: { id: 456, ... } }` (HTTP 201)\n\n### Обновить — `PATCH \u002Fv1\u002F{entity}\u002F{id}`\n\n```bash\ncurl -X PATCH -H \"X-Api-Key: $KEY\" -H \"Content-Type: application\u002Fjson\" \\\n  \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdeals\u002F123\" \\\n  -d '{\"stageId\": \"WON\", \"amount\": 200000}'\n```\n\n### Удалить — `DELETE \u002Fv1\u002F{entity}\u002F{id}`\n\n```bash\ncurl -X DELETE -H \"X-Api-Key: $KEY\" \\\n  \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdeals\u002F123\"\n```\n\n### Поиск — `POST \u002Fv1\u002F{entity}\u002Fsearch`\n\nПоиск с фильтрацией. Подробнее о синтаксисе фильтров: [Фильтрация](.\u002Ffiltering.md)\n\n```bash\ncurl -X POST -H \"X-Api-Key: $KEY\" -H \"Content-Type: application\u002Fjson\" \\\n  \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdeals\u002Fsearch\" \\\n  -d '{\"filter\": {\"stageId\": \"NEW\", \"amount\": {\"$gte\": 100000}}, \"sort\": {\"createdAt\": \"desc\"}, \"limit\": 200}'\n```\n\nПараметры:\n\n| Параметр | Тип | Описание |\n|----------|-----|---------|\n| `filter` | object | Условия фильтрации ([три синтаксиса](.\u002Ffiltering.md)) |\n| `sort` | string \\| object \\| array | Сортировка. Поддерживаются: `\"id\"` \u002F `\"-amount\"` \u002F `\"id,-createdAt\"` (string), `{ id: \"asc\", amount: \"desc\" }` или `{ id: 1, amount: -1 }` (object), `[\"id\", \"-amount\"]` (array). Невалидный тип → `400 INVALID_SORT_TYPE`. Подробнее про пагинацию — см. [filtering.md](.\u002Ffiltering.md#pagination-patterns). |\n| `limit` | number | Количество записей (по умолчанию 50, максимум 5000, авто-пагинация при > 50) |\n| `offset` | number | Пропустить N записей |\n| `autoWindow` | boolean | `false` — отключить разбивку по дате для больших выборок |\n\n**Windowed search:** для больших наборов данных поиск автоматически разбивает запрос на временные окна. Если это вызывает таймауты — отключите через `autoWindow: false`.\n\n### Агрегация — `POST \u002Fv1\u002F{entity}\u002Faggregate`\n\nПодсчёт количества и числовые агрегации (`sum`, `avg`, `min`, `max`) с фильтрацией.\n\n```bash\ncurl -X POST -H \"X-Api-Key: $KEY\" -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"aggregate\": [\n      { \"field\": \"amount\", \"function\": \"sum\" },\n      { \"field\": \"amount\", \"function\": \"avg\" }\n    ],\n    \"filter\": { \"stageId\": \"WON\" }\n  }' \\\n  \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdeals\u002Faggregate\"\n```\n\nПараметры (body):\n\n| Параметр | Тип | Описание |\n|----------|-----|---------|\n| `aggregate` | array | Массив агрегаций: `{ \"field\": \"amount\", \"function\": \"sum\" }`. Функции: `count`, `sum`, `avg`, `min`, `max`. Без массива — только `count` |\n| `filter` | object | Фильтрация по полям сущности |\n| `groupBy` | string \\| string[] | Поле или массив полей для группировки (максимум 5). Допустимые значения — из списка `aggregatable` конкретной сущности. Для entities без `aggregatable` (items, requisites) параметр не поддерживается |\n\n> **Как это работает:** `count` считается одним быстрым вызовом в Битрикс24. Для `sum`\u002F`avg`\u002F`min`\u002F`max` платформа подгружает записи под фильтр (до 5000 — больше помечается `meta.truncated: true`) и считает на стороне Вайбкод. При невалидном поле ответ содержит список доступных.\n\n> **Пользовательские поля (UF)** поддерживаются в `sum`\u002F`avg`\u002F`min`\u002F`max` для UF-типов `integer`, `double`, `money`. `groupBy` принимает UF-поля любого типа. Подробно — в разделе [Агрегация POST — UF-поля](#агрегация-post-uf-поля) ниже.\n\n> **Смарт-процессы (items)** используют path-параметр: `POST \u002Fv1\u002Fitems\u002F:entityTypeId\u002Faggregate`. Зарезервированные `entityTypeId` (1, 2, 3, 4, 7, 31) обслуживаются специализированными API сделок, лидов, контактов, компаний, предложений, счетов.\n\n### Агрегация POST — UF-поля\n\nКанонический POST-вариант агрегации принимает массив выражений и поддерживает пользовательские поля (`UF_CRM_*`, `ufCrm_*`).\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdeals\u002Faggregate \\\n  -H \"X-Api-Key: $KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"aggregate\": [\n      { \"function\": \"sum\", \"field\": \"amount\" },\n      { \"function\": \"sum\", \"field\": \"UF_CRM_BUDGET\" },\n      { \"function\": \"avg\", \"field\": \"UF_CRM_SCORE\" }\n    ],\n    \"groupBy\": \"UF_CRM_PRIORITY\"\n  }'\n```\n\n**Правила UF-поддержки:**\n\n| Функция | Принимает UF-типы |\n|---------|-------------------|\n| `sum`, `avg`, `min`, `max` | только `integer`, `double`, `money` |\n| `groupBy` | любой UF-тип (string, enumeration, date, integer, …) |\n\n**Money-поля** хранятся в Битрикс24 как строка `\"сумма|валюта\"` (например `\"1500.50|RUB\"`). Агрегат извлекает числовую часть до `|` — все арифметические операции корректны.\n\n**Ошибки:**\n\n| HTTP | Код | Когда |\n|------|-----|-------|\n| 400 | `INVALID_PARAMS` | UF-тип не из списка `integer`\u002F`double`\u002F`money` для `sum`\u002F`avg`\u002F`min`\u002F`max` — в `message` указан фактический тип |\n| 400 | `INVALID_PARAMS` | Поле не найдено ни в схеме, ни в UF-кэше — в `message` перечислены доступные стандартные и UF-поля |\n\n**Кэш UF-полей:** одно обращение к `crm.{entity}.fields` на комбинацию `портал+сущность` (+entityTypeId для items). TTL 5 минут — повторные агрегаты в пределах окна не вызывают дополнительных запросов.\n\n### Схема полей — `GET \u002Fv1\u002F{entity}\u002Ffields`\n\nПолучить описание всех полей сущности с типами.\n\n```bash\ncurl -H \"X-Api-Key: $KEY\" \\\n  \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdeals\u002Ffields\"\n```\n\n### Пакетные операции — `POST \u002Fv1\u002F{entity}\u002Fbatch`\n\nМассовое создание, обновление или удаление записей одной сущности.\n\n```json\n{ \"action\": \"create\", \"items\": [{ \"title\": \"Сделка 1\" }, { \"title\": \"Сделка 2\" }] }\n```\n\nДля работы с **разными сущностями** в одном запросе используйте [Batch API](.\u002Fbatch.md).\n\n## Формат ответа\n\nВсе эндпоинты возвращают единый формат:\n\n```json\n{\n  \"success\": true,\n  \"data\": [ ... ],\n  \"total\": 150,\n  \"meta\": { \"hasMore\": true }\n}\n```\n\n| Поле | Описание |\n|------|---------|\n| `success` | `true` при успешном выполнении |\n| `data` | Массив записей (list\u002Fsearch) или объект (get\u002Fcreate) |\n| `total` | Общее количество записей (для list\u002Fsearch) |\n| `meta.hasMore` | Есть ли ещё записи для загрузки |\n\n## Преобразование полей\n\nВайбкод автоматически преобразует имена полей при отправке запроса. В запросах всегда используйте camelCase:\n\n```json\n{ \"title\": \"Сделка\", \"stageId\": \"NEW\", \"assignedById\": 1 }\n```\n\nВ ответах формат полей зависит от Bitrix24 API конкретной сущности:\n\n| Формат ответа | Сущности | Пример ответа |\n|---------------|----------|---------------|\n| camelCase | CRM (deals, contacts, companies, leads, quotes, invoices), **tasks**, catalog, sale, documents, bookings | `{ \"id\": 1, \"title\": \"Сделка\", \"stageId\": \"NEW\" }` |\n| UPPER_CASE (только сырые\u002Fнедекларированные поля) | users, departments, files, folders, calendar-events, activities, workgroups | `{ \"ID\": 1, \"NAME\": \"…\" }` |\n\n> Сущности с объявленной схемой полей (включая **tasks**) возвращают **описанные** поля в camelCase (`id`\u002F`title`\u002F`status`\u002F`responsibleId`\u002F…). `tasks` ранее ошибочно числилась в UPPER_CASE-строке — её ответы `list`\u002F`get` полностью camelCase. UPPER_CASE-форму могут сохранять только сырые\u002Fнедекларированные поля сущностей из второй строки.\n\n## Пользовательские поля (UF)\n\nПользовательские поля передаются и возвращаются **без преобразования имени**. Поддерживаются оба формата Bitrix24:\n\n- Старый API: `UF_CRM_1234567890`\n- SPA API: `ufCrm_1234567890`\n\n```json\n{ \"UF_CRM_1234567890\": \"значение\" }\n```\n\nИмя поля в ответе совпадает с тем, что возвращает Bitrix24. Для получения списка пользовательских полей используйте `GET \u002Fv1\u002Fuserfields\u002F:entity`.\n\nУправление пользовательскими полями: [Custom Fields](.\u002Fuserfields.md)\n\n## Особые сущности\n\n### Smart Processes (Items)\n\nСмарт-процессы используют `entityTypeId` в URL: `GET \u002Fv1\u002Fitems\u002F{entityTypeId}`.\n\n```bash\n# Список записей смарт-процесса с entityTypeId = 1058\ncurl -H \"X-Api-Key: $KEY\" \\\n  \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fitems\u002F1058?limit=10\"\n```\n\nСписок доступных смарт-процессов: `GET \u002Fv1\u002Fsmart-processes`.\n\n### Calendar Events\n\nТребуют обязательные параметры: `type` (user\u002Fgroup\u002Fcompany) и `ownerId`.\n\n```bash\ncurl -H \"X-Api-Key: $KEY\" \\\n  \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fcalendar-events?type=user&ownerId=1\"\n```\n\n### Files\n\nТребуют `folderId`. Получите его из `GET \u002Fv1\u002Fstorages` → поле `rootFolderId`.\n\n## Rate Limit\n\n10 запросов\u002Fсекунду — лимит Битрикс24 на уровне портала, общий для всех ключей.\n\n**Как укладываться в лимит:**\n- [Batch API](.\u002Fbatch.md) — 50 вызовов за 1 единицу лимита\n- `POST \u002Fv1\u002F{entity}\u002Fbatch` — до 500 записей CRUD за 10 единиц (а не за 500)\n- `POST \u002Fv1\u002F{entity}\u002Faggregate` — `count` идёт одним быстрым вызовом; `sum`\u002F`avg`\u002F`min`\u002F`max` подгружают до 5000 записей и считаются на стороне Вайбкод\n- Параметр `select` — загрузка только нужных полей сокращает объём ответа\n\nПодробнее: [Оптимизация](.\u002Foptimization.md) — паттерны для дашбордов, массовых операций, сканирования больших объёмов\n\n## Паттерны использования\n\n| Задача | Подход |\n|--------|--------|\n| Дашборд \u002F аналитика | `POST \u002Fv1\u002F{entity}\u002Faggregate` — счётчики и суммы по фильтру |\n| Массовое обновление | `POST \u002Fv1\u002F{entity}\u002Fbatch` с action=update |\n| Данные из нескольких сущностей | `POST \u002Fv1\u002Fbatch` — deals + tasks + contacts в 1 запросе |\n| Запись + связанные данные | `?include=company,contact` — [связанные данные](.\u002Fincludes.md) в одном ответе |\n| Сканирование 1000+ записей | `POST \u002Fv1\u002F{entity}\u002Fsearch` с limit + offset |\n\n## Связанные разделы\n\n- [Связанные данные (include)](.\u002Fincludes.md) — загрузка связанных сущностей в одном запросе\n- [Фильтрация](.\u002Ffiltering.md) — три синтаксиса фильтров, даты, NOT-фильтры\n- [Batch API](.\u002Fbatch.md) — до 50 вызовов в одном запросе\n- [Все сущности](.\u002Fentities-index.md) — полный список сущностей со ссылками\n- [Оптимизация](.\u002Foptimization.md) — rate limits, паттерны производительности\n- [Коды ошибок](.\u002Ferrors.md) — справочник ошибок платформы\n","2026-07-07",{}]