#Агрегация контактов

POST /v1/contacts/aggregate

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

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

  • typeId — тип контакта (для groupBy)
  • sourceId — источник (для groupBy)
  • assignedById — ответственный (для groupBy)

Все поля в aggregatable — категориальные идентификаторы, поэтому по стандартным полям работают count и groupBy. Для числовых функций (sum/avg/min/max) используйте пользовательские поля.

Пользовательские поля (UF): UF-поля типов integer, double, money — для числовых функций; UF любого типа — для groupBy. Полный список UF-полей конкретного портала приходит в тексте ошибки INVALID_PARAMS, если передать несуществующее имя.

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

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

#Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/contacts/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "assignedById": 1 },
    "groupBy": "typeId"
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/contacts/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "assignedById": 1 },
    "groupBy": "typeId"
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/contacts/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { assignedById: 1 },
    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/contacts/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { assignedById: 1 },
    groupBy: 'typeId',
  }),
})

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

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

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

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

JSON 
{}

Работа с пользовательскими полями (UF) — sum по UF + группировка по другому UF:

JSON 
{
  "aggregate": [{ "field": "UF_CRM_LTV", "function": "sum" }],
  "groupBy": "UF_CRM_SEGMENT"
}

#Поля ответа

Поле Тип Описание
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": 1200,
    "aggregates": {},
    "groups": [
      { "typeId": "CLIENT", "count": 800 },
      { "typeId": "SUPPLIER", "count": 300 },
      { "typeId": "PARTNER", "count": 100 }
    ],
    "meta": {
      "totalRecords": 1200,
      "recordsProcessed": 1200,
      "truncated": false
    }
  }
}

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

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

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

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupBy field 'name' is not aggregatable on this entity. Available: typeId, sourceId, assignedById"
  }
}

#Ошибки

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

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

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

Money-поля. UF-поля типа money хранятся в формате "сумма|валюта" ("1500|RUB") — агрегат извлекает числовую часть автоматически, складывать можно без парсинга.

Фильтрация по UF работает. В filter можно передавать любые поля — стандартные и пользовательские, любого типа. Например, { "filter": { "ufCrm_1234": "value" } } вернёт количество контактов с этим значением UF.

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