184 lines
6.9 KiB
Markdown
184 lines
6.9 KiB
Markdown
# Требования к API для аналитики по проектам
|
||
|
||
## Endpoint
|
||
|
||
```
|
||
GET /api/v1/workspaces/{workspace_id}/analytics/projects
|
||
```
|
||
|
||
## Параметры запроса (Query Parameters)
|
||
|
||
| Параметр | Тип | Обязательный | Описание |
|
||
|----------|-----|-------------|----------|
|
||
| `project_ids` | `string[]` | Нет | Массив UUID проектов для фильтрации. Если не указан - все проекты workspace |
|
||
| `date_from` | `string (ISO 8601)` | Нет | Начало периода (например: `2024-12-01T00:00:00Z`) |
|
||
| `date_to` | `string (ISO 8601)` | Нет | Конец периода (например: `2024-12-31T23:59:59Z`) |
|
||
| `grouping` | `enum: "day" \| "week" \| "month" \| "quarter"` | Да | Группировка данных по периодам |
|
||
| `date_grouping` | `enum: "purchase_date" \| "link_date" \| "placement_date"` | Да | По какой дате группировать размещения |
|
||
| `metrics` | `string[]` | Нет | Массив метрик для расчета. Если не указан - возвращаются все доступные метрики |
|
||
|
||
### Доступные метрики:
|
||
- `total_cost` - Сумма расходов
|
||
- `purchases_count` - Количество закупов (размещений)
|
||
- `total_subscriptions` - Общее количество подписок
|
||
- `total_views` - Общее количество просмотров
|
||
- `avg_cpf` - Средний CPF (cost per follower)
|
||
- `avg_cpm` - Средний CPM (cost per mille)
|
||
- `avg_post_cost` - Средняя стоимость поста
|
||
- `clicks_count` - Количество переходов (кликов)
|
||
- `reach_volume` - Объем охвата
|
||
- `total_discounts` - Сумма скидок
|
||
- `avg_discount_percent` - Средний процент скидки
|
||
- `avg_conversion` - Средняя конверсия закупов
|
||
|
||
## Формат ответа
|
||
|
||
```json
|
||
{
|
||
"periods": [
|
||
{
|
||
"period": "2024-12-01",
|
||
"period_label": "1 дек",
|
||
"metrics": {
|
||
"total_cost": 5500.0,
|
||
"purchases_count": 3,
|
||
"total_subscriptions": 156,
|
||
"total_views": 8500,
|
||
"avg_cpf": 35.26,
|
||
"avg_cpm": 647.06,
|
||
"avg_post_cost": 1833.33,
|
||
"clicks_count": 156,
|
||
"reach_volume": 8500,
|
||
"total_discounts": 0.0,
|
||
"avg_discount_percent": 0.0,
|
||
"avg_conversion": 0.0
|
||
}
|
||
},
|
||
{
|
||
"period": "2024-12-02",
|
||
"period_label": "2 дек",
|
||
"metrics": {
|
||
"total_cost": 3200.0,
|
||
"purchases_count": 2,
|
||
"total_subscriptions": 89,
|
||
"total_views": 4200,
|
||
"avg_cpf": 35.96,
|
||
"avg_cpm": 761.9,
|
||
"avg_post_cost": 1600.0,
|
||
"clicks_count": 89,
|
||
"reach_volume": 4200,
|
||
"total_discounts": 0.0,
|
||
"avg_discount_percent": 0.0,
|
||
"avg_conversion": 0.0
|
||
}
|
||
}
|
||
],
|
||
"totals": {
|
||
"total_cost": 8700.0,
|
||
"purchases_count": 5,
|
||
"total_subscriptions": 245,
|
||
"total_views": 12700,
|
||
"avg_cpf": 35.51,
|
||
"avg_cpm": 685.04,
|
||
"avg_post_cost": 1740.0,
|
||
"clicks_count": 245,
|
||
"reach_volume": 12700,
|
||
"total_discounts": 0.0,
|
||
"avg_discount_percent": 0.0,
|
||
"avg_conversion": 0.0
|
||
}
|
||
}
|
||
```
|
||
|
||
## Примеры запросов
|
||
|
||
### Пример 1: График расходов по дням за декабрь
|
||
```http
|
||
GET /api/v1/workspaces/123e4567-e89b-12d3-a456-426614174000/analytics/projects?grouping=day&date_grouping=placement_date&date_from=2024-12-01T00:00:00Z&date_to=2024-12-31T23:59:59Z&metrics[]=total_cost&project_ids[]=proj-001&project_ids[]=proj-002
|
||
```
|
||
|
||
### Пример 2: Средний CPF по неделям
|
||
```http
|
||
GET /api/v1/workspaces/123e4567-e89b-12d3-a456-426614174000/analytics/projects?grouping=week&date_grouping=placement_date&metrics[]=avg_cpf&metrics[]=total_subscriptions
|
||
```
|
||
|
||
### Пример 3: Все метрики по месяцам
|
||
```http
|
||
GET /api/v1/workspaces/123e4567-e89b-12d3-a456-426614174000/analytics/projects?grouping=month&date_grouping=purchase_date&date_from=2024-01-01T00:00:00Z&date_to=2024-12-31T23:59:59Z
|
||
```
|
||
|
||
## Формат периода (period)
|
||
|
||
В зависимости от `grouping`:
|
||
- `day`: `"YYYY-MM-DD"` (например: `"2024-12-01"`)
|
||
- `week`: `"YYYY-Www"` (например: `"2024-W49"`) - ISO week format
|
||
- `month`: `"YYYY-MM"` (например: `"2024-12"`)
|
||
- `quarter`: `"YYYY-QN"` (например: `"2024-Q4"`)
|
||
|
||
## Формат period_label
|
||
|
||
Человекочитаемая метка периода для отображения на графике:
|
||
- `day`: `"1 дек"` или `"1 дек 2024"`
|
||
- `week`: `"49 нед. 2024"` или `"1-7 дек"`
|
||
- `month`: `"дек 2024"`
|
||
- `quarter`: `"Q4 2024"`
|
||
|
||
## Логика расчета метрик
|
||
|
||
### Агрегации (SUM):
|
||
- `total_cost` - сумма всех `cost`
|
||
- `total_subscriptions` - сумма всех `subscriptions_count`
|
||
- `total_views` - сумма всех `views_count`
|
||
- `total_discounts` - сумма всех скидок
|
||
- `clicks_count` - сумма всех кликов
|
||
- `reach_volume` - сумма всех просмотров (аналогично `total_views`)
|
||
|
||
### Счетчики (COUNT):
|
||
- `purchases_count` - количество размещений в периоде
|
||
|
||
### Средние значения (AVG):
|
||
- `avg_cpf` = `total_cost / total_subscriptions` (если `total_subscriptions > 0`)
|
||
- `avg_cpm` = `(total_cost / total_views) * 1000` (если `total_views > 0`)
|
||
- `avg_post_cost` = `total_cost / purchases_count` (если `purchases_count > 0`)
|
||
- `avg_discount_percent` = средний процент скидки по размещениям
|
||
- `avg_conversion` = средняя конверсия закупов
|
||
|
||
### Totals (итоговые значения):
|
||
Все метрики в `totals` рассчитываются как агрегация по всем периодам в ответе.
|
||
|
||
## Обработка ошибок
|
||
|
||
### 400 Bad Request
|
||
```json
|
||
{
|
||
"detail": [
|
||
{
|
||
"loc": ["query", "grouping"],
|
||
"msg": "Invalid grouping value. Must be one of: day, week, month, quarter",
|
||
"type": "value_error"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 422 Unprocessable Entity
|
||
```json
|
||
{
|
||
"detail": [
|
||
{
|
||
"loc": ["query", "date_from"],
|
||
"msg": "date_from must be before date_to",
|
||
"type": "value_error"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## Примечания
|
||
|
||
- Если для метрики нет данных (например, `total_discounts`), возвращается `0` или `null`
|
||
- Если знаменатель равен 0 при расчете средних значений, возвращается `null`
|
||
- Периоды сортируются по возрастанию (`period`)
|
||
- Если данных нет для какого-то периода, он не включается в ответ (или включается с нулевыми значениями - на усмотрение бэкенда)
|
||
|