#Агрегация конфигураций открытых линий

POST /v1/openline-configs/aggregate

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

Группировка. groupBy принимает 4 поля: active, queueType, agentId, lineId — это aggregatable-поля из `GET /v1/openline-configs/fields`. Остальные поля схемы (id, name, workTimeFrom, workTimeTo) и UPPER_SNAKE_CASE-поля ответа в groupBy отвергаются с 400 INVALID_PARAMS — подробности в Известных особенностях.

Числовые агрегации (sum/avg/min/max) не применимы. Поля openline-configs — категориальные или идентификационные; поддерживается только функция count с field: "*".

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

Параметр Тип Обяз. Описание
aggregate array нет Массив агрегаций. Каждый элемент: { "field": "*", "function": "count" }. Функция count требует field: "*". Без параметра — только count
filter object нет Фильтрация. Синтаксис фильтрации. Пример: {"active": false}
groupBy string | string[] нет Поле или массив полей для группировки. Допустимые значения: active, queueType, agentId, lineId — см. Известные особенности

#Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/openline-configs/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "groupBy": "queueType"
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/openline-configs/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "groupBy": "queueType"
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/openline-configs/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    groupBy: 'queueType',
  }),
})

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/openline-configs/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    groupBy: 'queueType',
  }),
})

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

Для группировки по нескольким полям передайте массив: "groupBy": ["queueType", "active"]. Принимаются комбинации из 4 допустимых полей: active, queueType, agentId, lineId.

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

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

JSON 
{}

Явная передача count через aggregate:

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

#Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.count number Итоговое количество конфигураций в выборке (после применения фильтра, если он сработал). Это основной показатель для приложения
data.aggregates object Результаты агрегаций (для openline-configs всегда {})
data.groups array Группы (только при groupBy). Каждый элемент: поле группировки + count + aggregates
data.meta.totalRecords number Сколько записей увидел aggregator во входной выборке. Без groupBy совпадает с data.count; с groupBy равен сумме count по всем группам. Техническая метрика
data.meta.recordsProcessed number Сколько записей реально обработано при группировке. 0, если groupBy не передан
data.meta.truncated boolean true, если под выборку попало более 5000 записей
data.meta.groupTotal number Количество групп в результате (только при groupBy)
data.meta.groupsTruncated boolean Признак усечения списка групп (только при groupBy)

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

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

JSON 
{
  "success": true,
  "data": {
    "count": 10,
    "aggregates": {},
    "groups": [
      { "queueType": "all", "count": 9, "aggregates": {} },
      { "queueType": "evenly", "count": 1, "aggregates": {} }
    ],
    "meta": {
      "totalRecords": 10,
      "recordsProcessed": 10,
      "truncated": false,
      "groupTotal": 2,
      "groupsTruncated": false
    }
  }
}

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

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

400 — функция count с неверным именем поля:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "count aggregate requires field \"*\""
  }
}

#Ошибки

HTTP Код Описание
400 INVALID_PARAMS Функция count передана с field не равным "*", или передан groupBy по полю не из схемы Вайбкода
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
403 SCOPE_DENIED API-ключ не имеет скоупа imopenlines

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

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

Параметр filter в aggregate игнорируется. Передача {"filter": {"active": false}} не влияет на результат — метод возвращает count по всем конфигурациям портала. Причина: aggregate обходит записи через метод списка imopenlines.config.list.get, который на стороне Битрикс24 фильтр для openline-configs не применяет. Для подсчёта по подмножеству используйте groupBy (например, groupBy: ["active"] разобьёт результат по признаку активности) или обрабатывайте результат `POST /v1/openline-configs/search` на стороне клиента.

Функция count требует field: "*". При передаче {"field": "id", "function": "count"} возвращается 400 INVALID_PARAMS. Единственный корректный формат: {"field": "*", "function": "count"}.

groupBy принимает только 4 поля из схемы Вайбкода: active, queueType, agentId, lineId. Это aggregatable-поля из ответа `GET /v1/openline-configs/fields`. Остальные поля схемы (id, name, workTimeFrom, workTimeTo) и UPPER_SNAKE_CASE-поля (QUEUE_TIME, CRM, ...) в groupBy отвергаются с 400 INVALID_PARAMS и сообщением «groupBy field 'X' is not aggregatable on this entity. Available: active, queueType, agentId, lineId».

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