#Агрегация позиций корзины

POST /v1/basket-items/aggregate

Подсчёт количества позиций и числовые агрегации (sum, avg, min, max) по полям price и quantity. Поддерживает фильтрацию и группировку по orderId, productId, currency.

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

Поле Назначение
price Числовое — подходит для sum / avg / min / max (агрегации по цене за единицу)
quantity Числовое — подходит для sum / avg / min / max (агрегации по количеству)
currency Категориальное — используется в groupBy (по валюте)
orderId, productId Идентификаторы — используются в groupBy (по заказу или товару)

Полный список агрегируемых полей перечислен в таблице выше.

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

Параметр Тип Обяз. Описание
aggregate array нет Массив агрегаций: [{ "field": "quantity", "function": "sum" }]. Функции: count, sum, avg, min, max. Без параметра — только count
filter object нет Фильтрация — те же поля, что в `GET /v1/basket-items`. Синтаксис фильтрации
groupBy string | string[] нет Поле или массив полей для группировки (максимум 5)
groupOrderBy array нет Сортировка групп: [{ "field": "quantity:sum", "direction": "desc" }]
groupLimit number нет Ограничение количества возвращаемых групп (1-1000)

#Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/basket-items/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [
      { "field": "quantity", "function": "sum" },
      { "field": "price", "function": "avg" }
    ],
    "groupBy": "productId",
    "groupLimit": 5
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/basket-items/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [
      { "field": "quantity", "function": "sum" },
      { "field": "price", "function": "avg" }
    ],
    "groupBy": "productId",
    "groupLimit": 5
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/basket-items/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    aggregate: [
      { field: 'quantity', function: 'sum' },
      { field: 'price', function: 'avg' },
    ],
    groupBy: 'productId',
    groupLimit: 5,
  }),
})

const { success, data } = await res.json()
console.log('Топ-5 товаров по продажам:', data.groups)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/basket-items/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    aggregate: [{ field: 'quantity', function: 'sum' }],
    groupBy: 'productId',
  }),
})

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

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

Общее количество позиций без выгрузки записей:

JSON 
{}

Общая стоимость всех позиций в заказе:

JSON 
{
  "aggregate": [{ "field": "price", "function": "sum" }],
  "filter": { "orderId": 33 }
}

Топ-3 товаров по сумме продаж:

JSON 
{
  "aggregate": [{ "field": "quantity", "function": "sum" }],
  "groupBy": "productId",
  "groupOrderBy": [{ "field": "quantity:sum", "direction": "desc" }],
  "groupLimit": 3
}

#Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.count number Общее количество позиций, соответствующих фильтру
data.aggregates object Результаты агрегаций: { "quantity": { "sum": ... }, "price": { "avg": ... } }
data.groups array Группы (только при groupBy)
data.meta.totalRecords number Общее количество записей
data.meta.recordsProcessed number Количество обработанных записей (до 5000)
data.meta.truncated boolean true, если записей больше 5000
data.meta.groupTotal number Количество групп до groupLimit
data.meta.groupsTruncated boolean Был ли список групп обрезан groupLimit

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

JSON 
{
  "success": true,
  "data": {
    "count": 261,
    "aggregates": {
      "quantity": { "sum": 412 }
    },
    "groups": [
      {
        "productId": 119,
        "count": 23,
        "aggregates": { "quantity": { "sum": 47 } }
      },
      {
        "productId": 245,
        "count": 18,
        "aggregates": { "quantity": { "sum": 36 } }
      },
      {
        "productId": 87,
        "count": 14,
        "aggregates": { "quantity": { "sum": 21 } }
      }
    ],
    "meta": {
      "totalRecords": 261,
      "recordsProcessed": 261,
      "truncated": false,
      "groupTotal": 89,
      "groupsTruncated": true
    }
  }
}

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

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

400 — неизвестное поле в groupBy:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Unknown field 'foo'. Available: price, quantity, currency, orderId, productId"
  }
}

#Ошибки

HTTP Код Описание
400 INVALID_PARAMS Неизвестная функция или несуществующее поле — сообщение содержит список допустимых полей
400 INVALID_PARAMS Передано больше 5 полей в groupBy
400 INVALID_PARAMS Зарезервированные ключевые слова в groupBy: count, aggregates, meta, groups
403 SCOPE_DENIED API-ключ не имеет скоупа sale
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

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

Учёт незавершённых корзин. В выборку попадают и позиции с orderId: null (товары в незавершённых корзинах). Чтобы исключить их, добавьте filter[orderId][!]=null.

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