#Оптимизация и batch

Как получить максимум от VibeCode API: объединять запросы, использовать правильный уровень API и избегать типичных ошибок.

#Уровни API

VibeCode предлагает три уровня работы с Битрикс24:

#1. Entity API (рекомендуется)

35 сущностей: CRM, задачи, пользователи, календарь, диск, чат, генератор документов, бронирование, бизнес-процессы, открытые линии, телефония и другие:

  • GET /v1/deals — список сделок
  • POST /v1/deals/search — поиск с фильтрами и сортировкой
  • POST /v1/deals/aggregate — агрегация (сумма, среднее, группировка)
  • POST /v1/deals/batch — массовые операции (до 500 записей)

Entity API валидирует данные, преобразует поля и работает быстрее прямых вызовов.

#2. Batch API

POST /v1/batch — выполнить до 50 вызовов за один запрос. Единый entity-формат с автоматическим маппингом полей:

JSON 
{
  "calls": [
    {"id": "deals", "entity": "deals", "action": "list", "params": {"filter": {"stageId": "NEW"}}},
    {"id": "contacts", "entity": "contacts", "action": "search", "params": {"filter": {"typeId": "CLIENT"}}},
    {"id": "user", "entity": "users", "action": "get", "entityId": 1}
  ]
}

Rate limit считается как 1 вызов, а не 50. Идеально для дашбордов, где нужны данные из нескольких сущностей. Действие search поддерживается — каждый search-вызов авто-пагинирует до 5000 записей.

#Rate limit

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

Как снизить нагрузку:

  • /v1/batch — 50 вызовов = 1 единица rate limit
  • /v1/deals/batch — 500 записей CRUD = 10 единиц rate limit (вместо 500)
  • /v1/deals/aggregate — одна агрегация вместо загрузки всех записей

#Авто-пагинация

Не реализуй пагинацию через start вручную! Entity API делает это автоматически:

GET /v1/deals?limit=200

VibeCode сам сделает внутренние запросы через batch Битрикс24 и вернёт все записи.

POST /v1/{entity}/search автоматически разбивает крупные запросы на временные окна для надёжности. Если windowing вызывает проблемы (таймауты, сетевые ошибки), его можно отключить:

JSON 
{
  "filter": { "$gte": { "createdAt": "2026-01-01" } },
  "autoWindow": false
}

Мета-данные ответа включают windowCount (количество окон) и windowErrors (количество окон с ошибками). Ошибки отдельных окон не фатальны — запрос вернёт данные из остальных окон.

#Паттерны

#Дашборд / аналитика

Используй POST /v1/deals/aggregate вместо загрузки всех записей:

JSON 
{
  "aggregate": {"total": {"sum": "opportunity"}, "count": {"count": "*"}},
  "groupBy": ["stageId"]
}

#Сбор данных из нескольких сущностей

Используй POST /v1/batch с entity-форматом:

JSON 
{
  "calls": [
    {"id": "new", "entity": "deals", "action": "list", "params": {"filter": {"stageId": "NEW"}}},
    {"id": "won", "entity": "deals", "action": "list", "params": {"filter": {"stageId": "WON"}}},
    {"id": "contacts", "entity": "contacts", "action": "list"}
  ]
}

#Массовое сканирование (1000+ записей)

  1. Получи список через Entity API: GET /v1/deals?limit=5000
  2. Для связанных данных: /v1/batch с entity-вызовами по 50 за запрос

#Массовое обновление

POST /v1/deals/batch с action: "update" — до 500 записей за HTTP-запрос.

#Известные ограничения Битрикс24

Метод Проблема Решение
crm.timeline.comment.list Игнорирует фильтр >=CREATED Получи все, фильтруй по дате на клиенте
im.dialog.messages.get Нет фильтра по дате, пагинация по 20 Пагинируй вручную, используй LAST_ID
Любой *.list метод Макс. 50 записей от Битрикс24 Используй limit в Entity API для авто-пагинации
im.chat.get ~40% сделок не имеют чата В batch обрабатывай ошибки поэлементно

#Что дальше