## Агрегация отгрузок `POST /v1/shipments/aggregate` Подсчёт отгрузок и сумма, среднее, минимум и максимум по стоимости доставки с фильтром и группировкой по заказу или службе доставки. ## Стандартные поля | Поле | Назначение | |------|------------| | `priceDelivery` | Стоимость доставки — основное поле для `sum` / `avg` / `min` / `max`. Доступно и для `groupBy` | | `basePriceDelivery`, `discountPrice` | Базовая стоимость доставки и скидка на доставку — числовые поля для `sum` / `avg` / `min` / `max` | | `orderId` | Идентификатор заказа — используется в `groupBy`, чтобы разложить отгрузки по заказам | | `deliveryId` | Идентификатор службы доставки — используется в `groupBy`, чтобы разложить отгрузки по службам | Поля для `groupBy` — массив `aggregatable` в [`GET /v1/shipments/fields`](./fields.md). Числовые функции принимают любое поле с типом `number` из той же схемы, в том числе поля вне `aggregatable`. **Пользовательские поля.** На несуществующее имя поля в `sum` / `avg` / `min` / `max` ответ `400 INVALID_PARAMS` перечисляет допустимые числовые поля. В этом списке только стандартные поля отгрузки — `basePriceDelivery`, `companyId`, `deliveryId`, `discountPrice`, `empAllowDeliveryId`, `empCanceledId`, `empDeductedId`, `empMarkedId`, `empResponsibleId`, `id`, `orderId`, `priceDelivery`, `responsibleId`, пользовательских полей в нём нет. Отказ на поле вне `aggregatable` в `groupBy` называет допустимыми только `orderId`, `priceDelivery`, `deliveryId`. ## Поля запроса (body) | Поле | Тип | Обяз. | Описание | |------|-----|:-----:|---------| | `aggregate` | array | нет | Массив выражений `{ "field": "priceDelivery", "function": "sum" }`, до 5 в одном запросе. Функции: `count`, `sum`, `avg`, `min`, `max`. Для `count` поле — `"*"`. Без параметра возвращается только `count` | | `filter` | object | нет | Фильтрация по полям [`GET /v1/shipments/fields`](./fields.md).
[Синтаксис фильтрации](/docs/filtering). Пример: `{ "orderId": 1027 }` | | `groupBy` | string \| string[] | нет | Поле или массив полей для группировки, до 5 полей. Допустимые значения — из массива `aggregatable`: `orderId`, `priceDelivery`, `deliveryId` | | `groupOrderBy` | array | нет | Сортировка групп: `[{ "field": "priceDelivery:sum", "direction": "desc" }]`. В `field` — `count`, имя поля из `groupBy` или `<поле>:<функция>` из `aggregate`. Работает только вместе с `groupBy` | | `groupLimit` | number | нет | Ограничение числа возвращаемых групп, от 1 до 1000. Работает только вместе с `groupBy` | ## Примеры ### curl — личный ключ ```bash curl -X POST "https://vibecode.bitrix24.tech/v1/shipments/aggregate" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "filter": { "orderId": 1027 }, "aggregate": [ { "field": "*", "function": "count" }, { "field": "priceDelivery", "function": "sum" }, { "field": "priceDelivery", "function": "avg" } ], "groupBy": "deliveryId" }' ``` ### curl — OAuth-приложение ```bash curl -X POST "https://vibecode.bitrix24.tech/v1/shipments/aggregate" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "filter": { "orderId": 1027 }, "aggregate": [ { "field": "*", "function": "count" }, { "field": "priceDelivery", "function": "sum" }, { "field": "priceDelivery", "function": "avg" } ], "groupBy": "deliveryId" }' ``` ### JavaScript — личный ключ ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/shipments/aggregate', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ filter: { orderId: 1027 }, aggregate: [ { field: '*', function: 'count' }, { field: 'priceDelivery', function: 'sum' }, { field: 'priceDelivery', function: 'avg' }, ], groupBy: 'deliveryId', }), }) const { success, data } = await res.json() // data.groups — стоимость доставки по службам доставки console.log(data.groups) ``` ### JavaScript — OAuth-приложение ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/shipments/aggregate', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ filter: { orderId: 1027 }, aggregate: [ { field: '*', function: 'count' }, { field: 'priceDelivery', function: 'sum' }, { field: 'priceDelivery', function: 'avg' }, ], groupBy: 'deliveryId', }), }) const { success, data } = await res.json() ``` ## Другие сценарии Блоки ниже — тела запросов. Только количество отгрузок заказа — без массива `aggregate` записи не выгружаются, в ответе `data.meta.recordsProcessed` равен `0`: ```json { "filter": { "orderId": 1027 } } ``` Группировка по двум полям — по заказу и службе доставки: ```json { "aggregate": [{ "field": "*", "function": "count" }], "groupBy": ["orderId", "deliveryId"] } ``` Сумма и среднее стоимости доставки без группировки: ```json { "filter": { "orderId": 1027 }, "aggregate": [ { "field": "*", "function": "count" }, { "field": "priceDelivery", "function": "sum" }, { "field": "priceDelivery", "function": "avg" } ] } ``` ## Поля ответа | Поле | Тип | Описание | |------|-----|---------| | `success` | boolean | Всегда `true` при успехе | | `data.count` | number | Количество отгрузок под фильтр | | `data.aggregates` | object | Результаты числовых функций по полям: `{ "priceDelivery": { "sum": 500, "avg": 500 } }`. Пустой объект, если в `aggregate` только `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": 1, "aggregates": { "priceDelivery": { "sum": 500, "avg": 500 } }, "groups": [ { "deliveryId": 1, "count": 1, "aggregates": { "priceDelivery": { "sum": 500, "avg": 500 } } } ], "meta": { "totalRecords": 1, "recordsProcessed": 1, "truncated": false, "groupTotal": 1, "groupsTruncated": false } } } ``` ## Пример ответа при ошибке 400 — поля нет в схеме, сообщение перечисляет допустимые числовые поля: ```json { "success": false, "error": { "code": "INVALID_PARAMS", "message": "Field 'weight' not found. Available numeric fields: basePriceDelivery, companyId, deliveryId, discountPrice, empAllowDeliveryId, empCanceledId, empDeductedId, empMarkedId, empResponsibleId, id, orderId, priceDelivery, responsibleId." } } ``` ## Ошибки | 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` не числовое, например `trackingNumber` — сообщение называет его тип | | 400 | `INVALID_PARAMS` | Поля для `sum` / `avg` / `min` / `max` нет в схеме — сообщение содержит список числовых полей | | 400 | `INVALID_PARAMS` | Поля `op`, `field` или `function` переданы на верхнем уровне тела вместо массива `aggregate` | | 400 | `INVALID_PARAMS` | `groupBy` не строка и не массив строк | | 400 | `INVALID_PARAMS` | Поле в `groupBy` вне массива `aggregatable` — сообщение содержит список допустимых | | 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` и числовых функций или сужайте фильтр, например по `orderId`. Полный разбор — [Агрегация POST — потолок 5000 записей](/docs/entity-api#агрегация-post-потолок-5000-записей). ## Смотрите также - [Список отгрузок](./list.md) - [Поиск отгрузок](./search.md) - [Поля отгрузки](./fields.md) - [Отгрузки](/docs/entities/shipments) - [Синтаксис фильтрации](/docs/filtering) - [Лимиты и оптимизация](/docs/optimization)