1079 lines
40 KiB
Markdown
1079 lines
40 KiB
Markdown
# API Документация: Маркетинговый анализ и стратегии (Frontend/AI Agent)
|
|
|
|
## Базовый URL
|
|
|
|
```
|
|
https://api.konturai.kz
|
|
```
|
|
|
|
## Обзор
|
|
|
|
API для генерации маркетингового анализа и стратегий на основе данных о бизнесе. Все эндпоинты требуют JWT аутентификации для связи данных с пользователем.
|
|
|
|
**Важные изменения:**
|
|
|
|
- ✅ Все эндпоинты теперь требуют JWT токен в заголовке `Authorization`
|
|
- ✅ Пользователи могут видеть только свои анализы и стратегии
|
|
- ✅ Добавлена детальная история статусов для каждого анализа и стратегии
|
|
- ✅ Новые эндпоинты для получения списка всех анализов/стратегий пользователя
|
|
- ✅ **НОВОЕ**: Добавлена поддержка типов анализов (РЫНОК, КОНКУРЕНТЫ, ЦА, КАНАЛЫ, SWOT)
|
|
|
|
---
|
|
|
|
## Аутентификация
|
|
|
|
Все запросы должны включать JWT токен в заголовке `Authorization`:
|
|
|
|
```
|
|
Authorization: Bearer <your_jwt_token>
|
|
```
|
|
|
|
### Структура JWT токена
|
|
|
|
JWT токен содержит следующую информацию:
|
|
|
|
- **sub**: Email пользователя
|
|
- **uid**: ID пользователя (Long) - используется для связи данных
|
|
- **roles**: Роли пользователя (String, разделённые запятыми)
|
|
|
|
### Ошибки аутентификации
|
|
|
|
Если токен отсутствует или невалиден, API вернет:
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"message": "Не авторизован",
|
|
"error": {
|
|
"code": "UNAUTHORIZED",
|
|
"message": "Требуется аутентификация. Пожалуйста, предоставьте валидный JWT токен."
|
|
}
|
|
}
|
|
```
|
|
|
|
**HTTP статус**: `401 Unauthorized`
|
|
|
|
---
|
|
|
|
## Эндпоинты
|
|
|
|
### 1. Запуск маркетингового анализа
|
|
|
|
**POST** `/api/marketing/analysis/start`
|
|
|
|
Создает новую задачу на генерацию маркетингового анализа и запускает асинхронную обработку. Анализ автоматически связывается с пользователем из JWT токена.
|
|
|
|
#### Заголовки запроса
|
|
|
|
```
|
|
Content-Type: application/json
|
|
Authorization: Bearer <your_jwt_token>
|
|
```
|
|
|
|
#### Тело запроса (JSON)
|
|
|
|
| Поле | Тип | Обязательный | Описание | Пример значения |
|
|
| ---------------- | ------ | ------------ | ------------------------------ | -------------------------------- |
|
|
| `product` | string | ✅ | Название продукта или услуги | "Веб-разработка" |
|
|
| `location` | string | ✅ | Географическая локация работы | "Алматы, Казахстан" |
|
|
| `client` | string | ✅ | Тип целевой аудитории | "B2B клиенты" |
|
|
| `differentiator` | string | ✅ | Уникальные особенности бизнеса | "Быстрая разработка за 2 недели" |
|
|
| `analysisType` | string | ✅ | Тип анализа для генерации | "РЫНОК" |
|
|
|
|
#### Валидация полей
|
|
|
|
**`product`** (string, обязательное)
|
|
|
|
- Минимальная длина: 3 символа
|
|
- Максимальная длина: 200 символов
|
|
|
|
**`location`** (string, обязательное)
|
|
|
|
- Минимальная длина: 2 символа
|
|
- Максимальная длина: 150 символов
|
|
|
|
**`client`** (string, обязательное)
|
|
|
|
- Допустимые значения:
|
|
- `"B2B клиенты"`
|
|
- `"B2C клиенты"`
|
|
- `"Частные лица"`
|
|
- `"Корпорации"`
|
|
- `"Малый бизнес"`
|
|
|
|
**`differentiator`** (string, обязательное)
|
|
|
|
- Минимальная длина: 10 символов
|
|
- Максимальная длина: 500 символов
|
|
|
|
**`analysisType`** (string, обязательное)
|
|
|
|
- Допустимые значения (регистр не важен, но рекомендуется использовать заглавные буквы):
|
|
- `"РЫНОК"` - Анализ рынка (размер рынка, динамика роста, сегменты, тренды)
|
|
- `"КОНКУРЕНТЫ"` - Анализ конкурентов (основные конкуренты, их сильные/слабые стороны, позиционирование)
|
|
- `"ЦА"` - Анализ целевой аудитории (демография, психография, потребности, поведение)
|
|
- `"КАНАЛЫ"` - Анализ маркетинговых каналов (эффективность каналов, рекомендации по выбору)
|
|
- `"SWOT"` - SWOT-анализ (сильные стороны, слабые стороны, возможности, угрозы)
|
|
|
|
#### Пример запроса
|
|
|
|
```javascript
|
|
const response = await fetch('https://api.konturai.kz/api/marketing/analysis/start', {
|
|
method: 'POST',
|
|
headers: {
|
|
'Content-Type': 'application/json',
|
|
Authorization: `Bearer ${jwtToken}`
|
|
},
|
|
body: JSON.stringify({
|
|
product: 'Разработка мобильных приложений',
|
|
location: 'Нур-Султан, Казахстан',
|
|
client: 'B2B клиенты',
|
|
differentiator: 'Специализируемся на быстрой разработке MVP за 4 недели',
|
|
analysisType: 'РЫНОК'
|
|
})
|
|
});
|
|
```
|
|
|
|
#### Пример успешного ответа (200 OK)
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Анализ запущен успешно",
|
|
"data": {
|
|
"analysisId": "507f1f77bcf86cd799439011",
|
|
"status": "processing",
|
|
"estimatedCompletionTime": "2025-01-20T15:38:00",
|
|
"message": "Анализ запущен успешно. Результаты будут готовы в течение 5-10 минут."
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 2. Получение результата анализа
|
|
|
|
**GET** `/api/marketing/analysis/{analysisId}`
|
|
|
|
Возвращает статус и результаты анализа по идентификатору. Пользователь может получить только свои анализы.
|
|
|
|
#### Заголовки запроса
|
|
|
|
```
|
|
Authorization: Bearer <your_jwt_token>
|
|
```
|
|
|
|
#### Параметры пути
|
|
|
|
| Параметр | Тип | Описание |
|
|
| ------------ | ------ | --------------------- |
|
|
| `analysisId` | string | Идентификатор анализа |
|
|
|
|
#### Пример запроса
|
|
|
|
```javascript
|
|
const response = await fetch(`https://api.konturai.kz/api/marketing/analysis/${analysisId}`, {
|
|
headers: {
|
|
Authorization: `Bearer ${jwtToken}`
|
|
}
|
|
});
|
|
```
|
|
|
|
#### Пример ответа (когда анализ завершен - 200 OK)
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Операция выполнена успешно",
|
|
"data": {
|
|
"analysisId": "507f1f77bcf86cd799439011",
|
|
"status": "completed",
|
|
"createdAt": "2025-01-20T15:30:00",
|
|
"completedAt": "2025-01-20T15:38:00",
|
|
"report": {
|
|
"summary": "Краткое резюме анализа...",
|
|
"targetAudience": {
|
|
"description": "Описание целевой аудитории...",
|
|
"channels": ["Instagram", "LinkedIn", "Telegram"]
|
|
},
|
|
"recommendations": ["Рекомендация 1", "Рекомендация 2"],
|
|
"strategy": {
|
|
"duration": "2 недели",
|
|
"channels": ["Instagram", "Telegram", "21MC"],
|
|
"contentTypes": ["посты", "сторис", "баннеры"]
|
|
},
|
|
"pdfUrl": "/api/marketing/analysis/507f1f77bcf86cd799439011/download"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Статусы анализа
|
|
|
|
| Статус | Описание |
|
|
| ------------ | ----------------------------- |
|
|
| `queued` | Запрос в очереди на обработку |
|
|
| `processing` | Анализ выполняется |
|
|
| `completed` | Анализ завершен успешно |
|
|
| `failed` | Анализ завершился с ошибкой |
|
|
|
|
#### Ошибки доступа
|
|
|
|
Если пользователь пытается получить доступ к анализу другого пользователя:
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"message": "Доступ запрещен",
|
|
"error": {
|
|
"code": "FORBIDDEN",
|
|
"message": "У вас нет доступа к этому анализу"
|
|
}
|
|
}
|
|
```
|
|
|
|
**HTTP статус**: `403 Forbidden`
|
|
|
|
---
|
|
|
|
### 3. Получение списка всех анализов пользователя
|
|
|
|
**GET** `/api/marketing/analysis/my`
|
|
|
|
Возвращает список всех анализов текущего пользователя, отсортированных по дате создания (новые первыми).
|
|
|
|
#### Заголовки запроса
|
|
|
|
```
|
|
Authorization: Bearer <your_jwt_token>
|
|
```
|
|
|
|
#### Пример запроса
|
|
|
|
```javascript
|
|
const response = await fetch('https://api.konturai.kz/api/marketing/analysis/my', {
|
|
headers: {
|
|
Authorization: `Bearer ${jwtToken}`
|
|
}
|
|
});
|
|
```
|
|
|
|
#### Пример успешного ответа (200 OK)
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Операция выполнена успешно",
|
|
"data": [
|
|
{
|
|
"analysisId": "507f1f77bcf86cd799439011",
|
|
"product": "Разработка мобильных приложений",
|
|
"location": "Нур-Султан, Казахстан",
|
|
"clientType": "B2B клиенты",
|
|
"differentiator": "Быстрая разработка MVP за 4 недели",
|
|
"status": "completed",
|
|
"userId": "12345",
|
|
"createdAt": "2025-01-20T15:30:00",
|
|
"completedAt": "2025-01-20T15:38:00",
|
|
"statusHistory": [
|
|
{
|
|
"status": "queued",
|
|
"timestamp": "2025-01-20T15:30:00",
|
|
"message": "Анализ создан и добавлен в очередь"
|
|
},
|
|
{
|
|
"status": "processing",
|
|
"timestamp": "2025-01-20T15:30:05",
|
|
"message": "Начата обработка анализа"
|
|
},
|
|
{
|
|
"status": "completed",
|
|
"timestamp": "2025-01-20T15:38:00",
|
|
"message": "Анализ успешно завершен"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"analysisId": "507f1f77bcf86cd799439012",
|
|
"product": "Веб-разработка",
|
|
"location": "Алматы, Казахстан",
|
|
"clientType": "B2C клиенты",
|
|
"differentiator": "Современные технологии",
|
|
"status": "processing",
|
|
"userId": "12345",
|
|
"createdAt": "2025-01-20T14:00:00",
|
|
"completedAt": null,
|
|
"statusHistory": [
|
|
{
|
|
"status": "queued",
|
|
"timestamp": "2025-01-20T14:00:00",
|
|
"message": "Анализ создан и добавлен в очередь"
|
|
},
|
|
{
|
|
"status": "processing",
|
|
"timestamp": "2025-01-20T14:00:05",
|
|
"message": "Начата обработка анализа"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### Структура ответа
|
|
|
|
| Поле | Тип | Описание |
|
|
| ---------------------------------- | ------ | ------------------------------------------------------ |
|
|
| `data[].analysisId` | string | Уникальный идентификатор анализа |
|
|
| `data[].product` | string | Название продукта или услуги |
|
|
| `data[].location` | string | Географическая локация |
|
|
| `data[].clientType` | string | Тип целевой аудитории |
|
|
| `data[].differentiator` | string | Уникальные особенности бизнеса |
|
|
| `data[].status` | string | Текущий статус анализа |
|
|
| `data[].userId` | string | ID пользователя (из JWT) |
|
|
| `data[].createdAt` | string | ISO 8601 дата/время создания |
|
|
| `data[].completedAt` | string | ISO 8601 дата/время завершения (null если не завершен) |
|
|
| `data[].statusHistory` | array | Детальная история изменений статуса |
|
|
| `data[].statusHistory[].status` | string | Статус на момент изменения |
|
|
| `data[].statusHistory[].timestamp` | string | ISO 8601 дата/время изменения статуса |
|
|
| `data[].statusHistory[].message` | string | Описание изменения статуса |
|
|
|
|
---
|
|
|
|
### 4. Получение детальной истории анализа
|
|
|
|
**GET** `/api/marketing/analysis/{analysisId}/history`
|
|
|
|
Возвращает детальную информацию об анализе, включая полную историю изменений статуса.
|
|
|
|
#### Заголовки запроса
|
|
|
|
```
|
|
Authorization: Bearer <your_jwt_token>
|
|
```
|
|
|
|
#### Параметры пути
|
|
|
|
| Параметр | Тип | Описание |
|
|
| ------------ | ------ | --------------------- |
|
|
| `analysisId` | string | Идентификатор анализа |
|
|
|
|
#### Пример запроса
|
|
|
|
```javascript
|
|
const response = await fetch(`https://api.konturai.kz/api/marketing/analysis/${analysisId}/history`, {
|
|
headers: {
|
|
Authorization: `Bearer ${jwtToken}`
|
|
}
|
|
});
|
|
```
|
|
|
|
#### Пример успешного ответа (200 OK)
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Операция выполнена успешно",
|
|
"data": {
|
|
"analysisId": "507f1f77bcf86cd799439011",
|
|
"product": "Разработка мобильных приложений",
|
|
"location": "Нур-Султан, Казахстан",
|
|
"clientType": "B2B клиенты",
|
|
"differentiator": "Быстрая разработка MVP за 4 недели",
|
|
"status": "completed",
|
|
"userId": "12345",
|
|
"createdAt": "2025-01-20T15:30:00",
|
|
"completedAt": "2025-01-20T15:38:00",
|
|
"statusHistory": [
|
|
{
|
|
"status": "queued",
|
|
"timestamp": "2025-01-20T15:30:00",
|
|
"message": "Анализ создан и добавлен в очередь"
|
|
},
|
|
{
|
|
"status": "processing",
|
|
"timestamp": "2025-01-20T15:30:05",
|
|
"message": "Начата обработка анализа"
|
|
},
|
|
{
|
|
"status": "completed",
|
|
"timestamp": "2025-01-20T15:38:00",
|
|
"message": "Анализ успешно завершен"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 5. Скачивание PDF отчета
|
|
|
|
**GET** `/api/marketing/analysis/{analysisId}/download`
|
|
|
|
Возвращает PDF файл с полным маркетинговым отчетом. Пользователь может скачать только свои отчеты.
|
|
|
|
#### Заголовки запроса
|
|
|
|
```
|
|
Authorization: Bearer <your_jwt_token>
|
|
```
|
|
|
|
#### Параметры пути
|
|
|
|
| Параметр | Тип | Описание |
|
|
| ------------ | ------ | --------------------- |
|
|
| `analysisId` | string | Идентификатор анализа |
|
|
|
|
#### Пример запроса
|
|
|
|
```javascript
|
|
const response = await fetch(`https://api.konturai.kz/api/marketing/analysis/${analysisId}/download`, {
|
|
headers: {
|
|
Authorization: `Bearer ${jwtToken}`
|
|
}
|
|
});
|
|
|
|
if (response.ok) {
|
|
const blob = await response.blob();
|
|
const url = window.URL.createObjectURL(blob);
|
|
const a = document.createElement('a');
|
|
a.href = url;
|
|
a.download = `marketing_analysis_${analysisId}.pdf`;
|
|
a.click();
|
|
}
|
|
```
|
|
|
|
#### Успешный ответ (200 OK)
|
|
|
|
- **Content-Type**: `application/pdf`
|
|
- **Content-Disposition**: `attachment; filename="marketing_analysis_{analysisId}_{timestamp}.pdf"`
|
|
- **Body**: Бинарные данные PDF файла
|
|
|
|
---
|
|
|
|
### 6. Генерация маркетинговой стратегии
|
|
|
|
**POST** `/api/marketing/analysis/strategy/generate`
|
|
|
|
Создает маркетинговую стратегию на основе завершенного анализа. Стратегия автоматически связывается с пользователем из JWT токена.
|
|
|
|
#### Заголовки запроса
|
|
|
|
```
|
|
Content-Type: application/json
|
|
Authorization: Bearer <your_jwt_token>
|
|
```
|
|
|
|
#### Параметры запроса
|
|
|
|
| Параметр | Тип | Обязательный | Описание |
|
|
| ------------------- | ------- | ------------ | --------------------------------------------- |
|
|
| `analysisId` | string | ✅ | ID завершенного анализа (query parameter) |
|
|
| `durationWeeks` | integer | ❌ | Длительность стратегии в неделях (default: 4) |
|
|
| `priorityPlatforms` | array | ❌ | Приоритетные платформы (массив строк) |
|
|
|
|
#### Тело запроса (JSON, опционально)
|
|
|
|
```json
|
|
{
|
|
"durationWeeks": 4,
|
|
"priorityPlatforms": ["Instagram", "LinkedIn", "Telegram"]
|
|
}
|
|
```
|
|
|
|
#### Пример запроса
|
|
|
|
```javascript
|
|
const response = await fetch(`https://api.konturai.kz/api/marketing/analysis/strategy/generate?analysisId=${analysisId}`, {
|
|
method: 'POST',
|
|
headers: {
|
|
'Content-Type': 'application/json',
|
|
Authorization: `Bearer ${jwtToken}`
|
|
},
|
|
body: JSON.stringify({
|
|
durationWeeks: 4,
|
|
priorityPlatforms: ['Instagram', 'LinkedIn', 'Telegram']
|
|
})
|
|
});
|
|
```
|
|
|
|
#### Пример успешного ответа (200 OK)
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Генерация стратегии запущена успешно. Результаты будут готовы в течение 3-5 минут.",
|
|
"data": {
|
|
"strategyId": "507f1f77bcf86cd799439020",
|
|
"analysisId": "507f1f77bcf86cd799439011",
|
|
"status": "queued",
|
|
"createdAt": "2025-01-20T15:40:00",
|
|
"completedAt": null,
|
|
"durationWeeks": 4,
|
|
"priorityPlatforms": ["Instagram", "LinkedIn", "Telegram"]
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 7. Получение результата стратегии
|
|
|
|
**GET** `/api/marketing/analysis/strategy/{strategyId}`
|
|
|
|
Возвращает статус и результаты стратегии. Пользователь может получить только свои стратегии.
|
|
|
|
#### Заголовки запроса
|
|
|
|
```
|
|
Authorization: Bearer <your_jwt_token>
|
|
```
|
|
|
|
#### Параметры пути
|
|
|
|
| Параметр | Тип | Описание |
|
|
| ------------ | ------ | ----------------------- |
|
|
| `strategyId` | string | Идентификатор стратегии |
|
|
|
|
#### Пример ответа (когда стратегия завершена - 200 OK)
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Операция выполнена успешно",
|
|
"data": {
|
|
"strategyId": "507f1f77bcf86cd799439020",
|
|
"analysisId": "507f1f77bcf86cd799439011",
|
|
"status": "completed",
|
|
"createdAt": "2025-01-20T15:40:00",
|
|
"completedAt": "2025-01-20T15:43:00",
|
|
"durationWeeks": 4,
|
|
"priorityPlatforms": ["Instagram", "LinkedIn", "Telegram"],
|
|
"strategy": {
|
|
"weeklyPlans": [
|
|
{
|
|
"weekNumber": 1,
|
|
"mainThemes": ["Презентация продукта", "Преимущества"],
|
|
"contentRecommendations": "Создавайте контент, который демонстрирует ценность продукта",
|
|
"priorityPlatforms": ["Instagram", "LinkedIn"]
|
|
}
|
|
],
|
|
"postCalendar": [
|
|
{
|
|
"publishDate": "2025-01-21T10:00:00",
|
|
"platform": "Instagram",
|
|
"contentType": "пост",
|
|
"theme": "Презентация продукта",
|
|
"postText": "Полный текст поста для публикации...",
|
|
"hashtags": ["#маркетинг", "#бизнес"],
|
|
"publishTime": "10:00"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 8. Получение стратегии по ID анализа
|
|
|
|
**GET** `/api/marketing/analysis/{analysisId}/strategy`
|
|
|
|
Возвращает стратегию, связанную с указанным анализом. Пользователь может получить только стратегии для своих анализов.
|
|
|
|
#### Заголовки запроса
|
|
|
|
```
|
|
Authorization: Bearer <your_jwt_token>
|
|
```
|
|
|
|
#### Параметры пути
|
|
|
|
| Параметр | Тип | Описание |
|
|
| ------------ | ------ | --------------------- |
|
|
| `analysisId` | string | Идентификатор анализа |
|
|
|
|
---
|
|
|
|
### 9. Получение списка всех стратегий пользователя
|
|
|
|
**GET** `/api/marketing/analysis/strategy/my`
|
|
|
|
Возвращает список всех стратегий текущего пользователя, отсортированных по дате создания (новые первыми).
|
|
|
|
#### Заголовки запроса
|
|
|
|
```
|
|
Authorization: Bearer <your_jwt_token>
|
|
```
|
|
|
|
#### Пример успешного ответа (200 OK)
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Операция выполнена успешно",
|
|
"data": [
|
|
{
|
|
"strategyId": "507f1f77bcf86cd799439020",
|
|
"analysisId": "507f1f77bcf86cd799439011",
|
|
"status": "completed",
|
|
"userId": "12345",
|
|
"durationWeeks": 4,
|
|
"priorityPlatforms": ["Instagram", "LinkedIn", "Telegram"],
|
|
"createdAt": "2025-01-20T15:40:00",
|
|
"completedAt": "2025-01-20T15:43:00",
|
|
"statusHistory": [
|
|
{
|
|
"status": "queued",
|
|
"timestamp": "2025-01-20T15:40:00",
|
|
"message": "Стратегия создана и добавлена в очередь"
|
|
},
|
|
{
|
|
"status": "processing",
|
|
"timestamp": "2025-01-20T15:40:05",
|
|
"message": "Начата генерация стратегии"
|
|
},
|
|
{
|
|
"status": "completed",
|
|
"timestamp": "2025-01-20T15:43:00",
|
|
"message": "Стратегия успешно сгенерирована"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 10. Получение детальной истории стратегии
|
|
|
|
**GET** `/api/marketing/analysis/strategy/{strategyId}/history`
|
|
|
|
Возвращает детальную информацию о стратегии, включая полную историю изменений статуса.
|
|
|
|
#### Заголовки запроса
|
|
|
|
```
|
|
Authorization: Bearer <your_jwt_token>
|
|
```
|
|
|
|
#### Параметры пути
|
|
|
|
| Параметр | Тип | Описание |
|
|
| ------------ | ------ | ----------------------- |
|
|
| `strategyId` | string | Идентификатор стратегии |
|
|
|
|
#### Пример успешного ответа (200 OK)
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Операция выполнена успешно",
|
|
"data": {
|
|
"strategyId": "507f1f77bcf86cd799439020",
|
|
"analysisId": "507f1f77bcf86cd799439011",
|
|
"status": "completed",
|
|
"userId": "12345",
|
|
"durationWeeks": 4,
|
|
"priorityPlatforms": ["Instagram", "LinkedIn", "Telegram"],
|
|
"createdAt": "2025-01-20T15:40:00",
|
|
"completedAt": "2025-01-20T15:43:00",
|
|
"statusHistory": [
|
|
{
|
|
"status": "queued",
|
|
"timestamp": "2025-01-20T15:40:00",
|
|
"message": "Стратегия создана и добавлена в очередь"
|
|
},
|
|
{
|
|
"status": "processing",
|
|
"timestamp": "2025-01-20T15:40:05",
|
|
"message": "Начата генерация стратегии"
|
|
},
|
|
{
|
|
"status": "completed",
|
|
"timestamp": "2025-01-20T15:43:00",
|
|
"message": "Стратегия успешно сгенерирована"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Обработка ошибок
|
|
|
|
### Коды ошибок
|
|
|
|
| Код | HTTP статус | Описание |
|
|
| ------------------------ | ----------- | ------------------------------- |
|
|
| `UNAUTHORIZED` | 401 | Требуется аутентификация |
|
|
| `FORBIDDEN` | 403 | Нет доступа к ресурсу |
|
|
| `VALIDATION_ERROR` | 400 | Ошибка валидации входных данных |
|
|
| `NOT_FOUND` | 404 | Ресурс не найден |
|
|
| `INVALID_ANALYSIS` | 404 | Анализ не найден |
|
|
| `ANALYSIS_NOT_COMPLETED` | 400 | Анализ еще не завершен |
|
|
| `INTERNAL_SERVER_ERROR` | 500 | Внутренняя ошибка сервера |
|
|
|
|
### Формат ошибки
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"message": "Описание ошибки",
|
|
"error": {
|
|
"code": "ERROR_CODE",
|
|
"message": "Детальное сообщение об ошибке",
|
|
"details": {
|
|
"field1": "Сообщение об ошибке для поля 1"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Примеры использования
|
|
|
|
### JavaScript/TypeScript (Fetch API)
|
|
|
|
#### Получение JWT токена
|
|
|
|
```javascript
|
|
// Предполагается, что токен получен при логине
|
|
const jwtToken = localStorage.getItem('jwtToken');
|
|
```
|
|
|
|
#### Запуск анализа с JWT
|
|
|
|
```javascript
|
|
async function startMarketingAnalysis(data, jwtToken) {
|
|
const response = await fetch('https://api.konturai.kz/api/marketing/analysis/start', {
|
|
method: 'POST',
|
|
headers: {
|
|
'Content-Type': 'application/json',
|
|
Authorization: `Bearer ${jwtToken}`
|
|
},
|
|
body: JSON.stringify(data)
|
|
});
|
|
|
|
if (!response.ok) {
|
|
if (response.status === 401) {
|
|
throw new Error('Требуется аутентификация');
|
|
}
|
|
const error = await response.json();
|
|
throw new Error(error.error?.message || 'Ошибка при запуске анализа');
|
|
}
|
|
|
|
const result = await response.json();
|
|
return result.data.analysisId;
|
|
}
|
|
```
|
|
|
|
#### Получение списка всех анализов пользователя
|
|
|
|
```javascript
|
|
async function getMyAnalyses(jwtToken) {
|
|
const response = await fetch('https://api.konturai.kz/api/marketing/analysis/my', {
|
|
headers: {
|
|
Authorization: `Bearer ${jwtToken}`
|
|
}
|
|
});
|
|
|
|
if (!response.ok) {
|
|
throw new Error('Ошибка при получении списка анализов');
|
|
}
|
|
|
|
const result = await response.json();
|
|
return result.data; // Массив анализов
|
|
}
|
|
```
|
|
|
|
#### Получение детальной истории анализа
|
|
|
|
```javascript
|
|
async function getAnalysisHistory(analysisId, jwtToken) {
|
|
const response = await fetch(`https://api.konturai.kz/api/marketing/analysis/${analysisId}/history`, {
|
|
headers: {
|
|
Authorization: `Bearer ${jwtToken}`
|
|
}
|
|
});
|
|
|
|
if (!response.ok) {
|
|
if (response.status === 403) {
|
|
throw new Error('Нет доступа к этому анализу');
|
|
}
|
|
throw new Error('Ошибка при получении истории');
|
|
}
|
|
|
|
const result = await response.json();
|
|
return result.data;
|
|
}
|
|
```
|
|
|
|
#### Полный пример: создание анализа и отслеживание статуса
|
|
|
|
```javascript
|
|
async function createAndTrackAnalysis(product, location, client, differentiator, jwtToken) {
|
|
try {
|
|
// 1. Запускаем анализ
|
|
const analysisId = await startMarketingAnalysis(
|
|
{
|
|
product,
|
|
location,
|
|
client,
|
|
differentiator
|
|
},
|
|
jwtToken
|
|
);
|
|
|
|
console.log(`Анализ запущен: ${analysisId}`);
|
|
|
|
// 2. Получаем историю для отслеживания статуса
|
|
const checkStatus = async () => {
|
|
const history = await getAnalysisHistory(analysisId, jwtToken);
|
|
|
|
// Показываем последний статус
|
|
const lastStatus = history.statusHistory[history.statusHistory.length - 1];
|
|
console.log(`Статус: ${lastStatus.status} - ${lastStatus.message}`);
|
|
|
|
return history.status;
|
|
};
|
|
|
|
// 3. Polling: проверяем статус каждые 10 секунд
|
|
const pollInterval = setInterval(async () => {
|
|
const status = await checkStatus();
|
|
|
|
if (status === 'completed') {
|
|
clearInterval(pollInterval);
|
|
console.log('Анализ завершен!');
|
|
// Получаем полный результат
|
|
const fullResult = await getAnalysisResult(analysisId, jwtToken);
|
|
return fullResult;
|
|
} else if (status === 'failed') {
|
|
clearInterval(pollInterval);
|
|
throw new Error('Анализ завершился с ошибкой');
|
|
}
|
|
}, 10000);
|
|
|
|
// Останавливаем polling через 15 минут
|
|
setTimeout(
|
|
() => {
|
|
clearInterval(pollInterval);
|
|
console.log('Превышено время ожидания');
|
|
},
|
|
15 * 60 * 1000
|
|
);
|
|
} catch (error) {
|
|
console.error('Ошибка:', error);
|
|
throw error;
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Получение списка стратегий пользователя
|
|
|
|
```javascript
|
|
async function getMyStrategies(jwtToken) {
|
|
const response = await fetch('https://api.konturai.kz/api/marketing/analysis/strategy/my', {
|
|
headers: {
|
|
Authorization: `Bearer ${jwtToken}`
|
|
}
|
|
});
|
|
|
|
if (!response.ok) {
|
|
throw new Error('Ошибка при получении списка стратегий');
|
|
}
|
|
|
|
const result = await response.json();
|
|
return result.data; // Массив стратегий
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Рекомендации по интеграции
|
|
|
|
### 1. Обработка JWT токена
|
|
|
|
- Сохраняйте токен в безопасном месте (например, `localStorage` или `sessionStorage`)
|
|
- Проверяйте срок действия токена перед запросами
|
|
- Реализуйте механизм обновления токена при истечении
|
|
|
|
### 2. Обработка ошибок аутентификации
|
|
|
|
При получении `401 Unauthorized`:
|
|
|
|
- Перенаправляйте пользователя на страницу входа
|
|
- Очищайте сохраненный токен
|
|
- Показывайте понятное сообщение пользователю
|
|
|
|
### 3. Обработка ошибок доступа
|
|
|
|
При получении `403 Forbidden`:
|
|
|
|
- Показывайте сообщение о том, что ресурс недоступен
|
|
- Не пытайтесь повторять запрос с теми же параметрами
|
|
|
|
### 4. Polling стратегия
|
|
|
|
Для отслеживания статуса анализа/стратегии:
|
|
|
|
- Используйте интервал 10-15 секунд
|
|
- Максимальное время ожидания: 15 минут
|
|
- Показывайте прогресс пользователю на основе `statusHistory`
|
|
|
|
### 5. Отображение истории статусов
|
|
|
|
Используйте `statusHistory` для:
|
|
|
|
- Показывать временную шкалу изменений статуса
|
|
- Отображать детальную информацию о каждом этапе
|
|
- Информировать пользователя о прогрессе
|
|
|
|
### 6. Кэширование
|
|
|
|
- Кэшируйте список анализов/стратегий пользователя
|
|
- Обновляйте кэш при создании новых записей
|
|
- Используйте `analysisId`/`strategyId` как ключи кэша
|
|
|
|
---
|
|
|
|
## Примечания
|
|
|
|
1. **Формат даты**: Все даты возвращаются в формате ISO 8601 без timezone (LocalDateTime)
|
|
2. **Идентификаторы**: Используются MongoDB ObjectId (24 символа hex)
|
|
3. **Асинхронность**: Анализ и стратегия выполняются асинхронно
|
|
4. **Безопасность**: Все эндпоинты требуют валидный JWT токен
|
|
5. **Изоляция данных**: Пользователи видят только свои данные
|
|
6. **История статусов**: Детальная история доступна для всех анализов и стратегий
|
|
|
|
---
|
|
|
|
## Изменения: Поддержка типов анализов
|
|
|
|
### Обзор изменений
|
|
|
|
В API добавлена поддержка различных типов маркетинговых анализов. Теперь при создании анализа можно указать тип анализа, который определяет фокус и содержание генерируемого отчета.
|
|
|
|
### Новое поле в запросе
|
|
|
|
**Поле**: `analysisType` (обязательное)
|
|
|
|
**Тип**: `string`
|
|
|
|
**Допустимые значения**:
|
|
|
|
- `"РЫНОК"` - Анализ рынка
|
|
- `"КОНКУРЕНТЫ"` - Анализ конкурентов
|
|
- `"ЦА"` - Анализ целевой аудитории
|
|
- `"КАНАЛЫ"` - Анализ маркетинговых каналов
|
|
- `"SWOT"` - SWOT-анализ
|
|
|
|
### Описание типов анализов
|
|
|
|
#### 1. РЫНОК
|
|
|
|
Генерирует анализ рынка, включающий:
|
|
|
|
- Размер рынка
|
|
- Динамику роста
|
|
- Основные сегменты
|
|
- Тренды и перспективы развития
|
|
|
|
#### 2. КОНКУРЕНТЫ
|
|
|
|
Генерирует анализ конкурентов, включающий:
|
|
|
|
- Основных конкурентов
|
|
- Их сильные и слабые стороны
|
|
- Позиционирование
|
|
- Ценовую политику
|
|
- Маркетинговые стратегии
|
|
|
|
#### 3. ЦА (Целевая аудитория)
|
|
|
|
Генерирует анализ целевой аудитории, включающий:
|
|
|
|
- Демографические характеристики
|
|
- Психографический профиль
|
|
- Потребности и боли
|
|
- Поведенческие паттерны
|
|
- Предпочтения
|
|
|
|
#### 4. КАНАЛЫ
|
|
|
|
Генерирует анализ маркетинговых каналов, включающий:
|
|
|
|
- Оценку эффективности различных каналов коммуникации
|
|
- Рекомендации по выбору каналов
|
|
- Особенности использования каждого канала
|
|
- Бюджетные рекомендации
|
|
|
|
#### 5. SWOT
|
|
|
|
Генерирует SWOT-анализ, включающий:
|
|
|
|
- Сильные стороны (Strengths)
|
|
- Слабые стороны (Weaknesses)
|
|
- Возможности (Opportunities)
|
|
- Угрозы (Threats)
|
|
|
|
### Изменения в ответе
|
|
|
|
В ответе анализа теперь присутствует поле `analysisType` в объекте `reportData`, которое содержит название типа анализа.
|
|
|
|
### Пример использования
|
|
|
|
```javascript
|
|
// Запрос на создание SWOT-анализа
|
|
const response = await fetch('https://api.konturai.kz/api/marketing/analysis/start', {
|
|
method: 'POST',
|
|
headers: {
|
|
'Content-Type': 'application/json',
|
|
Authorization: `Bearer ${jwtToken}`
|
|
},
|
|
body: JSON.stringify({
|
|
product: 'Разработка мобильных приложений',
|
|
location: 'Нур-Султан, Казахстан',
|
|
client: 'B2B клиенты',
|
|
differentiator: 'Специализируемся на быстрой разработке MVP за 4 недели',
|
|
analysisType: 'SWOT' // Указываем тип анализа
|
|
})
|
|
});
|
|
```
|
|
|
|
### Рекомендации для фронтенда
|
|
|
|
1. **UI для выбора типа анализа**: Добавьте выпадающий список или радиокнопки для выбора типа анализа перед отправкой запроса.
|
|
|
|
2. **Валидация на фронтенде**: Убедитесь, что отправляется только один из допустимых значений.
|
|
|
|
3. **Отображение типа анализа**: При показе результатов анализа отображайте тип анализа для контекста.
|
|
|
|
4. **Обратная совместимость**: Если поле `analysisType` не указано, API вернет ошибку валидации. Это обязательное поле.
|
|
|
|
### Миграция существующих интеграций
|
|
|
|
Если у вас есть существующие интеграции, которые не используют поле `analysisType`, необходимо:
|
|
|
|
1. Добавить поле `analysisType` в запрос
|
|
2. Выбрать подходящий тип анализа по умолчанию или позволить пользователю выбрать
|
|
3. Обновить UI для отображения выбора типа анализа
|
|
|
|
---
|
|
|
|
## Поддержка
|
|
|
|
При возникновении проблем с API обращайтесь в техническую поддержку с указанием:
|
|
|
|
- `analysisId` или `strategyId` (если есть)
|
|
- Время запроса
|
|
- Описание проблемы
|
|
- Код ошибки (если есть)
|
|
- JWT токен (только для отладки, не в продакшене!)
|