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

Агрегация типов плательщиков

POST /v1/person-types/aggregate

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

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

Поле Назначение
active Признак активности — для groupBy
code Уникальный код — для groupBy
sort Порядок сортировки — числовое поле для sum, avg, min, max
id ID типа плательщика из списка типов плательщиков. Числовое поле для sum, avg, min, max

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

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

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

Примеры

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

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

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

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

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/person-types/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { id: 21 },
    aggregate: [{ field: '*', function: 'count' }],
    groupBy: ['active', 'code'],
    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/person-types/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { id: 21 },
    aggregate: [{ field: '*', function: 'count' }],
    groupBy: ['active', 'code'],
    groupOrderBy: [{ field: 'count', direction: 'desc' }],
    groupLimit: 10,
  }),
})

const { data } = await res.json()

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

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

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

JSON 
{ "filter": { "id": 21 } }

Сумма, среднее, минимум и максимум порядка сортировки:

JSON 
{
  "filter": { "id": 21 },
  "aggregate": [
    { "field": "*", "function": "count" },
    { "field": "sort", "function": "sum" },
    { "field": "sort", "function": "avg" },
    { "field": "sort", "function": "min" },
    { "field": "sort", "function": "max" }
  ]
}

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

JSON 
{
  "filter": { "id": 21, "code": "ABSENT_DOCS_PERSON_397F55D8FB1D" },
  "aggregate": [{ "field": "sort", "function": "sum" }],
  "groupBy": "active"
}

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

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.count number Общее количество типов под фильтр
data.aggregates object Числовые результаты по полю и функции, например { "sort": { "sum": 900 } }. При одном count — пустой объект
data.aggregates.<поле>.truncated boolean Приходит со значением true, если числовые результаты посчитаны по неполной выборке
data.groups array Приходит при groupBy. Каждая группа содержит значения полей группировки, count и aggregates. Для active значение — boolean, для code — string или null
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": {},
    "groups": [
      {
        "active": false,
        "code": "DOCS_PERSON_397F55D8FB1D",
        "count": 1,
        "aggregates": {}
      }
    ],
    "meta": {
      "totalRecords": 1,
      "recordsProcessed": 1,
      "truncated": false,
      "groupTotal": 1,
      "groupsTruncated": false
    }
  }
}

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

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

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
400 INVALID_PARAMS Поле числовой функции не найдено. Сообщение перечисляет допустимые поля: id, sort
400 INVALID_PARAMS Поле op, field или function передано на верхнем уровне без массива aggregate
400 INVALID_PARAMS groupBy передан не строкой и не массивом строк, либо массив содержит значение другого типа
400 INVALID_PARAMS Поле группировки не входит в active, code
400 INVALID_PARAMS В groupBy больше 5 полей
400 INVALID_PARAMS В groupBy зарезервированное имя: count, aggregates, meta, groups
400 INVALID_PARAMS groupOrderBy передан без groupBy
400 INVALID_PARAMS groupOrderBy передан не массивом, его элемент не содержит строкового field, поле отсутствует в группировке или выражениях агрегации, либо direction отличается от asc и desc
400 INVALID_PARAMS groupLimit передан без groupBy
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 записей, а запрос требует числовых вычислений или группировки. Записи не выгружаются. Сузьте фильтр
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 — Ошибки.

Известные особенности

Запрос без группировки и числовых функций подсчитывает записи без их выгрузки. Для числовых вычислений и любой группировки, включая группировку с одним count, действует ограничение 5000 записей. Если для портала включён отказ при превышении этого ограничения и под фильтр попало больше записей, запрос возвращает 422 AGGREGATION_LIMIT_EXCEEDED без их выгрузки. Иначе записи читаются постранично, максимум 5000. Для точного подсчёта на большой выборке используйте запрос без группировки и числовых функций. Для вычислений по всей выборке сужайте фильтр. Подробнее — Агрегация POST — потолок 5000 записей.

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