Агрегация записей справочника

POST /v1/statuses/aggregate

Подсчёт count и числовые агрегации sum, avg, min, max по записям справочников CRM с фильтром. Основной сценарий — count: сколько записей в справочнике или под фильтром.

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

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

Поля entityId, statusId, name, semantics — категориальные. Для них доступен только count с фильтром. Группировка groupBy у справочников не поддерживается. Пользовательских полей у справочников CRM нет.

Поля запроса (тело)

Примеры

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

curl -X POST "https://vibecode.bitrix24.tech/v1/statuses/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "entityId": "DEAL_STAGE" }
  }'

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

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

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

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

const { success, data } = await res.json()
console.log('Стадий в воронке:', data.count)

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

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

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

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

Общее число записей всех справочников — count без фильтра:

{}

Диапазон и среднее значение сортировки стадий воронки — числовые функции по полю sort:

{
  "aggregate": [
    { "field": "sort", "function": "min" },
    { "field": "sort", "function": "max" },
    { "field": "sort", "function": "avg" }
  ],
  "filter": { "entityId": "DEAL_STAGE" }
}

Ответ на такой запрос содержит заполненный data.aggregates:

{
  "success": true,
  "data": {
    "count": 8,
    "aggregates": {
      "sort": { "min": 10, "max": 80, "avg": 45 }
    },
    "meta": { "totalRecords": 8, "recordsProcessed": 8, "truncated": false }
  }
}

Поля ответа

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

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

С числовыми функциями поле data.aggregates заполняется — см. «Другие сценарии».

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

400 — числовая функция по несуществующему полю:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Field 'nope' not found. Available numeric fields: id, sort, categoryId."
  }
}

Ошибки

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

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

count против числовых функций. count считается одним обращением к Битрикс24 на любом объёме, записи не выгружаются — поэтому data.meta.recordsProcessed равен 0. Функции sum / avg / min / max загружают записи постранично и считают на стороне Вайбкод. При выборке больше 5000 записей приходит data.meta.truncated: true, а результат рассчитан по первым 5000. Потолок не единственная причина такой пометки: она появляется и когда прочитано меньше записей, чем обещал data.count, — размер нехватки лежит в data.meta.recordsShortfall.

Группировка недоступна. Поля справочника не входят в набор группируемых, поэтому groupBy возвращает 400 INVALID_PARAMS. Чтобы посчитать записи по типам справочника, вызывайте count с фильтром filter[entityId] отдельно для каждого типа.

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

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

• Список справочников
• Поиск записей справочника
• Поля справочника
• Синтаксис фильтрации
• Лимиты и оптимизация