Для AI-агентов: markdown этой страницы — /docs-content/entities/recurring-deals/aggregate.md индекс документации — /llms.txt

Агрегация

POST /v1/recurring-deals/aggregate

Подсчитывает настройки повторения сделок и вычисляет числовые показатели по фильтру. Используйте для анализа числа выполнений и ограничений.

Стандартные поля

Поле Назначение
counterRepeat Число выполнений. Имеет смысл для sum, avg, min, max
limitRepeat Ограничение числа повторов. Имеет смысл для числовых функций
id, dealId, basedId, categoryId Идентификаторы. Принимаются числовыми функциями, их сумма не описывает число выполнений

Стандартные поля недоступны для groupBy: регулярные сделки группируются только по UF. Запрос со стандартным полем возвращает INVALID_PARAMS с пустым перечнем доступных полей.

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

Метод принимает UF типов integer, double, money для числовых функций, UF любого типа — для groupBy и фильтра. Имена — UF_CRM_* или ufCrm_*. Для неизвестного числового UF ошибка INVALID_PARAMS перечисляет доступные числовые поля. Для использования UF настройте поле на портале.

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

Поле Тип Обязательный Описание
aggregate object[] нет До 5 выражений. По умолчанию — count по *
aggregate[].field string да Поле выражения: * для count, числовое поле для sum, avg, min, max
aggregate[].function string да Функция: count, sum, avg, min, max
filter object нет Условия по синтаксису фильтрации
groupBy string / string[] нет До 5 полей. Только UF, которые существуют на портале: стандартные поля группировать нельзя
groupOrderBy object[] нет Сортировка групп. Только при groupBy
groupOrderBy[].field string да Ключ группировки, count или запрошенный результат вида counterRepeat:sum
groupOrderBy[].direction string нет Направление: asc или desc. По умолчанию desc
groupLimit number нет При groupBy: целое число от 1 до 1000

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/recurring-deals/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"aggregate":[{"field":"counterRepeat","function":"sum"},{"field":"counterRepeat","function":"avg"}],"filter":{"active":true}}'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/recurring-deals/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"aggregate":[{"field":"counterRepeat","function":"sum"},{"field":"counterRepeat","function":"avg"}],"filter":{"active":true}}'

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

javascript 
const response = await fetch('https://vibecode.bitrix24.tech/v1/recurring-deals/aggregate', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({"aggregate":[{"field":"counterRepeat","function":"sum"},{"field":"counterRepeat","function":"avg"}],"filter":{"active":true}}),
})
const result = await response.json()
if (!result.success) throw new Error(result.error.message)
console.log(result.data)

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

javascript 
const response = await fetch('https://vibecode.bitrix24.tech/v1/recurring-deals/aggregate', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({"aggregate":[{"field":"counterRepeat","function":"sum"},{"field":"counterRepeat","function":"avg"}],"filter":{"active":true}}),
})
const result = await response.json()
if (!result.success) throw new Error(result.error.message)
console.log(result.data)

Для массива groupBy передайте до 5 имён существующих UF.

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

Блоки ниже — тела запросов.

Подсчёт всех настроек:

JSON 
{}

Подсчёт с фильтром:

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

Поля ответа

Поле Тип Описание
success boolean Признак успешного запроса
data object Результат агрегации. Его поля — строками data.* ниже
data.count number Общее число подходящих записей
data.aggregates object Результаты по полям и функциям
data.aggregates.<field>.truncated boolean Маркер неполного расчёта, если установлен
data.groups object[] Группы, только при groupBy
data.groups[].count number Число прочитанных записей в группе
data.groups[].aggregates object Результаты группы по полям и функциям
data.groups[].truncated boolean Маркер неполной группы, если установлен
data.meta.totalRecords number Общее число подходящих записей
data.meta.recordsProcessed number Число прочитанных записей, необязательное поле
data.meta.truncated boolean Расчёт по неполной выборке
data.meta.recordsShortfall number Недобор записей: totalRecords - recordsProcessed. Приходит и при потолке 5000
data.meta.pageErrorSample object Пример ошибки подстраницы при прерванном чтении
data.meta.warnings object[] При неполной выборке содержит AGGREGATE_TRUNCATED
data.meta.groupTotal number Число групп до ограничения groupLimit
data.meta.groupsTruncated boolean Ограничен ли список групп через groupLimit

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

JSON 
{
  "success": true,
  "data": {
    "count": 2,
    "aggregates": {
      "counterRepeat": {
        "sum": 699,
        "avg": 349.5
      }
    },
    "meta": {
      "totalRecords": 2,
      "recordsProcessed": 2,
      "truncated": false
    }
  }
}

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

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

400 — неизвестное числовое поле для агрегации:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Field 'UF_CRM_NOT_REAL' not found. Available numeric fields: id, dealId, basedId, counterRepeat, categoryId, limitRepeat."
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS aggregate не является массивом или массив пустой
400 INVALID_PARAMS В aggregate больше 5 выражений
400 INVALID_PARAMS Неизвестная или отсутствующая функция. Допустимы count, sum, avg, min, max
400 INVALID_PARAMS Для count указано поле, отличное от *
400 INVALID_PARAMS Для числовой функции не указано поле или указано *
400 INVALID_PARAMS Стандартное поле не имеет типа number
400 INVALID_PARAMS UF имеет нечисловой тип. Сообщение называет тип UF
400 INVALID_PARAMS Поле не найдено. Сообщение перечисляет допустимые стандартные и пользовательские числовые поля
400 INVALID_PARAMS Переданы отдельные op, field, function без массива aggregate
400 INVALID_PARAMS groupBy не является строкой или массивом строк
400 INVALID_PARAMS В groupBy больше 5 полей
400 INVALID_PARAMS В groupBy передано стандартное поле: регулярные сделки по стандартным полям не группируются
400 INVALID_PARAMS В groupBy использовано зарезервированное имя count, aggregates, meta или groups
400 INVALID_PARAMS groupOrderBy передан без groupBy
400 INVALID_PARAMS groupLimit передан без groupBy
400 INVALID_PARAMS groupOrderBy не является массивом
400 INVALID_PARAMS Элемент groupOrderBy не является объектом с непустой строкой field
400 INVALID_PARAMS Направление groupOrderBy отличается от asc или desc
400 INVALID_PARAMS Ключ сортировки вида <field>:<function> не запрошен в aggregate
400 INVALID_PARAMS Поле сортировки групп не является ключом groupBy, count или ключом числового результата
400 INVALID_PARAMS groupLimit не является целым числом от 1 до 1000
400 UNKNOWN_FILTER_FIELD Фильтр по неизвестному полю. Допустимые поля — в сообщении ошибки и описании полей
400 INVALID_FILTER_FIELD Имя поля начинается с неподдерживаемого префикса @ или !@
400 INVALID_FILTER_OPERATOR Неизвестный оператор, пустой объект условия или логическое условие $or либо $and
400 INVALID_DUPLICATE_FILTER_FIELD Два условия сводятся к одному условию фильтра. Передайте одно из них
400 INVALID_FILTER_SHAPE filter не является объектом
422 AGGREGATION_LIMIT_EXCEEDED Выборка для числовых функций или группировки превышает 5000 записей и включён режим отказа до чтения записей
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 TOKEN_MISSING Нет настроенных токенов доступа к Битрикс24
403 SCOPE_DENIED API-ключ не имеет скоупа crm
403 BITRIX_ACCESS_DENIED Битрикс24 отказал в доступе, в том числе из-за отсутствия нужного скоупа
422 BITRIX_ERROR Бизнес-отказ Битрикс24 или ограничение тарифа. Причина — в error.message
503 BITRIX_TIMEOUT Битрикс24 не ответил вовремя. Повторите после срока из Retry-After
502 BITRIX_UNAVAILABLE Нет соединения с Битрикс24
429 RATE_LIMITED Превышен лимит запросов. Точное значение — в заголовке x-ratelimit-limit. Повторите после срока из заголовка Retry-After

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

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

Без groupBy и без числовых функций метод возвращает подсчёт без чтения записей: recordsProcessed: 0, truncated: false. Запрос count вместе с groupBy требует чтения записей. Числовые функции вычисляются по прочитанным записям, максимум 5000. Для точного результата сужайте фильтр.

data.meta.truncated становится true, если прочитано меньше записей, чем указано в общем количестве, либо чтение прервано ошибкой подстраницы. Недобор возможен и ниже потолка 5000. При этом ответ всегда содержит recordsShortfall либо pageErrorSample, а результаты по полям и группам помечаются truncated.

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