#Обзор API

VibeCode предоставляет единый REST-интерфейс для работы с сущностями Битрикс24: CRM, задачи, пользователи, календарь, диск, каталог, документооборот и другие. Все сущности имеют одинаковый набор операций.

Базовый URL: https://vibecode.bitrix24.tech Авторизация: заголовок X-Api-Key: ваш_ключ

#Доступные операции

Каждая сущность поддерживает стандартный набор операций. Путь строится по шаблону /v1/{entity}.

#Список — `GET /v1/{entity}`

Получить записи с пагинацией, сортировкой и выборкой полей.

curl -H "X-Api-Key: $KEY" \
  "https://vibecode.bitrix24.tech/v1/deals?limit=100&offset=0"

Параметры:

Авто-пагинация: при limit > 50 VibeCode автоматически запрашивает несколько страниц у Битрикс24 и возвращает все записи в одном ответе.

#Получить по ID — `GET /v1/{entity}/{id}`

curl -H "X-Api-Key: $KEY" \
  "https://vibecode.bitrix24.tech/v1/deals/123"

Ответ: { success: true, data: { id: 123, title: "...", ... } }

#Создать — `POST /v1/{entity}`

curl -X POST -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  "https://vibecode.bitrix24.tech/v1/deals" \
  -d '{"title": "Новая сделка", "stageId": "NEW", "amount": 150000}'

Ответ: { success: true, data: { id: 456, ... } } (HTTP 201)

#Обновить — `PATCH /v1/{entity}/{id}`

curl -X PATCH -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  "https://vibecode.bitrix24.tech/v1/deals/123" \
  -d '{"stageId": "WON", "amount": 200000}'

#Удалить — `DELETE /v1/{entity}/{id}`

curl -X DELETE -H "X-Api-Key: $KEY" \
  "https://vibecode.bitrix24.tech/v1/deals/123"

#Поиск — `POST /v1/{entity}/search`

Поиск с фильтрацией. Подробнее о синтаксисе фильтров: Фильтрация

curl -X POST -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  "https://vibecode.bitrix24.tech/v1/deals/search" \
  -d '{"filter": {"stageId": "NEW", "amount": {"$gte": 100000}}, "sort": {"createdAt": "desc"}, "limit": 200}'

Параметры:

Windowed search: для больших наборов данных поиск автоматически разбивает запрос на временные окна. Если это вызывает таймауты — отключите через autoWindow: false.

#Агрегация — `GET /v1/{entity}/aggregate`

Подсчёт, сумма, среднее без загрузки всех записей.

curl -H "X-Api-Key: $KEY" \
  "https://vibecode.bitrix24.tech/v1/deals/aggregate?op=sum&field=amount&groupBy=stageId"

Параметры:

Операция count работает для всех сущностей. Для sum/avg/min/max укажите field — при невалидном поле ответ содержит список доступных.

#Схема полей — `GET /v1/{entity}/fields`

Получить описание всех полей сущности с типами.

curl -H "X-Api-Key: $KEY" \
  "https://vibecode.bitrix24.tech/v1/deals/fields"

#Пакетные операции — `POST /v1/{entity}/batch`

Массовое создание, обновление или удаление записей одной сущности.

{ "action": "create", "items": [{ "title": "Сделка 1" }, { "title": "Сделка 2" }] }

Для работы с разными сущностями в одном запросе используйте Batch API.

#Формат ответа

Все эндпоинты возвращают единый формат:

{
  "success": true,
  "data": [ ... ],
  "total": 150,
  "meta": { "hasMore": true }
}

#Преобразование полей

VibeCode автоматически преобразует имена полей при отправке запроса. В запросах всегда используйте camelCase:

{ "title": "Сделка", "stageId": "NEW", "assignedById": 1 }

В ответах формат полей зависит от Bitrix24 API конкретной сущности:

#Пользовательские поля (UF)

Пользовательские поля передаются и возвращаются без преобразования имени. Поддерживаются оба формата Bitrix24:

• Старый API: UF_CRM_1234567890
• SPA API: ufCrm_1234567890

{ "UF_CRM_1234567890": "значение" }

Имя поля в ответе совпадает с тем, что возвращает Bitrix24. Для получения списка пользовательских полей используйте GET /v1/userfields/:entity.

Управление пользовательскими полями: Custom Fields

#Особые сущности

#Smart Processes (Items)

Смарт-процессы используют entityTypeId в URL: GET /v1/items/{entityTypeId}.

# Список записей смарт-процесса с entityTypeId = 1058
curl -H "X-Api-Key: $KEY" \
  "https://vibecode.bitrix24.tech/v1/items/1058?limit=10"

Список доступных смарт-процессов: GET /v1/smart-processes.

#Calendar Events

Требуют обязательные параметры: type (user/group/company) и ownerId.

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

#Files

Требуют folderId. Получите его из GET /v1/storages → поле rootFolderId.

#Rate Limit

10 запросов/секунду — лимит Битрикс24 на уровне портала, общий для всех ключей.

Как укладываться в лимит:

• Batch API — 50 вызовов за 1 единицу лимита
• POST /v1/{entity}/batch — до 500 записей CRUD за 10 единиц (а не за 500)
• GET /v1/{entity}/aggregate — подсчёт, сумма, среднее одним запросом
• Параметр select — загрузка только нужных полей сокращает объём ответа

Подробнее: Оптимизация — паттерны для дашбордов, массовых операций, сканирования больших объёмов

#Паттерны использования

#Связанные разделы

• Связанные данные (include) — загрузка связанных сущностей в одном запросе
• Фильтрация — три синтаксиса фильтров, даты, NOT-фильтры
• Batch API — до 50 вызовов в одном запросе
• Все сущности — полный список сущностей со ссылками
• Оптимизация — rate limits, паттерны производительности
• Коды ошибок — справочник ошибок платформы