> For the complete documentation index, see [llms.txt](https://docs.fstrk.io/knowledge_base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fstrk.io/knowledge_base/api/obshaya-informaciya/analitika.md).

# Аналитика

#### GET /api/partners/bi/chats/

🔒 *bot-key или OAuth*

**Кратко:** Получить список чатов для аналитики (BI).

**Параметры запроса:**

* `limit` (integer, опциональный) — кол-во элементов на странице (макс. 500)
* `offset` (integer, опциональный) — кол-во элементов для пропуска
* `id` (integer, опциональный) — фильтр по числовому ID чата
* `status_changed_from` (string, date-time, опциональный) — дата последнего изменения статуса (начало)
* `status_changed_to` (string, date-time, опциональный) — дата последнего изменения статуса (конец)
* `updated_at_from` (string, date-time, опциональный) — дата последнего изменения (начало)
* `updated_at_to` (string, date-time, опциональный) — дата последнего изменения (конец)

**Возвращает:** `200 OK` — постраничный список объектов `CHChat`.

<details>

<summary>Пример ответа:</summary>

```json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 12345,
      "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "profile_id": 67890,
      "messenger_id": "123456789",
      "username": "ivan_ivanov",
      "platform": "Telegram",
      "first_name": "Иван",
      "last_name": "Иванов",
      "status": "active",
      "status_changed": "2024-06-01T10:00:00Z",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-06-01T10:00:00Z"
    }
  ]
}
```

</details>

**Ошибки:** 401 — ошибка авторизации.

**Пример запроса:**

```bash
curl -X GET "https://dashboard.fstrk.io/api/partners/bi/chats/?updated_at_from=2024-06-01T00:00:00Z&updated_at_to=2024-06-30T23:59:59Z&limit=500" \
  -H "bot-key: your_bot_key"
```

#### GET /api/partners/bi/profiles/

🔒 *bot-key или OAuth*

**Кратко:** Получить список клиентов для аналитики (BI).

**Параметры запроса:**

* `limit` (integer, опциональный) — кол-во элементов на странице (макс. 500)
* `offset` (integer, опциональный) — кол-во элементов для пропуска
* `id` (integer, опциональный) — фильтр по числовому ID профиля
* `created_at_from` (string, date-time, опциональный) — дата создания (начало)
* `created_at_to` (string, date-time, опциональный) — дата создания (конец)
* `updated_at_from` (string, date-time, опциональный) — дата обновления (начало)
* `updated_at_to` (string, date-time, опциональный) — дата обновления (конец)

**Возвращает:** `200 OK` — постраничный список объектов `CHCustomerProfile`: `id`, `uuid`, `full_name`, `phone_number`, `external_id`, `email`, `timezone`, `created_at`, `updated_at`, `tags`, `attrs`.

**Ошибки:** 401 — ошибка авторизации.

**Пример запроса:**

```bash
curl -X GET "https://dashboard.fstrk.io/api/partners/bi/profiles/?created_at_from=2024-01-01T00:00:00Z&limit=500" \
  -H "bot-key: your_bot_key"
```

#### GET /api/partners/bi/profiles/snapshot/

🔒 *bot-key или OAuth*

**Кратко:** Получить снимок данных по клиентам: общее количество и количество активных за период.

**Что делает:** Возвращает общее число клиентов бота на момент запроса и количество активных клиентов за указанный период. Период задаётся через `date_from`/`date_to` (максимум 31 день) или через одну дату `date`.

**Параметры запроса:**

* `date` (string, date, опциональный) — конкретная дата в формате `YYYY-MM-DD` (вместо `date_from`/`date_to`)
* `date_from` (string, date, опциональный) — начало периода в формате `YYYY-MM-DD`
* `date_to` (string, date, опциональный) — конец периода в формате `YYYY-MM-DD`
* `timezone` (string, опциональный) — часовая зона (по умолчанию `Europe/Moscow`)

**Возвращает:** `200 OK`:

* `customers_total` (integer) — общее кол-во клиентов на момент запроса
* `customers_active_count` (array) — активные клиенты за период: `date_from`, `date_to`, `count`

<details>

<summary>Пример ответа:</summary>

```json
{
  "customers_total": 85000,
  "customers_active_count": [
    {
      "date_from": "2024-06-01",
      "date_to": "2024-06-30",
      "count": 12400
    }
  ]
}
```

</details>

**Ошибки:** 400 — некорректные параметры дат; 401 — ошибка авторизации.

**Пример запроса:**

```bash
curl -X GET "https://dashboard.fstrk.io/api/partners/bi/profiles/snapshot/?date_from=2024-06-01&date_to=2024-06-30&timezone=Europe/Moscow" \
  -H "bot-key: your_bot_key"
```

#### GET /api/partners/bi/sessions/

🔒 *bot-key или OAuth*

**Кратко:** Получить список чат-сессий для аналитики (BI).

**Параметры запроса:**

* `limit` (integer, опциональный) — кол-во элементов на странице (макс. 500)
* `offset` (integer, опциональный) — кол-во элементов для пропуска
* `id` (integer, опциональный) — фильтр по числовому ID сессии
* `is_automatic` (boolean, опциональный) — фильтр по автоматическим сессиям
* `created_at_from` / `created_at_to` (string, date-time, опциональный) — диапазон дат создания
* `updated_at_from` / `updated_at_to` (string, date-time, опциональный) — диапазон дат обновления

**Возвращает:** `200 OK` — постраничный список объектов `CHChatCenterSession` с детальной статистикой по каждой сессии: длительность, время первого ответа оператора, среднее время ответа, количество сообщений, NPS и другие метрики.

<details>

<summary>Пример ответа:</summary>

```json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "title": null,
      "status": "closed",
      "is_automatic": false,
      "chat": {
        "id": 12345,
        "uuid": "7ab1c234-5678-4def-a012-3456789bcdef",
        "profile_id": 67890,
        "platform": "Telegram",
        "first_name": "Иван",
        "last_name": "Иванов",
        "status": "active"
      },
      "category": { "id": 1, "name": "Техподдержка" },
      "theme": { "id": 2, "name": "Проблема с оплатой" },
      "assigned_team": { "id": 1, "name": "Поддержка" },
      "assigned_operator": { "id": 5, "name": "Мария Петрова", "email": "maria@example.com" },
      "created_at": "2024-06-01T10:00:00Z",
      "updated_at": "2024-06-01T10:45:00Z",
      "closed_at": "2024-06-01T10:45:00Z",
      "assigned_first_time": "2024-06-01T10:02:00Z",
      "operator_first_reply_at": "2024-06-01T10:03:30Z",
      "operator_first_reply_time": 90,
      "operator_avg_reply_time": 60,
      "operator_reaction_time": 120,
      "duration": 2700,
      "messages_count": 18,
      "income_messages_count": 10,
      "outcome_messages_count": 8,
      "nps_value": "good",
      "nps_value_numeric": 5,
      "note": null,
      "variables": {}
    }
  ]
}
```

</details>

**Ошибки:** 401 — ошибка авторизации.

**Пример запроса:**

```bash
curl -X GET "https://dashboard.fstrk.io/api/partners/bi/sessions/?created_at_from=2024-06-01T00:00:00Z&created_at_to=2024-06-30T23:59:59Z&limit=500" \
  -H "bot-key: your_bot_key"
```

#### POST /api/partners/bi/sessions/reports/

🔒 *bot-key или OAuth*

**Кратко:** Сформировать отчёт по сессиям за период и получить его через email или callback.

**Что делает:** Асинхронно создаёт задачу на выгрузку отчёта. В ответе возвращает `task_uuid`, по которому можно отслеживать статус. Отчёт отправляется на указанный email и/или передаётся на callback URL.

**Тело запроса:**

* `start_at` (string, date-time, обязательный) — начало периода
* `end_at` (string, date-time, обязательный) — конец периода
* `email` (string, опциональный) — email для получения ссылки на отчёт
* `callback_url` (string, uri, опциональный) — URL для передачи результата

**Возвращает:** `201 Created`:

* `task_uuid` (uuid) — идентификатор задачи выгрузки

**Ошибки:** 400 — некорректные параметры; 401 — ошибка авторизации.

**Пример запроса:**

```bash
curl -X POST https://dashboard.fstrk.io/api/partners/bi/sessions/reports/ \
  -H "Content-Type: application/json" \
  -H "bot-key: your_bot_key" \
  -d '{
    "start_at": "2024-06-01T00:00:00Z",
    "end_at": "2024-06-30T23:59:59Z",
    "email": "analytics@example.com",
    "callback_url": "https://your-service.com/reports/callback"
  }'
```

#### GET /api/partners/bi/sessions/reports/{task\_uuid}/

🔒 *bot-key или OAuth*

**Кратко:** Получить статус задачи на выгрузку отчёта по сессиям.

**Что делает:** Возвращает текущий статус задачи и ссылку на файл отчёта после завершения. Статус задачи и ссылка на файл доступны в течение **7 суток** с момента создания.

**Параметры пути:**

* `task_uuid` (uuid, обязательный) — UUID задачи выгрузки

**Возвращает:** `200 OK`:

* `complete` (integer) — прогресс выполнения (0–100)
* `file_url` (string, uri) — ссылка на готовый файл отчёта (после завершения)

<details>

<summary>Пример ответа:</summary>

```json
{
  "complete": 100,
  "file_url": "https://storage.example.com/reports/sessions_june_2024.xlsx"
}
```

</details>

**Ошибки:** 401 — ошибка авторизации; 404 — задача не найдена или истёк срок хранения.

**Пример запроса:**

```bash
curl -X GET https://dashboard.fstrk.io/api/partners/bi/sessions/reports/3fa85f64-5717-4562-b3fc-2c963f66afa6/ \
  -H "bot-key: your_bot_key"
```