## Агрегация позиций отгрузок `POST /v1/shipment-items/aggregate` Подсчёт позиций отгрузок и сумма, среднее, минимум и максимум по количеству товара с фильтром и группировкой по отгрузке или позиции корзины. ## Стандартные поля | Поле | Назначение | |------|------------| | `quantity` | Количество товара в позиции — основное поле для `sum` / `avg` / `min` / `max`. Доступно и для `groupBy` | | `reservedQuantity` | Зарезервированное количество — числовое поле для `sum` / `avg` / `min` / `max` и `groupBy` | | `orderDeliveryId` | Идентификатор отгрузки из [`GET /v1/shipments`](/docs/entities/shipments/list) — используется в `groupBy`, чтобы разложить позиции по отгрузкам | | `basketId` | Идентификатор позиции корзины из [`GET /v1/basket-items`](/docs/entities/basket-items/list) — используется в `groupBy`, чтобы разложить позиции по товарам корзины | Поля для `groupBy` — массив `aggregatable` в [`GET /v1/shipment-items/fields`](./fields.md). Числовые функции принимают любое поле с типом `number` из той же схемы, в том числе `id` вне `aggregatable`. **Пользовательские поля.** Если в `sum` / `avg` / `min` / `max` передать несуществующее поле, ответ `400 INVALID_PARAMS` перечисляет допустимые числовые поля. В этом списке только стандартные поля позиции отгрузки — `basketId`, `id`, `orderDeliveryId`, `quantity`, `reservedQuantity`. Пользовательских полей в нём нет. ## Поля запроса (body) | Поле | Тип | Обяз. | Описание | |------|-----|:-----:|---------| | `aggregate` | array | нет | Массив выражений `{ "field": "quantity", "function": "sum" }`, до 5 в одном запросе. Функции: `count`, `sum`, `avg`, `min`, `max`. Для `count` поле — `"*"`. Без параметра возвращается только `count` | | `filter` | object | нет | Фильтрация по полям [`GET /v1/shipment-items/fields`](./fields.md).
[Синтаксис фильтрации](/docs/filtering). Пример: `{ "orderDeliveryId": 985 }` | | `groupBy` | string \| string[] | нет | Поле или массив полей для группировки, до 5 полей. Допустимые значения — из массива `aggregatable`: `quantity`, `reservedQuantity`, `orderDeliveryId`, `basketId` | | `groupOrderBy` | array | нет | Сортировка групп: `[{ "field": "quantity:sum", "direction": "desc" }]`. В `field` — `count`, имя поля из `groupBy` или `<поле>:<функция>` из `aggregate`. Работает только вместе с `groupBy` | | `groupLimit` | number | нет | Ограничение числа возвращаемых групп, от 1 до 1000. Работает только вместе с `groupBy` | ## Примеры ### curl — личный ключ ```bash curl -X POST "https://vibecode.bitrix24.tech/v1/shipment-items/aggregate" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "filter": { "orderDeliveryId": { "$in": [975, 985] } }, "aggregate": [ { "field": "*", "function": "count" }, { "field": "quantity", "function": "sum" }, { "field": "quantity", "function": "avg" } ], "groupBy": "orderDeliveryId" }' ``` ### curl — OAuth-приложение ```bash curl -X POST "https://vibecode.bitrix24.tech/v1/shipment-items/aggregate" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "filter": { "orderDeliveryId": { "$in": [975, 985] } }, "aggregate": [ { "field": "*", "function": "count" }, { "field": "quantity", "function": "sum" }, { "field": "quantity", "function": "avg" } ], "groupBy": "orderDeliveryId" }' ``` ### JavaScript — личный ключ ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/shipment-items/aggregate', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ filter: { orderDeliveryId: { $in: [975, 985] } }, aggregate: [ { field: '*', function: 'count' }, { field: 'quantity', function: 'sum' }, { field: 'quantity', function: 'avg' }, ], groupBy: 'orderDeliveryId', }), }) const { success, data } = await res.json() // data.groups — количество товара по каждой отгрузке console.log(data.groups) ``` ### JavaScript — OAuth-приложение ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/shipment-items/aggregate', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ filter: { orderDeliveryId: { $in: [975, 985] } }, aggregate: [ { field: '*', function: 'count' }, { field: 'quantity', function: 'sum' }, { field: 'quantity', function: 'avg' }, ], groupBy: 'orderDeliveryId', }), }) const { success, data } = await res.json() ``` Для группировки по нескольким полям передайте массив: `"groupBy": ["orderDeliveryId", "basketId"]`, максимум 5 полей. ## Другие сценарии Блоки ниже — тела запросов. Только количество позиций в отгрузке — без массива `aggregate` записи не выгружаются, в ответе `data.meta.recordsProcessed` равен `0`: ```json { "filter": { "orderDeliveryId": 985 } } ``` Отгрузки с наибольшим количеством товара — две первые группы по убыванию суммы `quantity`: ```json { "aggregate": [{ "field": "quantity", "function": "sum" }], "groupBy": "orderDeliveryId", "groupOrderBy": [{ "field": "quantity:sum", "direction": "desc" }], "groupLimit": 2 } ``` Общее и максимальное количество товара по всем позициям без группировки: ```json { "aggregate": [ { "field": "*", "function": "count" }, { "field": "quantity", "function": "sum" }, { "field": "quantity", "function": "max" } ] } ``` ## Поля ответа | Поле | Тип | Описание | |------|-----|---------| | `success` | boolean | Всегда `true` при успехе | | `data.count` | number | Количество позиций отгрузок под фильтр | | `data.aggregates` | object | Результаты числовых функций по полям: `{ "quantity": { "sum": 16, "avg": 5.33 } }`. Пустой объект, если в `aggregate` только `count`: результат `count` приходит в `data.count` и `data.groups[].count`, а не здесь | | `data.groups` | array | Присутствует только при `groupBy`. Каждый элемент — значения полей группировки, `count` и `aggregates` по группе | | `data.meta.totalRecords` | number | Общее количество записей под фильтр | | `data.meta.recordsProcessed` | number | Количество обработанных записей, до 5000 | | `data.meta.truncated` | boolean | `true`, если числа посчитаны не по всем записям под фильтр: прочитано меньше записей, чем обещал `data.count` — в том числе когда под фильтр попало больше 5000, — либо срез оборвался ошибкой подстраницы. Размер нехватки приходит в `data.meta.recordsShortfall`, оборванный срез — в `data.meta.pageErrorSample`. Присутствует всегда, на полном ответе равен `false`. Если в запросе нет ни `groupBy`, ни числовых функций, записи не выгружаются и флаг всегда `false` | | `data.meta.groupTotal` | number | Присутствует только при `groupBy` — количество групп до применения `groupLimit` | | `data.meta.groupsTruncated` | boolean | Присутствует только при `groupBy`. `true`, если список групп обрезан `groupLimit` | ## Пример ответа ```json { "success": true, "data": { "count": 3, "aggregates": { "quantity": { "sum": 16, "avg": 5.333333333333333 } }, "groups": [ { "orderDeliveryId": 975, "count": 1, "aggregates": { "quantity": { "sum": 1, "avg": 1 } } }, { "orderDeliveryId": 985, "count": 2, "aggregates": { "quantity": { "sum": 15, "avg": 7.5 } } } ], "meta": { "totalRecords": 3, "recordsProcessed": 3, "truncated": false, "groupTotal": 2, "groupsTruncated": false } } } ``` Без `groupBy` поля `data.groups`, `data.meta.groupTotal` и `data.meta.groupsTruncated` в ответе отсутствуют. ## Пример ответа при ошибке 400 — поля нет в схеме, сообщение перечисляет допустимые числовые поля: ```json { "success": false, "error": { "code": "INVALID_PARAMS", "message": "Field 'weight' not found. Available numeric fields: basketId, id, orderDeliveryId, quantity, reservedQuantity." } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|---------| | 400 | `INVALID_PARAMS` | `count` передан с полем, отличным от `"*"` | | 400 | `INVALID_PARAMS` | `aggregate` передан не массивом или пустым массивом | | 400 | `INVALID_PARAMS` | В `aggregate` больше 5 выражений | | 400 | `INVALID_PARAMS` | Неизвестная функция — сообщение перечисляет допустимые | | 400 | `INVALID_PARAMS` | `sum` / `avg` / `min` / `max` без поля или с полем `"*"` | | 400 | `INVALID_PARAMS` | Поле для `sum` / `avg` / `min` / `max` не числовое, например `xmlId` — сообщение называет его тип | | 400 | `INVALID_PARAMS` | Поля для `sum` / `avg` / `min` / `max` нет в схеме — сообщение содержит список числовых полей | | 400 | `INVALID_PARAMS` | Поля `field` или `function` переданы на верхнем уровне тела вместо массива `aggregate` | | 400 | `INVALID_PARAMS` | `groupBy` не строка и не массив строк | | 400 | `INVALID_PARAMS` | Поле в `groupBy` вне массива `aggregatable`, например `xmlId` — сообщение содержит список допустимых | | 400 | `INVALID_PARAMS` | В `groupBy` больше 5 полей | | 400 | `INVALID_PARAMS` | В `groupBy` зарезервированное имя: `count`, `aggregates`, `meta`, `groups` | | 400 | `INVALID_PARAMS` | `groupOrderBy` или `groupLimit` переданы без `groupBy`, либо значение одного из них некорректно | | 400 | `UNKNOWN_FILTER_FIELD` | Неизвестное поле в `filter` — сообщение содержит список полей позиции отгрузки | | 400 | `INVALID_FILTER_FIELD` | Имя поля в `filter` начинается с неподдерживаемого префикса `@` или `!@` | | 400 | `INVALID_FILTER_OPERATOR` | Неподдерживаемый оператор в `filter` или логическое условие, например `$or` | | 400 | `INVALID_FILTER_SHAPE` | `filter` передан не объектом условий, например строкой | | 400 | `INVALID_DUPLICATE_FILTER_FIELD` | Два условия фильтра сводятся к одному условию Битрикс24, например `$ne` и `$nin` на одном поле. Передайте одно из них | | 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `sale` | | 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` | | 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов | | 429 | `RATE_LIMITED` | Превышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Точное значение — в заголовке `x-ratelimit-limit` (потолок делится на реплики). Повторите после срока из заголовка `Retry-After` | Полный список общих ошибок API — [Ошибки](/docs/errors). ## Известные особенности **`count` против числовых функций.** Запрос без `groupBy` и без числовых функций считается одним запросом в Битрикс24 — записи не выгружаются, время ответа не зависит от количества позиций. Как только в запросе есть `sum` / `avg` / `min` / `max` или `groupBy`, в том числе вместе с одним `count`, записи подгружаются постранично, максимум 5000, и считаются на стороне Вайбкод. При `meta.truncated: true` пометка `truncated: true` стоит и внутри объекта каждого поля в `data.aggregates`, и у каждого элемента `data.groups`, а в `data.meta.warnings` приходит предупреждение `AGGREGATE_TRUNCATED`. Для точного числа на большой выборке используйте запрос без `groupBy` и числовых функций или сужайте фильтр, например по `orderDeliveryId`. Полный разбор — [Агрегация POST — потолок 5000 записей](/docs/entity-api#агрегация-post-потолок-5000-записей). **Подсчёт включает позиции системной отгрузки.** В выборку входят те же записи, что и в [список позиций](./list.md), в том числе позиции системной отгрузки, где лежит нераспределённый остаток корзины. Сумма `quantity` по позиции корзины без фильтра по отгрузке поэтому равна количеству товара в корзине. Чтобы посчитать только отгруженное, фильтруйте по `orderDeliveryId` отгрузок из [`GET /v1/shipments`](/docs/entities/shipments/list). ## Смотрите также - [Список позиций отгрузок](./list.md) - [Поиск позиций отгрузок](./search.md) - [Поля позиции отгрузки](./fields.md) - [Позиции отгрузок](/docs/entities/shipment-items) - [Синтаксис фильтрации](/docs/filtering) - [Лимиты и оптимизация](/docs/optimization)