359 lines
14 KiB
Markdown
359 lines
14 KiB
Markdown
# API Документация: Маркетинговый анализ
|
|
|
|
## Обзор
|
|
|
|
API для запуска маркетингового анализа на основе данных о бизнесе пользователя. Эндпоинт принимает информацию о продукте, локации, типе клиентов и уникальных особенностях бизнеса, затем генерирует маркетинговый отчет.
|
|
|
|
## Эндпоинт
|
|
|
|
**POST** `/api/marketing/analysis/start`
|
|
|
|
### Базовый URL
|
|
|
|
```
|
|
https://api.konturai.kz/api/marketing/analysis/start
|
|
```
|
|
|
|
## Запрос
|
|
|
|
### Заголовки
|
|
|
|
```
|
|
Content-Type: application/json
|
|
Authorization: Bearer {access_token} // Опционально, если требуется аутентификация
|
|
```
|
|
|
|
### Тело запроса (JSON)
|
|
|
|
| Поле | Тип | Обязательный | Описание | Пример значения |
|
|
| ---------------- | ------ | ------------ | ------------------------------ | -------------------------------- |
|
|
| `product` | string | ✅ | Название продукта или услуги | "Веб-разработка" |
|
|
| `location` | string | ✅ | Географическая локация работы | "Алматы, Казахстан" |
|
|
| `client` | string | ✅ | Тип целевой аудитории | "B2B клиенты" |
|
|
| `differentiator` | string | ✅ | Уникальные особенности бизнеса | "Быстрая разработка за 2 недели" |
|
|
|
|
### Валидация полей
|
|
|
|
#### `product` (string, обязательное)
|
|
|
|
- **Минимальная длина**: 3 символа
|
|
- **Максимальная длина**: 200 символов
|
|
- **Паттерн**: Разрешены буквы, цифры, пробелы, дефисы, запятые
|
|
- **Ошибка валидации**: `"product": "Поле 'product' должно содержать от 3 до 200 символов"`
|
|
|
|
#### `location` (string, обязательное)
|
|
|
|
- **Минимальная длина**: 2 символа
|
|
- **Максимальная длина**: 150 символов
|
|
- **Паттерн**: Разрешены буквы, цифры, пробелы, запятые, дефисы
|
|
- **Ошибка валидации**: `"location": "Поле 'location' должно содержать от 2 до 150 символов"`
|
|
|
|
#### `client` (string, обязательное)
|
|
|
|
- **Допустимые значения**:
|
|
- `"B2B клиенты"`
|
|
- `"B2C клиенты"`
|
|
- `"Частные лица"`
|
|
- `"Корпорации"`
|
|
- `"Малый бизнес"`
|
|
- **Ошибка валидации**: `"client": "Поле 'client' должно быть одним из: B2B клиенты, B2C клиенты, Частные лица, Корпорации, Малый бизнес"`
|
|
|
|
#### `differentiator` (string, обязательное)
|
|
|
|
- **Минимальная длина**: 10 символов
|
|
- **Максимальная длина**: 500 символов
|
|
- **Паттерн**: Разрешены любые символы
|
|
- **Ошибка валидации**: `"differentiator": "Поле 'differentiator' должно содержать от 10 до 500 символов"`
|
|
|
|
### Пример запроса
|
|
|
|
```json
|
|
{
|
|
"product": "Разработка мобильных приложений",
|
|
"location": "Нур-Султан, Казахстан",
|
|
"client": "B2B клиенты",
|
|
"differentiator": "Специализируемся на быстрой разработке MVP за 4 недели с использованием современных технологий"
|
|
}
|
|
```
|
|
|
|
## Ответ
|
|
|
|
### Успешный ответ (200 OK)
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"analysisId": "550e8400-e29b-41d4-a716-446655440000",
|
|
"status": "processing",
|
|
"estimatedCompletionTime": "2025-01-20T15:30:00Z",
|
|
"message": "Анализ запущен успешно. Результаты будут готовы в течение 5-10 минут."
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Поля ответа
|
|
|
|
| Поле | Тип | Описание |
|
|
| ------------------------------ | ------- | --------------------------------------------------------- |
|
|
| `success` | boolean | Флаг успешности операции |
|
|
| `data.analysisId` | string | Уникальный идентификатор анализа (UUID) |
|
|
| `data.status` | string | Статус анализа: `"processing"`, `"completed"`, `"failed"` |
|
|
| `data.estimatedCompletionTime` | string | ISO 8601 дата/время ожидаемого завершения анализа |
|
|
| `data.message` | string | Информационное сообщение для пользователя |
|
|
|
|
### Асинхронная обработка (202 Accepted)
|
|
|
|
Если анализ требует длительной обработки, сервер может вернуть статус 202:
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"analysisId": "550e8400-e29b-41d4-a716-446655440000",
|
|
"status": "queued",
|
|
"queuePosition": 3,
|
|
"estimatedWaitTime": 300,
|
|
"message": "Запрос добавлен в очередь. Примерное время ожидания: 5 минут."
|
|
}
|
|
}
|
|
```
|
|
|
|
## Обработка ошибок
|
|
|
|
### Ошибки валидации (400 Bad Request)
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": {
|
|
"code": "VALIDATION_ERROR",
|
|
"message": "Ошибка валидации входных данных",
|
|
"details": {
|
|
"product": "Поле 'product' обязательно для заполнения",
|
|
"client": "Недопустимое значение поля 'client'"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Ошибка аутентификации (401 Unauthorized)
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": {
|
|
"code": "UNAUTHORIZED",
|
|
"message": "Требуется аутентификация"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Ошибка сервера (500 Internal Server Error)
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": {
|
|
"code": "INTERNAL_SERVER_ERROR",
|
|
"message": "Произошла внутренняя ошибка сервера. Попробуйте позже."
|
|
}
|
|
}
|
|
```
|
|
|
|
### Ошибка таймаута (504 Gateway Timeout)
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": {
|
|
"code": "TIMEOUT",
|
|
"message": "Превышено время ожидания ответа от сервиса анализа"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Получение результатов анализа
|
|
|
|
После успешного запуска анализа, результаты можно получить по идентификатору:
|
|
|
|
**GET** `/api/marketing/analysis/{analysisId}`
|
|
|
|
### Пример запроса
|
|
|
|
```
|
|
GET /api/marketing/analysis/550e8400-e29b-41d4-a716-446655440000
|
|
```
|
|
|
|
### Пример ответа (когда анализ завершен)
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"analysisId": "550e8400-e29b-41d4-a716-446655440000",
|
|
"status": "completed",
|
|
"createdAt": "2025-01-20T15:00:00Z",
|
|
"completedAt": "2025-01-20T15:08:00Z",
|
|
"report": {
|
|
"summary": "Краткое резюме анализа...",
|
|
"targetAudience": {
|
|
"description": "Описание целевой аудитории...",
|
|
"channels": ["Instagram", "LinkedIn", "Telegram"]
|
|
},
|
|
"recommendations": ["Рекомендация 1", "Рекомендация 2"],
|
|
"strategy": {
|
|
"duration": "2 недели",
|
|
"channels": ["Instagram", "Telegram", "21MC"],
|
|
"contentTypes": ["посты", "сторис", "баннеры"]
|
|
},
|
|
"pdfUrl": "/api/marketing/analysis/550e8400-e29b-41d4-a716-446655440000/download"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Статусы анализа
|
|
|
|
- `queued` - Запрос в очереди на обработку
|
|
- `processing` - Анализ выполняется
|
|
- `completed` - Анализ завершен успешно
|
|
- `failed` - Анализ завершился с ошибкой
|
|
|
|
## Рекомендации по реализации
|
|
|
|
### 1. Валидация на бэкенде
|
|
|
|
```java
|
|
// Пример валидации (Java/Spring Boot)
|
|
@PostMapping("/api/marketing/analysis/start")
|
|
public ResponseEntity<?> startAnalysis(@Valid @RequestBody MarketingAnalysisRequest request) {
|
|
// Валидация выполняется автоматически через @Valid
|
|
// Дополнительная бизнес-логика валидации
|
|
if (!isValidClientType(request.getClient())) {
|
|
return ResponseEntity.badRequest()
|
|
.body(new ErrorResponse("VALIDATION_ERROR", "Недопустимый тип клиента"));
|
|
}
|
|
// Обработка запроса
|
|
}
|
|
```
|
|
|
|
### 2. Асинхронная обработка
|
|
|
|
Рекомендуется использовать асинхронную обработку для длительных операций:
|
|
|
|
```java
|
|
@Async
|
|
public CompletableFuture<AnalysisResult> processAnalysis(MarketingAnalysisRequest request) {
|
|
// Длительная обработка
|
|
// Генерация отчета
|
|
// Сохранение результатов
|
|
return CompletableFuture.completedFuture(result);
|
|
}
|
|
```
|
|
|
|
### 3. Хранение данных
|
|
|
|
Рекомендуемая структура таблицы в БД:
|
|
|
|
```sql
|
|
CREATE TABLE marketing_analysis (
|
|
id UUID PRIMARY KEY,
|
|
product VARCHAR(200) NOT NULL,
|
|
location VARCHAR(150) NOT NULL,
|
|
client_type VARCHAR(50) NOT NULL,
|
|
differentiator TEXT NOT NULL,
|
|
status VARCHAR(20) NOT NULL,
|
|
created_at TIMESTAMP NOT NULL,
|
|
completed_at TIMESTAMP,
|
|
user_id UUID, -- Если требуется аутентификация
|
|
report_data JSONB, -- JSON с результатами анализа
|
|
CONSTRAINT valid_client_type CHECK (client_type IN (
|
|
'B2B клиенты', 'B2C клиенты', 'Частные лица', 'Корпорации', 'Малый бизнес'
|
|
)),
|
|
CONSTRAINT valid_status CHECK (status IN (
|
|
'queued', 'processing', 'completed', 'failed'
|
|
))
|
|
);
|
|
```
|
|
|
|
### 4. Интеграция с AI сервисом
|
|
|
|
Если используется внешний AI сервис для генерации анализа:
|
|
|
|
```java
|
|
public AnalysisResult generateAnalysis(MarketingAnalysisRequest request) {
|
|
// Подготовка промпта для AI
|
|
String prompt = String.format(
|
|
"Проанализируй бизнес:\n" +
|
|
"Продукт: %s\n" +
|
|
"Локация: %s\n" +
|
|
"Клиенты: %s\n" +
|
|
"Уникальность: %s\n" +
|
|
"Создай маркетинговую стратегию...",
|
|
request.getProduct(),
|
|
request.getLocation(),
|
|
request.getClient(),
|
|
request.getDifferentiator()
|
|
);
|
|
|
|
// Вызов AI API
|
|
return aiService.generateReport(prompt);
|
|
}
|
|
```
|
|
|
|
### 5. Обработка ошибок
|
|
|
|
```java
|
|
@ExceptionHandler(ValidationException.class)
|
|
public ResponseEntity<ErrorResponse> handleValidationException(ValidationException e) {
|
|
return ResponseEntity.badRequest()
|
|
.body(new ErrorResponse("VALIDATION_ERROR", e.getMessage(), e.getDetails()));
|
|
}
|
|
|
|
@ExceptionHandler(Exception.class)
|
|
public ResponseEntity<ErrorResponse> handleGenericException(Exception e) {
|
|
log.error("Unexpected error", e);
|
|
return ResponseEntity.status(500)
|
|
.body(new ErrorResponse("INTERNAL_SERVER_ERROR", "Внутренняя ошибка сервера"));
|
|
}
|
|
```
|
|
|
|
## Тестирование
|
|
|
|
### Примеры тестовых запросов
|
|
|
|
#### Успешный запрос
|
|
|
|
```bash
|
|
curl -X POST https://api.konturai.kz/api/marketing/analysis/start \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"product": "Разработка мобильных приложений",
|
|
"location": "Алматы, Казахстан",
|
|
"client": "B2B клиенты",
|
|
"differentiator": "Специализируемся на быстрой разработке MVP за 4 недели"
|
|
}'
|
|
```
|
|
|
|
#### Запрос с ошибкой валидации
|
|
|
|
```bash
|
|
curl -X POST https://api.konturai.kz/api/marketing/analysis/start \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"product": "AB",
|
|
"location": "Алматы",
|
|
"client": "Неверный тип",
|
|
"differentiator": "Коротко"
|
|
}'
|
|
```
|
|
|
|
## Примечания
|
|
|
|
1. **Аутентификация**: Если требуется аутентификация, используйте JWT токен в заголовке `Authorization`
|
|
2. **Rate Limiting**: Рекомендуется ограничить количество запросов на пользователя (например, 10 запросов в час)
|
|
3. **Кэширование**: Можно кэшировать результаты для одинаковых запросов
|
|
4. **Логирование**: Все запросы должны логироваться для отладки и аналитики
|
|
5. **Мониторинг**: Отслеживайте время выполнения анализа и процент успешных завершений
|