digiops/marketing

Fork 0

Files

T

root 24cc534fed .

2025-12-01 11:01:56 +05:00

40 KiB

Raw Permalink Blame History

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 вернет:

{
    "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-анализ (сильные стороны, слабые стороны, возможности, угрозы)

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

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)

{
    "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	Идентификатор анализа

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

const response = await fetch(`https://api.konturai.kz/api/marketing/analysis/${analysisId}`, {
    headers: {
        Authorization: `Bearer ${jwtToken}`
    }
});

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

{
    "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`	Анализ завершился с ошибкой

Ошибки доступа

Если пользователь пытается получить доступ к анализу другого пользователя:

{
    "success": false,
    "message": "Доступ запрещен",
    "error": {
        "code": "FORBIDDEN",
        "message": "У вас нет доступа к этому анализу"
    }
}

HTTP статус: 403 Forbidden

3. Получение списка всех анализов пользователя

GET /api/marketing/analysis/my

Возвращает список всех анализов текущего пользователя, отсортированных по дате создания (новые первыми).

Заголовки запроса

Authorization: Bearer <your_jwt_token>

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

const response = await fetch('https://api.konturai.kz/api/marketing/analysis/my', {
    headers: {
        Authorization: `Bearer ${jwtToken}`
    }
});

Пример успешного ответа (200 OK)

{
    "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	Идентификатор анализа

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

const response = await fetch(`https://api.konturai.kz/api/marketing/analysis/${analysisId}/history`, {
    headers: {
        Authorization: `Bearer ${jwtToken}`
    }
});

Пример успешного ответа (200 OK)

{
    "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	Идентификатор анализа

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

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, опционально)

{
    "durationWeeks": 4,
    "priorityPlatforms": ["Instagram", "LinkedIn", "Telegram"]
}

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

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)

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

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

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

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

Формат ошибки

{
    "success": false,
    "message": "Описание ошибки",
    "error": {
        "code": "ERROR_CODE",
        "message": "Детальное сообщение об ошибке",
        "details": {
            "field1": "Сообщение об ошибке для поля 1"
        }
    }
}

Примеры использования

JavaScript/TypeScript (Fetch API)

Получение JWT токена

// Предполагается, что токен получен при логине
const jwtToken = localStorage.getItem('jwtToken');

Запуск анализа с JWT

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;
}

Получение списка всех анализов пользователя

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; // Массив анализов
}

Получение детальной истории анализа

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;
}

Полный пример: создание анализа и отслеживание статуса

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;
    }
}

Получение списка стратегий пользователя

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; // Массив стратегий
}

Примечания

Формат даты: Все даты возвращаются в формате ISO 8601 без timezone (LocalDateTime)
Идентификаторы: Используются MongoDB ObjectId (24 символа hex)
Асинхронность: Анализ и стратегия выполняются асинхронно
Безопасность: Все эндпоинты требуют валидный JWT токен
Изоляция данных: Пользователи видят только свои данные
История статусов: Детальная история доступна для всех анализов и стратегий

Изменения: Поддержка типов анализов

Обзор изменений

В API добавлена поддержка различных типов маркетинговых анализов. Теперь при создании анализа можно указать тип анализа, который определяет фокус и содержание генерируемого отчета.

Новое поле в запросе

Поле: analysisType (обязательное)

Тип: string

Допустимые значения:

"РЫНОК" - Анализ рынка
"КОНКУРЕНТЫ" - Анализ конкурентов
"ЦА" - Анализ целевой аудитории
"КАНАЛЫ" - Анализ маркетинговых каналов
"SWOT" - SWOT-анализ

Описание типов анализов

1. РЫНОК

Генерирует анализ рынка, включающий:

Размер рынка
Динамику роста
Основные сегменты
Тренды и перспективы развития

2. КОНКУРЕНТЫ

Генерирует анализ конкурентов, включающий:

Основных конкурентов
Их сильные и слабые стороны
Позиционирование
Ценовую политику
Маркетинговые стратегии

3. ЦА (Целевая аудитория)

Генерирует анализ целевой аудитории, включающий:

Демографические характеристики
Психографический профиль
Потребности и боли
Поведенческие паттерны
Предпочтения

4. КАНАЛЫ

Генерирует анализ маркетинговых каналов, включающий:

Оценку эффективности различных каналов коммуникации
Рекомендации по выбору каналов
Особенности использования каждого канала
Бюджетные рекомендации

5. SWOT

Генерирует SWOT-анализ, включающий:

Сильные стороны (Strengths)
Слабые стороны (Weaknesses)
Возможности (Opportunities)
Угрозы (Threats)

Изменения в ответе

В ответе анализа теперь присутствует поле analysisType в объекте reportData, которое содержит название типа анализа.

Пример использования

// Запрос на создание 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' // Указываем тип анализа
    })
});

Миграция существующих интеграций

Если у вас есть существующие интеграции, которые не используют поле analysisType, необходимо:

Добавить поле analysisType в запрос
Выбрать подходящий тип анализа по умолчанию или позволить пользователю выбрать
Обновить UI для отображения выбора типа анализа

Поддержка

При возникновении проблем с API обращайтесь в техническую поддержку с указанием:

analysisId или strategyId (если есть)
Время запроса
Описание проблемы
Код ошибки (если есть)
JWT токен (только для отладки, не в продакшене!)

40 KiB Raw Permalink Blame History

API Документация: Маркетинговый анализ и стратегии (Frontend/AI Agent)

Базовый URL

Обзор

Аутентификация

Структура JWT токена

Ошибки аутентификации

Эндпоинты

1. Запуск маркетингового анализа

Заголовки запроса

Тело запроса (JSON)

Валидация полей

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

Пример успешного ответа (200 OK)

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

Заголовки запроса

Параметры пути

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

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

Статусы анализа

Ошибки доступа

3. Получение списка всех анализов пользователя

Заголовки запроса

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

Пример успешного ответа (200 OK)

Структура ответа

4. Получение детальной истории анализа

Заголовки запроса

Параметры пути

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

Пример успешного ответа (200 OK)

5. Скачивание PDF отчета

Заголовки запроса

Параметры пути

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

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

6. Генерация маркетинговой стратегии

Заголовки запроса

Параметры запроса

Тело запроса (JSON, опционально)

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

Пример успешного ответа (200 OK)

7. Получение результата стратегии

Заголовки запроса

Параметры пути

Пример ответа (когда стратегия завершена - 200 OK)

8. Получение стратегии по ID анализа

Заголовки запроса

Параметры пути

9. Получение списка всех стратегий пользователя

Заголовки запроса

Пример успешного ответа (200 OK)

10. Получение детальной истории стратегии

Заголовки запроса

Параметры пути

Пример успешного ответа (200 OK)

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

Коды ошибок

Формат ошибки

Примеры использования

JavaScript/TypeScript (Fetch API)

Получение JWT токена

Запуск анализа с JWT

Получение списка всех анализов пользователя

Получение детальной истории анализа

Полный пример: создание анализа и отслеживание статуса

Получение списка стратегий пользователя

Рекомендации по интеграции

1. Обработка JWT токена

2. Обработка ошибок аутентификации

3. Обработка ошибок доступа

4. Polling стратегия

5. Отображение истории статусов

6. Кэширование

Примечания

Изменения: Поддержка типов анализов

Обзор изменений

Новое поле в запросе

Описание типов анализов

1. РЫНОК

40 KiB

Raw Permalink Blame History