#Агрегация дел

POST /v1/activities/aggregate

Подсчёт количества дел с фильтрацией и группировкой.

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

  • typeId — тип активности (для groupBy)
  • ownerTypeId — тип родительской сущности (для groupBy)
  • responsibleId — ответственный (для groupBy)
  • completed — статус выполнения (для groupBy)

Все поля в aggregatable — категориальные идентификаторы, поэтому основной сценарий — count с группировкой. Числовые функции sum/avg/min/max применяются редко.

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

Параметр Тип Обяз. Описание
aggregate array нет Массив агрегаций. Каждый элемент: { "field": "*", "function": "count" }. Без массива — только count
filter object нет Фильтрация по полям GET /v1/activities/fields. Синтаксис фильтрации
groupBy string | string[] нет Поле или массив полей для группировки (максимум 5). Допустимые значения — из списка выше

#Примеры

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

Количество дел по сделке (ownerTypeId: 2 — сделка), сгруппированное по типу активности:

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/activities/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "ownerTypeId": 2, "ownerId": 741, "completed": "Y" },
    "groupBy": "typeId"
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/activities/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "ownerTypeId": 2, "ownerId": 741, "completed": "Y" },
    "groupBy": "typeId"
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/activities/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { ownerTypeId: 2, ownerId: 741, completed: 'Y' },
    groupBy: 'typeId',
  }),
})

const { success, data } = await res.json()
console.log('Всего завершённых дел по сделке:', data.count)
console.log('Распределение по типу:', data.groups)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/activities/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { ownerTypeId: 2, ownerId: 741, completed: 'Y' },
    groupBy: 'typeId',
  }),
})

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

Для группировки по нескольким полям передайте массив: "groupBy": ["typeId", "completed"] (максимум 5).

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

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

JSON 
{}

Группировка дел по контакту (ownerTypeId: 3) по статусу выполнения:

JSON 
{
  "filter": { "ownerTypeId": 3, "ownerId": 485 },
  "groupBy": "completed"
}

#Поля ответа

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

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

Ответ на основной запрос (groupBy: "typeId"):

JSON 
{
  "success": true,
  "data": {
    "count": 2600,
    "aggregates": {},
    "groups": [
      { "typeId": 1, "count": 1200 },
      { "typeId": 2, "count": 800 },
      { "typeId": 6, "count": 600 }
    ],
    "meta": {
      "totalRecords": 2600,
      "recordsProcessed": 2600,
      "truncated": false
    }
  }
}

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

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

400 — groupBy по неаггрегируемому полю или несуществующему полю:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupBy field 'subject' is not aggregatable on this entity. Available: typeId, ownerTypeId, responsibleId, completed"
  }
}

#Ошибки

HTTP Код Описание
400 INVALID_PARAMS groupBy по неаггрегируемому полю или больше 5 полей в groupBy
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
403 SCOPE_DENIED API-ключ не имеет скоупа crm

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

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

Универсальный ownerTypeId. Для счётчиков по родительской сущности используйте пары ownerTypeId + ownerId: 2 — сделка, 3 — контакт, 4 — компания, 1 — лид. Это самый частый сценарий для /v1/activities/aggregate.

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