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

Агрегация свойств заказа

POST /v1/order-properties/aggregate

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

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

Поле Назначение
personTypeId ID типа плательщика из GET /v1/person-types. Для groupBy
type Тип свойства — для groupBy
required Обязательность поля при заполнении заказа — для groupBy
active Признак активности — для groupBy
sort Порядок сортировки — для sum, avg, min, max
inputFieldLocation Устаревшее поле. Битрикс24 его не использует — числовое поле
id ID свойства из списка свойств заказа. Числовое поле
propsGroupId ID группы из свойства того же типа плательщика в списке свойств заказа. Числовое поле

Поля для groupBy перечислены в data.aggregatable метода GET /v1/order-properties/fields. Числовые функции принимают поля с типом number из той же схемы: id, personTypeId, propsGroupId, sort, inputFieldLocation.

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

Поле Тип Обяз. Описание
aggregate array нет Массив выражений { "field": "sort", "function": "sum" }, от 1 до 5 выражений. Функции: count, sum, avg, min, max. Для count поле — "*". Если параметр не передан, используется [{ "field": "*", "function": "count" }]
filter object нет Фильтр по полям GET /v1/order-properties/fields.
Синтаксис фильтрации. Пример: { "id": 125 }
groupBy string | string[] нет Поле или массив полей для группировки, до 5 полей. Допустимые поля: personTypeId, type, required, active
groupOrderBy array нет Сортировка групп: [{ "field": "count", "direction": "desc" }]. В field — count, поле из groupBy или <field>:<function> из aggregate. Направления: asc, desc. Если direction не передан, используется desc. Требует groupBy
groupLimit number нет Число возвращаемых групп: целое от 1 до 1000. Если не передан, группы не обрезаются. Требует groupBy

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/order-properties/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "id": 125 },
    "aggregate": [
      { "field": "*", "function": "count" },
      { "field": "sort", "function": "sum" }
    ],
    "groupBy": ["type", "active"],
    "groupOrderBy": [{ "field": "count", "direction": "desc" }],
    "groupLimit": 10
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/order-properties/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "id": 125 },
    "aggregate": [
      { "field": "*", "function": "count" },
      { "field": "sort", "function": "sum" }
    ],
    "groupBy": ["type", "active"],
    "groupOrderBy": [{ "field": "count", "direction": "desc" }],
    "groupLimit": 10
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/order-properties/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { id: 125 },
    aggregate: [
      { field: '*', function: 'count' },
      { field: 'sort', function: 'sum' },
    ],
    groupBy: ['type', 'active'],
    groupOrderBy: [{ field: 'count', direction: 'desc' }],
    groupLimit: 10,
  }),
})

const { data } = await res.json()
console.log('Свойства по типу и активности:', data.groups)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/order-properties/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { id: 125 },
    aggregate: [
      { field: '*', function: 'count' },
      { field: 'sort', function: 'sum' },
    ],
    groupBy: ['type', 'active'],
    groupOrderBy: [{ field: 'count', direction: 'desc' }],
    groupLimit: 10,
  }),
})

const { data } = await res.json()

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

Блоки ниже — тела запросов.

Количество свойств под фильтр без группировки и числовых функций — записи не выгружаются:

JSON 
{ "filter": { "id": 125 } }

Сумма порядка сортировки с группировкой, если фильтр не находит записей:

JSON 
{
  "filter": { "id": 125, "code": "ABSENT_DELIVERY_COMMENT" },
  "aggregate": [{ "field": "sort", "function": "sum" }],
  "groupBy": ["type", "active"]
}

Для последнего запроса data.count и сумма равны 0, data.groups — пустой массив.

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.count number Общее количество свойств под фильтр
data.aggregates object Числовые результаты по полю и функции, например { "sort": { "sum": 500 } }. При одном count — пустой объект
data.aggregates.<field>.truncated boolean Приходит со значением true, если числовые результаты посчитаны по неполной выборке
data.groups array Приходит при groupBy. Каждая группа содержит значения полей группировки, count и aggregates. personTypeId имеет тип number, type — string, required и active — boolean
data.groups[].count number Количество обработанных записей группы
data.groups[].aggregates object Числовые результаты внутри группы, в том же формате, что и data.aggregates
data.groups[].truncated boolean Приходит со значением true на неполной выборке. Количество и вычисления группы относятся к обработанным записям
data.meta.totalRecords number Общее количество записей под фильтр
data.meta.recordsProcessed number Количество обработанных записей, до 5000. Без группировки и числовых функций — 0
data.meta.truncated boolean true, если прочитано меньше записей, чем обещает общее количество, в том числе из-за потолка 5000, либо чтение оборвалось ошибкой подстраницы. На полном ответе — false. Без группировки и числовых функций всегда false
data.meta.recordsShortfall number Число непрочитанных записей: totalRecords - recordsProcessed. Приходит при недоборе, в том числе при потолке 5000
data.meta.pageErrorSample object Пример ошибки подстраницы. Приходит, если чтение оборвалось на ошибке
data.meta.warnings array При неполной выборке содержит предупреждение с кодом AGGREGATE_TRUNCATED
data.meta.groupTotal number Приходит при groupBy: число групп до применения groupLimit
data.meta.groupsTruncated boolean Приходит при groupBy. true, если группы обрезаны через groupLimit

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

JSON 
{
  "success": true,
  "data": {
    "count": 1,
    "aggregates": {
      "sort": {
        "sum": 500
      }
    },
    "groups": [
      {
        "type": "STRING",
        "active": false,
        "count": 1,
        "aggregates": {
          "sort": {
            "sum": 500
          }
        }
      }
    ],
    "meta": {
      "totalRecords": 1,
      "recordsProcessed": 1,
      "truncated": false,
      "groupTotal": 1,
      "groupsTruncated": false
    }
  }
}

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

400 — строковое поле name передано в числовую функцию sum:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Field 'name' is not numeric (type: string). Only number fields support sum."
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS aggregate передан не массивом или пустым массивом
400 INVALID_PARAMS В aggregate больше 5 выражений
400 INVALID_PARAMS Неизвестная функция или функция не передана
400 INVALID_PARAMS Для count передано поле, отличное от "*"
400 INVALID_PARAMS Для sum, avg, min, max не передано поле или передано "*"
400 INVALID_PARAMS Для числовой функции передано нечисловое поле, например name или defaultValue
400 INVALID_PARAMS Поле числовой функции не найдено. Сообщение перечисляет допустимые поля: id, personTypeId, propsGroupId, sort, inputFieldLocation
400 INVALID_PARAMS Поле op, field или function передано на верхнем уровне без массива aggregate
400 INVALID_PARAMS groupBy передан не строкой и не массивом строк, либо массив содержит значение другого типа
400 INVALID_PARAMS Поле группировки не входит в personTypeId, type, required, active
400 INVALID_PARAMS В groupBy больше 5 полей
400 INVALID_PARAMS В groupBy зарезервированное имя: count, aggregates, meta, groups
400 INVALID_PARAMS groupOrderBy передан без groupBy
400 INVALID_PARAMS groupLimit передан без groupBy
400 INVALID_PARAMS groupOrderBy передан не массивом
400 INVALID_PARAMS Элемент groupOrderBy не является объектом с непустым строковым field
400 INVALID_PARAMS groupOrderBy.direction отличается от asc и desc
400 INVALID_PARAMS Ключ <field>:<function> в groupOrderBy.field отсутствует среди числовых выражений aggregate
400 INVALID_PARAMS groupOrderBy.field не является count, полем из groupBy или ключом числового выражения aggregate
400 INVALID_PARAMS groupLimit не является целым числом от 1 до 1000
400 UNKNOWN_FILTER_FIELD Неизвестное поле в filter
400 INVALID_FILTER_FIELD Имя поля в filter начинается с неподдерживаемого префикса @ или !@
400 INVALID_FILTER_OPERATOR Неподдерживаемый оператор, пустой объект в условии или логические условия $or / $and
400 INVALID_FILTER_SHAPE filter передан не объектом условий, например строкой, числом или массивом
400 INVALID_DUPLICATE_FILTER_FIELD Два условия фильтра сводятся к одному условию, например $ne и $nin для одного поля
422 AGGREGATION_LIMIT_EXCEEDED При включённом ограничении для портала под фильтр попало больше 5000 записей, а запрос требует числовых вычислений или группировки. Записи не выгружаются. Сузьте фильтр
422 BITRIX_ERROR У пользователя ключа нет прав в Битрикс24. Код Битрикс24 — в error.b24Code: 200040300010
403 BITRIX_ACCESS_DENIED У учётных данных портала нет скоупа sale (insufficient_scope)
422 BITRIX_ERROR Бизнес-отказ с текстом Битрикс24
503 BITRIX_TIMEOUT Битрикс24 не ответил вовремя. Повторите после срока из Retry-After
502 BITRIX_UNAVAILABLE Нет соединения с Битрикс24
403 SCOPE_DENIED API-ключ не имеет скоупа sale
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
429 RATE_LIMITED Превышен лимит запросов. Точное значение — в заголовке x-ratelimit-limit. Повторите после срока из заголовка Retry-After

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

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