Агрегация лидов

POST /v1/leads/aggregate

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

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

• opportunity — сумма, каноническое имя, алиас amount. Числовые функции и groupBy
• stageId — статус, каноническое имя, алиас statusId. Для groupBy
• sourceId — источник. Для groupBy
• assignedById — ответственный. Для groupBy

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

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

Примеры

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

curl -X POST "https://vibecode.bitrix24.tech/v1/leads/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [
      { "field": "amount", "function": "sum" },
      { "field": "amount", "function": "avg" }
    ],
    "filter": { "sourceId": "WEB" },
    "groupBy": "statusId"
  }'

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

curl -X POST "https://vibecode.bitrix24.tech/v1/leads/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [
      { "field": "amount", "function": "sum" },
      { "field": "amount", "function": "avg" }
    ],
    "filter": { "sourceId": "WEB" },
    "groupBy": "statusId"
  }'

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

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

const { success, data } = await res.json()
console.log('Всего лидов:', data.count)
console.log('По статусам:', data.groups)

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

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

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

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

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

Подсчёт записей — count с полем "*", самый быстрый запрос без выгрузки записей. Без массива aggregate результат тот же:

{ "aggregate": [{ "field": "*", "function": "count" }] }

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

{
  "aggregate": [{ "field": "UF_CRM_BUDGET", "function": "sum" }],
  "groupBy": "UF_CRM_PRIORITY"
}

Поля ответа

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

Ответ на основной запрос (агрегации + groupBy: "statusId"):

{
  "success": true,
  "data": {
    "count": 100,
    "aggregates": {
      "amount": { "sum": 500000, "avg": 5000 }
    },
    "groups": [
      {
        "statusId": "NEW",
        "count": 60,
        "aggregates": { "amount": { "sum": 300000 } }
      },
      {
        "statusId": "CONVERTED",
        "count": 40,
        "aggregates": { "amount": { "sum": 200000 } }
      }
    ],
    "meta": {
      "totalRecords": 100,
      "recordsProcessed": 100,
      "truncated": false
    }
  }
}

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

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

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

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Field 'foo' not found. Available numeric fields: stageId, statusId, opportunity, amount, sourceId, assignedById"
  }
}

Ошибки

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

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

count vs числовые функции. count считается одним вызовом в Битрикс24 на любом объёме данных. Функции sum/avg/min/max подгружают записи постранично (максимум 5000) и считают на стороне Вайбкод — если под фильтр попадает больше 5000 записей, meta.truncated будет true, агрегация выполнится по первым 5000. Для точных счётчиков на больших выборках используйте count или сужайте фильтр. Потолок не единственная причина такой пометки: она появляется и когда прочитано меньше записей, чем обещал data.count, — размер нехватки лежит в data.meta.recordsShortfall.

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

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

Признак усечения приходит рядом с самим числом. Когда ответ приходит с meta.truncated: true, пометка truncated: true стоит внутри объекта каждого поля в data.aggregates, у каждого элемента data.groups, а в data.meta.warnings добавляется предупреждение с кодом AGGREGATE_TRUNCATED. Так клиент, который читает только само число, видит, что оно посчитано по части записей. На полном ответе ни одной из этих пометок нет. Полный разбор — Агрегация POST — потолок 5000 записей.

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

• Список лидов
• Поиск лидов
• Синтаксис фильтрации
• Лимиты и оптимизация