#Агрегация оплат

POST /v1/payments/aggregate

Подсчёт количества оплат и числовые агрегации (sum, avg, min, max) по полю sum. Поддерживает фильтрацию и группировку по paySystemId, orderId, currency, paid, responsibleId.

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

Поле Назначение
sum Единственное числовое поле — подходит для sum / avg / min / max (название поля и функции совпадают, но это разные сущности)
paySystemId, orderId, responsibleId Идентификаторы — используются в groupBy (по платёжной системе, заказу, ответственному)
currency Категориальное — используется в groupBy (по валюте)
paid Логическое — используется в groupBy (оплачено / не оплачено)

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

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

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

#Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/payments/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [{ "field": "sum", "function": "sum" }],
    "groupBy": "paySystemId"
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/payments/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [{ "field": "sum", "function": "sum" }],
    "groupBy": "paySystemId"
  }'

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

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

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

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

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

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

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

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

JSON 
{}

Сумма всех принятых оплат:

JSON 
{
  "aggregate": [{ "field": "sum", "function": "sum" }],
  "filter": { "paid": true }
}

Топ-3 платёжных систем по сумме с сортировкой:

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

#Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.count number Общее количество оплат, соответствующих фильтру
data.aggregates object Результаты агрегаций: { "sum": { "sum": ..., "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": 99,
    "aggregates": {
      "sum": { "sum": 8475.87 }
    },
    "groups": [
      {
        "paySystemId": 11,
        "count": 87,
        "aggregates": { "sum": { "sum": 5870.5 } }
      },
      {
        "paySystemId": 6,
        "count": 8,
        "aggregates": { "sum": { "sum": 2025.37 } }
      },
      {
        "paySystemId": 25,
        "count": 4,
        "aggregates": { "sum": { "sum": 580 } }
      }
    ],
    "meta": {
      "totalRecords": 99,
      "recordsProcessed": 99,
      "truncated": false,
      "groupTotal": 3,
      "groupsTruncated": false
    }
  }
}

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

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

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

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Unknown field 'foo'. Available: sum, currency, paid, paySystemId, orderId, responsibleId"
  }
}

#Ошибки

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.

Группировка по currency важна на мультивалютных порталах. Сумма всех оплат в data.aggregates.sum.sum без groupBy: "currency" смешивает разные валюты — реальный смысл получается только при разделении.

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