digiops/marketing

Fork 0

Files

T

root b887e4d652 init

2025-09-24 10:10:42 +05:00

12 KiB

Raw Permalink Blame History

API Документация для Фронтенда

Данная документация описывает все доступные API эндпоинты для фронтенда системы управления социальными сетями Konturai.

Базовый URL

https://api.konturai.kz/api/smm

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

Все запросы требуют аутентификации. Используйте Bearer токен в заголовке Authorization:

Authorization: Bearer <your-jwt-token>

1. CampaignController - Управление кампаниями

Базовый путь: /api/smm/campaigns

1.1 Получить все кампании

GET /api/smm/campaigns

Ответ:

[
    {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Новогодняя кампания",
        "goal": "Увеличение продаж на 20%",
        "budget": 100000.0,
        "startAt": "2024-01-01T00:00:00Z",
        "endAt": "2024-01-31T23:59:59Z",
        "status": "ACTIVE"
    }
]

1.2 Получить кампанию по ID

GET /api/smm/campaigns/{id}

Параметры:

id (UUID) - ID кампании

Ответ: Объект CampaignDto

1.3 Создать кампанию

POST /api/smm/campaigns
Content-Type: application/json

Тело запроса:

{
    "name": "Новогодняя кампания",
    "goal": "Увеличение продаж на 20%",
    "budget": 100000.0,
    "startAt": "2024-01-01T00:00:00Z",
    "endAt": "2024-01-31T23:59:59Z",
    "status": "PLANNED"
}

Валидация:

name - обязательное поле, не пустое
budget - должно быть >= 0
startAt - дата должна быть в будущем или настоящем
endAt - дата должна быть в будущем

Ответ: 201 Created, объект CampaignDto

1.4 Обновить кампанию

PUT /api/smm/campaigns/{id}
Content-Type: application/json

Параметры:

id (UUID) - ID кампании

Тело запроса: То же, что и при создании

Ответ: Объект CampaignDto

1.5 Удалить кампанию

DELETE /api/smm/campaigns/{id}

Параметры:

id (UUID) - ID кампании

Ответ: 204 No Content

2. ChannelController - Управление каналами

Базовый путь: /api/smm/channels

2.1 Получить все каналы

GET /api/smm/channels

Ответ:

[
    {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "Основной Telegram канал",
        "type": "TELEGRAM",
        "isActive": true
    }
]

2.2 Получить канал по ID

GET /api/smm/channels/{id}

Параметры:

id (UUID) - ID канала

Ответ: Объект ChannelDto

2.3 Создать канал

POST /api/smm/channels
Content-Type: application/json

Тело запроса:

{
    "name": "Основной Telegram канал",
    "type": "TELEGRAM",
    "apiKeyRef": "telegram_bot_token",
    "isActive": true
}

Валидация:

name - обязательное поле, не пустое
type - обязательное поле, один из: TELEGRAM, VK, INSTAGRAM
apiKeyRef - обязательное поле, не пустое

Ответ: 201 Created, объект ChannelDto

2.4 Обновить канал

PUT /api/smm/channels/{id}
Content-Type: application/json

Параметры:

id (UUID) - ID канала

Тело запроса: То же, что и при создании

Ответ: Объект ChannelDto

2.5 Удалить канал

DELETE /api/smm/channels/{id}

Параметры:

id (UUID) - ID канала

Ответ: 204 No Content

3. ContentController - Управление контентом

Базовый путь: /api/smm/content

3.1 Получить весь контент

GET /api/smm/content

Ответ:

[
    {
        "id": "550e8400-e29b-41d4-a716-446655440002",
        "campaignId": "550e8400-e29b-41d4-a716-446655440000",
        "locale": "ru",
        "topic": "Новогодние скидки",
        "postDraft": "Специальное предложение на новогодние праздники!",
        "assetsRefs": "image1.jpg,image2.jpg",
        "scheduledAt": "2024-01-15T10:00:00Z",
        "priority": 1,
        "status": "PENDING_APPROVAL"
    }
]

3.2 Получить контент по ID

GET /api/smm/content/{id}

Параметры:

id (UUID) - ID контента

Ответ: Объект ContentQueueDto

3.3 Создать контент

POST /api/smm/content
Content-Type: application/json

Тело запроса:

{
    "campaignId": "550e8400-e29b-41d4-a716-446655440000",
    "locale": "ru",
    "topic": "Новогодние скидки",
    "postDraft": "Специальное предложение на новогодние праздники!",
    "assetsRefs": "image1.jpg,image2.jpg",
    "scheduledAt": "2024-01-15T10:00:00Z",
    "priority": 1
}

Валидация:

campaignId - обязательное поле, должен существовать
locale - обязательное поле, не пустое
topic - обязательное поле, не пустое

Ответ: 201 Created, объект ContentQueueDto

3.4 Обновить контент

PUT /api/smm/content/{id}
Content-Type: application/json

Параметры:

id (UUID) - ID контента

Тело запроса: То же, что и при создании

Ответ: Объект ContentQueueDto

3.5 Удалить контент

DELETE /api/smm/content/{id}

Параметры:

id (UUID) - ID контента

Ответ: 204 No Content

3.6 Одобрить контент

POST /api/smm/content/{id}/approve

Параметры:

id (UUID) - ID контента

Ответ: Объект ContentQueueDto со статусом APPROVED

3.7 Получить сообщения контента

GET /api/smm/content/{id}/messages

Параметры:

id (UUID) - ID контента

Ответ:

[
    {
        "id": "550e8400-e29b-41d4-a716-446655440003",
        "channelId": "550e8400-e29b-41d4-a716-446655440001",
        "contentId": "550e8400-e29b-41d4-a716-446655440002",
        "externalId": "12345",
        "url": "https://t.me/channel/12345",
        "postedAt": "2024-01-15T10:00:00Z"
    }
]

4. PublishingController - Публикация контента

Базовый путь: /api/smm/publishing

4.1 Опубликовать контент

POST /api/smm/publishing/post/{contentId}

Параметры:

contentId (UUID) - ID контента для публикации

Ответ:

{
    "success": true,
    "message": "Пост успешно опубликован",
    "data": {
        "messageId": "550e8400-e29b-41d4-a716-446655440003",
        "externalUrl": "https://t.me/channel/12345"
    }
}

Примечание: Контент должен быть в статусе APPROVED для публикации.

5. AnalyticsController - Аналитика

Базовый путь: /api/smm/analytics

5.1 Запустить сбор аналитики

POST /api/smm/analytics/collect-now

Ответ:

{
    "success": true,
    "message": "Сбор аналитики запущен."
}

Примечание: Этот эндпоинт предназначен для администраторов и отладки. Обычно аналитика собирается автоматически по расписанию.

Типы данных

CampaignStatus

enum CampaignStatus {
    PLANNED = 'PLANNED',
    ACTIVE = 'ACTIVE',
    COMPLETED = 'COMPLETED'
}

ChannelType

enum ChannelType {
    TELEGRAM = 'TELEGRAM',
    VK = 'VK',
    INSTAGRAM = 'INSTAGRAM'
}

ContentStatus

enum ContentStatus {
    DRAFT = 'DRAFT',
    PENDING_APPROVAL = 'PENDING_APPROVAL',
    APPROVED = 'APPROVED',
    PUBLISHED = 'PUBLISHED',
    FAILED = 'FAILED'
}

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

Стандартные HTTP коды ответов:

200 OK - Успешный запрос
201 Created - Ресурс создан
204 No Content - Успешное удаление
400 Bad Request - Ошибка валидации
401 Unauthorized - Не авторизован
403 Forbidden - Нет доступа
404 Not Found - Ресурс не найден
500 Internal Server Error - Внутренняя ошибка сервера

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

{
    "timestamp": "2024-01-15T10:00:00Z",
    "status": 400,
    "error": "Bad Request",
    "message": "Validation failed",
    "path": "/api/smm/campaigns"
}

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

Создание полного workflow:

Создать кампанию:

const campaign = await fetch('/api/smm/campaigns', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer ' + token
    },
    body: JSON.stringify({
        name: 'Новогодняя кампания',
        goal: 'Увеличение продаж',
        budget: 100000,
        startAt: '2024-01-01T00:00:00Z',
        endAt: '2024-01-31T23:59:59Z',
        status: 'PLANNED'
    })
});

Создать канал:

const channel = await fetch('/api/smm/channels', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer ' + token
    },
    body: JSON.stringify({
        name: 'Основной канал',
        type: 'TELEGRAM',
        apiKeyRef: 'telegram_bot_token',
        isActive: true
    })
});

Создать контент:

const content = await fetch('/api/smm/content', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer ' + token
    },
    body: JSON.stringify({
        campaignId: campaign.id,
        locale: 'ru',
        topic: 'Новогодние скидки',
        postDraft: 'Специальное предложение!',
        scheduledAt: '2024-01-15T10:00:00Z',
        priority: 1
    })
});

Одобрить контент:

await fetch(`/api/smm/content/${content.id}/approve`, {
    method: 'POST',
    headers: {
        Authorization: 'Bearer ' + token
    }
});

Опубликовать контент:

const publishResult = await fetch(`/api/smm/publishing/post/${content.id}`, {
    method: 'POST',
    headers: {
        Authorization: 'Bearer ' + token
    }
});

Примечания

Все даты передаются в формате ISO 8601 с UTC временной зоной
UUID используются для всех идентификаторов
Все запросы требуют аутентификации через JWT токен
Система автоматически публикует контент по расписанию (если scheduledAt указан)
Аналитика собирается автоматически каждый час

12 KiB Raw Permalink Blame History

API Документация для Фронтенда

Базовый URL

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

1. CampaignController - Управление кампаниями

1.1 Получить все кампании

1.2 Получить кампанию по ID

1.3 Создать кампанию

1.4 Обновить кампанию

1.5 Удалить кампанию

2. ChannelController - Управление каналами

2.1 Получить все каналы

2.2 Получить канал по ID

2.3 Создать канал

2.4 Обновить канал

2.5 Удалить канал

3. ContentController - Управление контентом

3.1 Получить весь контент

3.2 Получить контент по ID

3.3 Создать контент

3.4 Обновить контент

3.5 Удалить контент

3.6 Одобрить контент

3.7 Получить сообщения контента

4. PublishingController - Публикация контента

4.1 Опубликовать контент

5. AnalyticsController - Аналитика

5.1 Запустить сбор аналитики

Типы данных

CampaignStatus

ChannelType

ContentStatus

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

Стандартные HTTP коды ответов:

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

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

Создание полного workflow:

Примечания

12 KiB

Raw Permalink Blame History