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

`POST /v1/openline-configs/aggregate`

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

**Группировка.** `groupBy` принимает 2 поля: `active`, `queueType` — это `aggregatable`-поля из [`GET /v1/openline-configs/fields`](/docs/openlines/config/fields). Остальные поля (`id`, `name`, `workTimeFrom`, `workTimeTo` и прочие camelCase-поля ответа) в `groupBy` отвергаются с `400 INVALID_PARAMS` — подробности в [Известных особенностях](#известные-особенности).

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

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

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

## Примеры

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

```bash
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-приложение

```bash
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"]`. Принимаются комбинации из 2 допустимых полей: `active`, `queueType`.

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

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

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

```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 | Сколько записей обработано во входной выборке. Без `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 — [Ошибки](/docs/errors).

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

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

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

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

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

- [Список конфигураций](/docs/openlines/config/list)
- [Синтаксис фильтрации](/docs/filtering)
- [Лимиты и оптимизация](/docs/optimization)