marketing-parser/marketing-analysis-api.md

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 символов"

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

{
    "product": "Разработка мобильных приложений",
    "location": "Нур-Султан, Казахстан",
    "client": "B2B клиенты",
    "differentiator": "Специализируемся на быстрой разработке MVP за 4 недели с использованием современных технологий"
}

Ответ

Успешный ответ (200 OK)

{
    "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:

{
    "success": true,
    "data": {
        "analysisId": "550e8400-e29b-41d4-a716-446655440000",
        "status": "queued",
        "queuePosition": 3,
        "estimatedWaitTime": 300,
        "message": "Запрос добавлен в очередь. Примерное время ожидания: 5 минут."
    }
}

Обработка ошибок

Ошибки валидации (400 Bad Request)

{
    "success": false,
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Ошибка валидации входных данных",
        "details": {
            "product": "Поле 'product' обязательно для заполнения",
            "client": "Недопустимое значение поля 'client'"
        }
    }
}

Ошибка аутентификации (401 Unauthorized)

{
    "success": false,
    "error": {
        "code": "UNAUTHORIZED",
        "message": "Требуется аутентификация"
    }
}

Ошибка сервера (500 Internal Server Error)

{
    "success": false,
    "error": {
        "code": "INTERNAL_SERVER_ERROR",
        "message": "Произошла внутренняя ошибка сервера. Попробуйте позже."
    }
}

Ошибка таймаута (504 Gateway Timeout)

{
    "success": false,
    "error": {
        "code": "TIMEOUT",
        "message": "Превышено время ожидания ответа от сервиса анализа"
    }
}

Получение результатов анализа

После успешного запуска анализа, результаты можно получить по идентификатору:

GET /api/marketing/analysis/{analysisId}

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

GET /api/marketing/analysis/550e8400-e29b-41d4-a716-446655440000

Пример ответа (когда анализ завершен)

{
    "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/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. Асинхронная обработка

Рекомендуется использовать асинхронную обработку для длительных операций:

@Async
public CompletableFuture<AnalysisResult> processAnalysis(MarketingAnalysisRequest request) {
    // Длительная обработка
    // Генерация отчета
    // Сохранение результатов
    return CompletableFuture.completedFuture(result);
}

3. Хранение данных

Рекомендуемая структура таблицы в БД:

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 сервис для генерации анализа:

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. Обработка ошибок

@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", "Внутренняя ошибка сервера"));
}

Тестирование

Примеры тестовых запросов

Успешный запрос

curl -X POST https://api.konturai.kz/api/marketing/analysis/start \
  -H "Content-Type: application/json" \
  -d '{
    "product": "Разработка мобильных приложений",
    "location": "Алматы, Казахстан",
    "client": "B2B клиенты",
    "differentiator": "Специализируемся на быстрой разработке MVP за 4 недели"
  }'

Запрос с ошибкой валидации

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. Мониторинг: Отслеживайте время выполнения анализа и процент успешных завершений