Агрегация типов смарт-процессов

POST /v1/smart-processes/aggregate

Подсчёт количества типов смарт-процессов по фильтру с опциональной группировкой. Считает, сколько типов на портале удовлетворяют условию, и разбивает их по значению выбранного поля — например, сколько типов создал каждый сотрудник или у скольких включена та или иная возможность.

Поля для агрегации

Группировка и числовые функции работают по полям из списка aggregatable:

  • createdBy, updatedBy — кто создал и кто последним изменил тип. Подходят для groupBy.
  • customSectionId — идентификатор цифрового рабочего места. Подходит для groupBy.
  • isCategoriesEnabled, isStagesEnabled, isAutomationEnabled, isBizProcEnabled, isPaymentsEnabled, isCountersEnabled, isLinkWithProductsEnabled — флаги возможностей.

Основной сценарий для каталога типов — count (сколько типов под фильтр) и groupBy (разбивка по полю). У типов смарт-процессов нет пользовательских полей — агрегируются только перечисленные стандартные.

Поля запроса (body)

Параметр Тип Обяз. Описание
aggregate array нет Массив агрегаций. Каждый элемент: { "field": "*", "function": "count" }. Функция count считает строки, а не значения поля. Функции: count, sum, avg, min, max. Без массива возвращается только count
filter object нет Фильтрация по полям типа. Список полей: Поля типа. Синтаксис фильтрации
groupBy string | string[] нет Поле или массив полей для группировки (максимум 5). Принимает только поля из списка aggregatable выше

Примеры

curl — личный ключ

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/smart-processes/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "isStagesEnabled": true },
    "groupBy": "createdBy"
  }'

curl — OAuth-приложение

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/smart-processes/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "isStagesEnabled": true },
    "groupBy": "createdBy"
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/smart-processes/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { isStagesEnabled: true },
    groupBy: 'createdBy',
  }),
})

const { success, data } = await res.json()
console.log('Всего типов:', data.count)
console.log('По создателям:', data.groups)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/smart-processes/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { isStagesEnabled: true },
    groupBy: 'createdBy',
  }),
})

const { success, data } = await res.json()

Для группировки по нескольким полям передайте массив: "groupBy": ["createdBy", "isStagesEnabled"] (максимум 5).

Другие сценарии

Подсчёт записей — count с полем "*", самый быстрый запрос без выгрузки записей. Без массива aggregate результат тот же:

JSON 
{ "aggregate": [{ "field": "*", "function": "count" }] }

Сколько типов с включёнными роботами и триггерами:

JSON 
{ "filter": { "isAutomationEnabled": true } }

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.count number Количество типов, соответствующих фильтру
data.aggregates object Результаты числовых функций. Для группировки по count — пустой объект
data.groups array Группы (только при groupBy). Каждый элемент: поле группировки + count + aggregates
data.meta.totalRecords number Общее количество типов под фильтр
data.meta.recordsProcessed number Сколько типов обработано для агрегации
data.meta.truncated boolean true, если под фильтр попало больше 5000 типов
data.meta.groupTotal number Количество групп (только при groupBy)
data.meta.groupsTruncated boolean true, если список групп был усечён

Пример ответа

Группировка по создателю (groupBy: "createdBy"):

JSON 
{
  "success": true,
  "data": {
    "count": 7,
    "aggregates": {},
    "groups": [
      { "createdBy": 1, "count": 4, "aggregates": {} },
      { "createdBy": 835, "count": 2, "aggregates": {} },
      { "createdBy": 1013, "count": 1, "aggregates": {} }
    ],
    "meta": {
      "totalRecords": 7,
      "recordsProcessed": 7,
      "truncated": false,
      "groupTotal": 3,
      "groupsTruncated": false
    }
  }
}

Без groupBy поле data.groups в ответе отсутствует.

Пример ответа при ошибке

400 — поле недоступно для группировки:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupBy field 'title' is not aggregatable on this entity. Available: customSectionId, createdBy, updatedBy, isCategoriesEnabled, isStagesEnabled, isAutomationEnabled, isBizProcEnabled, isPaymentsEnabled, isCountersEnabled, isLinkWithProductsEnabled."
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS Неизвестная функция, несуществующее поле или поле вне списка aggregatable — сообщение перечисляет доступные поля
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
403 SCOPE_DENIED API-ключ не имеет скоупа crm

Полный список общих ошибок API — Ошибки.

Известные особенности

count считается одним вызовом. Запрос без массива aggregate возвращает количество типов под фильтр одним обращением к Битрикс24, не выгружая записи.

Группировка по флагу даёт две группы — true и false. Например, groupBy: "isAutomationEnabled" разделит типы на две группы: с включёнными роботами и без них. Если все типы имеют одинаковое значение флага, в ответе будет одна группа.

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