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

POST /v1/order-statuses/aggregate

Подсчёт количества статусов с группировкой по type или notify. У сущности нет числовых полей, поэтому числовые функции (sum, avg) не применяются — основной сценарий — count с фильтром или группировкой.

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

Все поля статуса категориальные — подходят только для groupBy и filter:

Поле Назначение
type Группировка по типу: O (заказа) или D (доставки)
notify Группировка по тому, отправляется ли уведомление

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

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

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

#Примеры

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

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

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

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

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

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

const { success, data } = await res.json()
console.log('Распределение статусов:', data.groups)

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

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

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

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

Общее количество статусов на портале:

JSON 
{}

Сколько статусов с включённым уведомлением:

JSON 
{
  "filter": { "notify": true }
}

Группировка по обоим осям сразу:

JSON 
{
  "groupBy": ["type", "notify"]
}

#Поля ответа

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

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

JSON 
{
  "success": true,
  "data": {
    "count": 9,
    "aggregates": {},
    "groups": [
      { "type": "O", "count": 6, "aggregates": {} },
      { "type": "D", "count": 3, "aggregates": {} }
    ],
    "meta": {
      "totalRecords": 9,
      "recordsProcessed": 9,
      "truncated": false,
      "groupTotal": 2,
      "groupsTruncated": false
    }
  }
}

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

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

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

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Unknown field 'foo'. Available: type, notify"
  }
}

#Ошибки

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 имеет смысл. Поскольку в схеме статуса нет числовых полей в aggregatable, функции sum / avg / min / max всегда возвращают пустой aggregates. Для подсчёта статусов используйте count (без aggregate) с фильтром или группировкой.

Малый объём данных. На порталах число статусов измеряется десятками, поэтому meta.truncated (срабатывает только при > 5000 записей) для этой сущности не активируется.

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