# API Документация: Обновленные поля для генерации бизнес-анализа (Frontend/AI Agent) ## Обзор изменений API для генерации маркетингового анализа был обновлен с новыми полями, которые более точно отражают требования бизнес-анализа. Все старые поля были заменены новыми для улучшения качества анализа. --- ## Изменения в структуре запроса ### Удаленные поля (больше не используются) Следующие поля были **удалены** из API и больше не принимаются: - ❌ `location` - заменено на `region` - ❌ `client` - заменено на `targetAudience` - ❌ `differentiator` - заменено на комбинацию `businessNiche`, `strongSide`, `weakSide` ### Новые обязательные поля | Поле | Тип | Обязательный | Описание | Пример значения | | ---------------- | ------ | ------------ | -------------------------------------- | ------------------------------------------------------ | | `businessNiche` | string | ✅ | Ниша бизнеса | "E-commerce платформы" | | `product` | string | ✅ | Продукт или услуга | "Разработка мобильных приложений" | | `targetAudience` | string | ✅ | Целевая аудитория (детальное описание) | "Малый и средний бизнес, владельцы интернет-магазинов" | | `region` | string | ✅ | Регион (город Казахстана) | "Алматы" | | `goal` | string | ✅ | Цель на 6-12 месяцев | "Увеличить количество клиентов на 50%" | | `detailLevel` | string | ✅ | Уровень детализации анализа | "СТАНДАРТНО" | | `analysisType` | string | ✅ | Тип анализа | "РЫНОК" | ### Новые опциональные поля | Поле | Тип | Обязательный | Описание | Пример значения | | ------------ | ------ | ------------ | ----------------------- | ------------------------------------------------- | | `strongSide` | string | ❌ | Сильная сторона бизнеса | "Опытная команда разработчиков, быстрая доставка" | | `weakSide` | string | ❌ | Слабая сторона бизнеса | "Ограниченный маркетинговый бюджет" | --- ## Детальное описание полей ### 1. `businessNiche` (обязательное) **Описание**: Ниша бизнеса, в которой работает компания. **Валидация**: - Минимальная длина: 3 символа - Максимальная длина: 200 символов - Разрешены: буквы, цифры, пробелы, дефисы, запятые - Паттерн: `^[\p{L}\p{N}\s\-,]+$` **Примеры**: ```json "businessNiche": "E-commerce платформы" "businessNiche": "Образовательные технологии" "businessNiche": "Финансовые услуги для малого бизнеса" ``` --- ### 2. `product` (обязательное) **Описание**: Конкретный продукт или услуга, которую предоставляет компания. **Валидация**: - Минимальная длина: 3 символа - Максимальная длина: 200 символов - Разрешены: буквы, цифры, пробелы, дефисы, запятые - Паттерн: `^[\p{L}\p{N}\s\-,]+$` **Примеры**: ```json "product": "Разработка мобильных приложений" "product": "Консультации по маркетингу" "product": "Веб-разработка и дизайн" ``` --- ### 3. `targetAudience` (обязательное) **Описание**: Структурированное описание целевой аудитории в формате JSON. Позволяет выбрать гендер, возрастные диапазоны и типы аудитории. Можно выбрать несколько вариантов в каждой категории. **Валидация**: - Должно быть объектом JSON с полями `genders`, `ageRanges`, `types` - Хотя бы одно поле должно быть заполнено и содержать непустой массив - Каждое поле должно содержать только допустимые значения **Структура**: ```json { "genders": ["Женщины", "Мужчины"], "ageRanges": ["20-40", "25-45"], "types": ["Семьи", "Молодёжь"] } ``` **Допустимые значения**: - `genders`: `["Женщины", "Мужчины"]` - можно выбрать один или оба - `ageRanges`: `["20-40", "25-45", "18-25", "40-60", "60+"]` - можно выбрать один или несколько диапазонов - `types`: `["Семьи", "Молодёжь", "Все подряд"]` - можно выбрать один или несколько типов **Примеры**: ```json "targetAudience": { "genders": ["Женщины"], "ageRanges": ["20-40"], "types": ["Молодёжь"] } ``` ```json "targetAudience": { "genders": ["Женщины", "Мужчины"], "ageRanges": ["25-45", "40-60"], "types": ["Семьи"] } ``` ```json "targetAudience": { "genders": ["Мужчины"], "ageRanges": ["18-25"], "types": ["Молодёжь", "Все подряд"] } ``` **Примечание**: Можно выбрать несколько вариантов в каждой категории. Все выбранные значения будут отражены в анализе. --- ### 4. `region` (обязательное) **Описание**: Регионы (города Казахстана), в которых работает бизнес. Можно выбрать один или несколько регионов. Это поле заменяет старое поле `location`. **Валидация**: - Должно быть массивом строк - Минимум один регион должен быть выбран - Каждый регион должен быть одним из допустимых городов Казахстана - Проверка выполняется через валидатор `@ValidRegion` **Допустимые значения** (точное совпадение): - `"Алматы"` - `"Астана"` - `"Шымкент"` - `"Караганда"` - `"Актобе"` - `"Тараз"` - `"Павлодар"` - `"Усть-Каменогорск"` - `"Семей"` - `"Костанай"` - `"Кызылорда"` - `"Уральск"` - `"Петропавловск"` - `"Атырау"` - `"Актау"` - `"Туркестан"` - `"Кокшетау"` - `"Талдыкорган"` - `"Экибастуз"` - `"Рудный"` **Примеры**: ```json "region": ["Алматы"] ``` ```json "region": ["Алматы", "Астана", "Шымкент"] ``` ```json "region": ["Астана", "Караганда"] ``` **Важно**: - Значения должны точно совпадать с допустимыми городами (регистр важен) - Можно выбрать все регионы, перечислив их в массиве - Все выбранные регионы будут отражены в анализе --- ### 5. `goal` (обязательное) **Описание**: Цель бизнеса на период 6-12 месяцев. Это новое поле, которое помогает AI лучше понять приоритеты бизнеса. **Валидация**: - Минимальная длина: 10 символов - Максимальная длина: 500 символов - Разрешены любые символы **Примеры**: ```json "goal": "Увеличить количество клиентов на 50% за следующие 6 месяцев" "goal": "Выйти на рынок соседних регионов и открыть 3 новых филиала" "goal": "Повысить узнаваемость бренда и увеличить продажи через онлайн-каналы на 30%" ``` --- ### 6. `detailLevel` (обязательное) **Описание**: Уровень детализации анализа. Влияет на объем и глубину генерируемого анализа. **Валидация**: - Должно быть одним из допустимых значений - Проверка выполняется через валидатор `@ValidDetailLevel` **Допустимые значения** (точное совпадение, регистр важен): - `"КРАТКО"` - Краткий анализ (1-2 абзаца) - `"СТАНДАРТНО"` - Стандартный анализ (3-5 абзацев) - **рекомендуется по умолчанию** - `"ПОДРОБНО"` - Подробный анализ (5-8 абзацев) **Влияние на анализ**: | Уровень | Длина ответов | Количество рекомендаций | Детализация стратегии | | ------------ | ------------- | ----------------------- | ------------------------ | | `КРАТКО` | 1-2 абзаца | 3-4 рекомендации | Краткая | | `СТАНДАРТНО` | 3-5 абзацев | 4-6 рекомендаций | Стандартная | | `ПОДРОБНО` | 5-8 абзацев | 6-8 рекомендаций | Детальная с обоснованием | **Примеры**: ```json "detailLevel": "КРАТКО" "detailLevel": "СТАНДАРТНО" "detailLevel": "ПОДРОБНО" ``` --- ### 7. `strongSide` (опциональное) **Описание**: Сильная сторона бизнеса. Помогает AI лучше понять конкурентные преимущества. **Валидация**: - Максимальная длина: 500 символов - Разрешены любые символы - Может быть пустым или отсутствовать **Примеры**: ```json "strongSide": "Опытная команда разработчиков с 10+ летним опытом, быстрая доставка проектов" "strongSide": "Уникальная технология, низкие цены, отличная поддержка клиентов" ``` **Примечание**: Если поле не указано, AI будет анализировать сильные стороны на основе других данных. --- ### 8. `weakSide` (опциональное) **Описание**: Слабая сторона бизнеса. Помогает AI лучше понять области для улучшения. **Валидация**: - Максимальная длина: 500 символов - Разрешены любые символы - Может быть пустым или отсутствовать **Примеры**: ```json "weakSide": "Ограниченный маркетинговый бюджет, недостаточная узнаваемость бренда" "weakSide": "Небольшая команда, ограниченные ресурсы для масштабирования" ``` **Примечание**: Если поле не указано, AI будет анализировать слабые стороны на основе других данных. --- ### 9. `analysisType` (обязательное) **Описание**: Тип(ы) анализа, которые необходимо провести. Можно выбрать один или несколько типов анализа. При выборе нескольких типов будет создан отдельный анализ для каждого типа. **Валидация**: - Должно быть массивом строк - Минимум один тип анализа должен быть выбран - Каждый тип должен быть одним из допустимых значений - Проверка выполняется через валидатор `@ValidAnalysisType` **Допустимые значения**: - `"РЫНОК"` - Анализ рынка (размер рынка, динамика роста, сегменты, тренды) - `"КОНКУРЕНТЫ"` - Анализ конкурентов (основные конкуренты, их сильные/слабые стороны, позиционирование) - `"ЦА"` - Анализ целевой аудитории (демография, психография, потребности, поведение) - `"КАНАЛЫ"` - Анализ маркетинговых каналов (эффективность каналов, рекомендации по выбору) - `"SWOT"` - SWOT-анализ (сильные стороны, слабые стороны, возможности, угрозы) **Примеры**: ```json "analysisType": ["РЫНОК"] ``` ```json "analysisType": ["РЫНОК", "КОНКУРЕНТЫ", "ЦА"] ``` ```json "analysisType": ["РЫНОК", "КОНКУРЕНТЫ", "ЦА", "КАНАЛЫ", "SWOT"] ``` **Важно**: - При выборе нескольких типов анализа API создаст отдельные записи анализа для каждого типа - В ответе будет возвращен массив с информацией о каждом созданном анализе - Каждый анализ будет обрабатываться независимо и иметь свой статус --- ## Полный пример запроса ### POST `/api/marketing/analysis/start` **Пример 1: Один тип анализа, один регион** ```json { "businessNiche": "E-commerce платформы", "product": "Разработка мобильных приложений для интернет-магазинов", "targetAudience": { "genders": ["Женщины"], "ageRanges": ["25-45"], "types": ["Молодёжь"] }, "region": ["Алматы"], "goal": "Увеличить количество клиентов на 50% за следующие 6 месяцев и выйти на рынок соседних регионов", "detailLevel": "СТАНДАРТНО", "strongSide": "Опытная команда разработчиков с 10+ летним опытом, быстрая доставка проектов, использование современных технологий", "weakSide": "Ограниченный маркетинговый бюджет, недостаточная узнаваемость бренда в новых регионах", "analysisType": ["РЫНОК"] } ``` **Пример 2: Несколько типов анализа, несколько регионов** ```json { "businessNiche": "E-commerce платформы", "product": "Разработка мобильных приложений для интернет-магазинов", "targetAudience": { "genders": ["Женщины", "Мужчины"], "ageRanges": ["25-45", "40-60"], "types": ["Семьи", "Молодёжь"] }, "region": ["Алматы", "Астана", "Шымкент"], "goal": "Увеличить количество клиентов на 50% за следующие 6 месяцев и выйти на рынок соседних регионов", "detailLevel": "СТАНДАРТНО", "strongSide": "Опытная команда разработчиков с 10+ летним опытом, быстрая доставка проектов", "weakSide": "Ограниченный маркетинговый бюджет", "analysisType": ["РЫНОК", "КОНКУРЕНТЫ", "ЦА"] } ``` **Пример 3: Все типы анализа** ```json { "businessNiche": "E-commerce платформы", "product": "Разработка мобильных приложений для интернет-магазинов", "targetAudience": { "genders": ["Женщины", "Мужчины"], "ageRanges": ["20-40", "25-45"], "types": ["Семьи", "Молодёжь", "Все подряд"] }, "region": ["Алматы", "Астана"], "goal": "Увеличить количество клиентов на 50% за следующие 6 месяцев", "detailLevel": "ПОДРОБНО", "analysisType": ["РЫНОК", "КОНКУРЕНТЫ", "ЦА", "КАНАЛЫ", "SWOT"] } ``` --- ## Примеры использования на фронтенде ### JavaScript/TypeScript ```typescript interface TargetAudience { genders?: ('Женщины' | 'Мужчины')[]; ageRanges?: ('20-40' | '25-45' | '18-25' | '40-60' | '60+')[]; types?: ('Семьи' | 'Молодёжь' | 'Все подряд')[]; } interface MarketingAnalysisRequest { businessNiche: string; product: string; targetAudience: TargetAudience; region: string[]; goal: string; detailLevel: 'КРАТКО' | 'СТАНДАРТНО' | 'ПОДРОБНО'; strongSide?: string; weakSide?: string; analysisType: ('РЫНОК' | 'КОНКУРЕНТЫ' | 'ЦА' | 'КАНАЛЫ' | 'SWOT')[]; } // Список допустимых регионов const VALID_REGIONS = [ 'Алматы', 'Астана', 'Шымкент', 'Караганда', 'Актобе', 'Тараз', 'Павлодар', 'Усть-Каменогорск', 'Семей', 'Костанай', 'Кызылорда', 'Уральск', 'Петропавловск', 'Атырау', 'Актау', 'Туркестан', 'Кокшетау', 'Талдыкорган', 'Экибастуз', 'Рудный', ]; // Список уровней детализации const DETAIL_LEVELS = ['КРАТКО', 'СТАНДАРТНО', 'ПОДРОБНО'] as const; // Функция для отправки запроса async function startMarketingAnalysis( data: MarketingAnalysisRequest ): Promise { const response = await fetch( 'https://api.konturai.kz/api/marketing/analysis/start', { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: 'Bearer YOUR_JWT_TOKEN', // Если требуется }, body: JSON.stringify(data), } ); const result = await response.json(); if (!result.success) { throw new Error(result.error?.message || 'Failed to start analysis'); } // Если выбрано несколько типов анализа, result.data будет массивом return result.data; } interface MarketingAnalysisResponse { analysisId: string; status: string; estimatedCompletion: string; message: string; } // Пример использования const result = await startMarketingAnalysis({ businessNiche: 'E-commerce платформы', product: 'Разработка мобильных приложений', targetAudience: { genders: ['Женщины', 'Мужчины'], ageRanges: ['25-45'], types: ['Молодёжь'] }, region: ['Алматы', 'Астана'], goal: 'Увеличить количество клиентов на 50% за следующие 6 месяцев', detailLevel: 'СТАНДАРТНО', strongSide: 'Опытная команда, быстрая доставка', weakSide: 'Ограниченный маркетинговый бюджет', analysisType: ['РЫНОК', 'КОНКУРЕНТЫ'], }); // Если выбрано несколько типов анализа, result будет массивом if (Array.isArray(result)) { console.log(`Создано ${result.length} анализов`); result.forEach((analysis, index) => { console.log(`Анализ ${index + 1}: ${analysis.analysisId}`); }); } else { console.log('Анализ создан:', result.analysisId); } ``` ### React компонент с формой ```tsx import React, { useState } from 'react'; const MarketingAnalysisForm: React.FC = () => { const [formData, setFormData] = useState({ businessNiche: '', product: '', targetAudience: { genders: [], ageRanges: [], types: [] }, region: [], goal: '', detailLevel: 'СТАНДАРТНО', strongSide: '', weakSide: '', analysisType: [], }); const handleSubmit = async (e: React.FormEvent) => { e.preventDefault(); try { const analysisId = await startMarketingAnalysis(formData); console.log('Analysis started:', analysisId); // Перенаправление на страницу с результатами } catch (error) { console.error('Error:', error); } }; return (
setFormData({ ...formData, businessNiche: e.target.value }) } required minLength={3} maxLength={200} />
setFormData({ ...formData, product: e.target.value }) } required minLength={3} maxLength={200} />
{['Женщины', 'Мужчины'].map((gender) => ( ))}
{['20-40', '25-45', '18-25', '40-60', '60+'].map((age) => ( ))}
{['Семьи', 'Молодёжь', 'Все подряд'].map((type) => ( ))}
{VALID_REGIONS.map((region) => ( ))}