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

Агрегация воронок

POST /v1/deal-categories/aggregate

Подсчёт количества воронок и числовые агрегаты по фильтру. Без тела запроса возвращает общее количество воронок одним вызовом, без выгрузки записей.

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

Параметр Тип Обяз. Описание
aggregate array нет Массив агрегаций. Каждый элемент: { "field": "sort", "function": "sum" }. Функции: count, sum, avg, min, max. Для count поле — "*". Без массива возвращается только count
filter object нет Точное равенство и $in по id, name, sort. Фильтр по isLocked или createdAt даёт 400 UNSUPPORTED_FILTER. Синтаксис фильтрации

Числовые функции (sum/avg/min/max) применимы к числовым полям воронки — sort. Группировка (groupBy) недоступна: у воронок нет категориальных полей для группировки, запрос с groupBy возвращает 400 INVALID_PARAMS.

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/deal-categories/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/deal-categories/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

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

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

const { success, data } = await res.json()
console.log('Всего воронок:', data.count)

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

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

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

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

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

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

Сумма поля sort по всем воронкам:

JSON 
{
  "aggregate": [{ "field": "sort", "function": "sum" }]
}

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.count number Общее количество воронок под фильтр
data.aggregates object Результаты числовых агрегаций по полям. Пустой объект, если массив aggregate не передан
data.meta.totalRecords number Общее количество воронок под фильтр
data.meta.recordsProcessed number Сколько записей обработано: 0 для чистого count, число записей при числовых функциях
data.meta.truncated boolean true, если числа посчитаны не по всем записям под фильтр: прочитано меньше записей, чем обещал data.count — в том числе когда под фильтр попало больше 5000, — либо срез оборвался ошибкой подстраницы. Размер нехватки приходит в data.meta.recordsShortfall, оборванный срез — в data.meta.pageErrorSample. Присутствует всегда, на полном ответе равен false. Если в запросе нет ни groupBy, ни числовых функций, записи не выгружаются и флаг всегда false

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

Запрос количества (тело {}):

JSON 
{
  "success": true,
  "data": {
    "count": 6,
    "aggregates": {},
    "meta": {
      "totalRecords": 6,
      "recordsProcessed": 0,
      "truncated": false
    }
  }
}

Сумма поля sort (тело { "aggregate": [{ "field": "sort", "function": "sum" }] }):

JSON 
{
  "success": true,
  "data": {
    "count": 6,
    "aggregates": { "sort": { "sum": 2410 } },
    "meta": {
      "totalRecords": 6,
      "recordsProcessed": 6,
      "truncated": false
    }
  }
}

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

400 — передан groupBy (у воронок нет полей для группировки):

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupBy field 'isLocked' is not aggregatable on this entity. Available: ."
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS Передан groupBy или числовая функция по нечисловому полю
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
429 RATE_LIMITED Превышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Точное значение — в заголовке x-ratelimit-limit (потолок делится на реплики). Повторите после срока из заголовка Retry-After

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

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

Признак усечения приходит рядом с самим числом. Когда ответ приходит с meta.truncated: true, пометка truncated: true стоит внутри объекта каждого поля в data.aggregates, у каждого элемента data.groups, а в data.meta.warnings добавляется предупреждение с кодом AGGREGATE_TRUNCATED. Так клиент, который читает только само число, видит, что оно посчитано по части записей. На полном ответе ни одной из этих пометок нет. Полный разбор — Агрегация POST — потолок 5000 записей.

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