#Обзор API

Вайбкод предоставляет единый 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 Вайбкод автоматически запрашивает несколько страниц у Битрикс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.

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

Подсчёт количества и числовые агрегации (sum, avg, min, max) с фильтрацией.

curl -X POST -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "aggregate": [
      { "field": "amount", "function": "sum" },
      { "field": "amount", "function": "avg" }
    ],
    "filter": { "stageId": "WON" }
  }' \
  "https://vibecode.bitrix24.tech/v1/deals/aggregate"

Параметры (body):

Как это работает: count считается одним быстрым вызовом в Битрикс24. Для sum/avg/min/max платформа подгружает записи под фильтр (до 5000 — больше помечается meta.truncated: true) и считает на стороне Вайбкод. При невалидном поле ответ содержит список доступных.

Пользовательские поля (UF) поддерживаются в sum/avg/min/max для UF-типов integer, double, money. groupBy принимает UF-поля любого типа. Подробно — в разделе Агрегация POST — UF-поля ниже.

Смарт-процессы (items) используют path-параметр: POST /v1/items/:entityTypeId/aggregate. Зарезервированные entityTypeId (1, 2, 3, 4, 7, 31) обслуживаются специализированными API сделок, лидов, контактов, компаний, предложений, счетов.

#Агрегация POST — UF-поля

Канонический POST-вариант агрегации принимает массив выражений и поддерживает пользовательские поля (UF_CRM_*, ufCrm_*).

curl -X POST https://vibecode.bitrix24.tech/v1/deals/aggregate \
  -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [
      { "function": "sum", "field": "amount" },
      { "function": "sum", "field": "UF_CRM_BUDGET" },
      { "function": "avg", "field": "UF_CRM_SCORE" }
    ],
    "groupBy": "UF_CRM_PRIORITY"
  }'

Правила UF-поддержки:

Money-поля хранятся в Битрикс24 как строка "сумма|валюта" (например "1500.50|RUB"). Агрегат извлекает числовую часть до | — все арифметические операции корректны.

Ошибки:

Кэш UF-полей: одно обращение к crm.{entity}.fields на комбинацию портал+сущность (+entityTypeId для items). TTL 5 минут — повторные агрегаты в пределах окна не вызывают дополнительных запросов.

#Схема полей — `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 }
}

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

Вайбкод автоматически преобразует имена полей при отправке запроса. В запросах всегда используйте 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)
• POST /v1/{entity}/aggregate — count идёт одним быстрым вызовом; sum/avg/min/max подгружают до 5000 записей и считаются на стороне Вайбкод
• Параметр select — загрузка только нужных полей сокращает объём ответа

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

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

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

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