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

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

## Базовый URL

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

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

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

```
Authorization: Bearer <your-jwt-token>
```

---

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

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

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

```http
GET /api/smm/campaigns
```

**Ответ:**

```json
[
    {
        "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

```http
GET /api/smm/campaigns/{id}
```

**Параметры:**

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

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

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

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

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

```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 Обновить кампанию

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

**Параметры:**

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

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

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

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

```http
DELETE /api/smm/campaigns/{id}
```

**Параметры:**

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

**Ответ:** 204 No Content

---

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

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

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

```http
GET /api/smm/channels
```

**Ответ:**

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

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

```http
GET /api/smm/channels/{id}
```

**Параметры:**

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

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

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

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

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

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

**Валидация:**

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

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

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

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

**Параметры:**

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

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

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

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

```http
DELETE /api/smm/channels/{id}
```

**Параметры:**

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

**Ответ:** 204 No Content

---

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

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

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

```http
GET /api/smm/content
```

**Ответ:**

```json
[
    {
        "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

```http
GET /api/smm/content/{id}
```

**Параметры:**

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

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

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

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

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

```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 Обновить контент

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

**Параметры:**

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

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

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

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

```http
DELETE /api/smm/content/{id}
```

**Параметры:**

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

**Ответ:** 204 No Content

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

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

**Параметры:**

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

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

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

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

**Параметры:**

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

**Ответ:**

```json
[
    {
        "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 Опубликовать контент

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

**Параметры:**

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

**Ответ:**

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

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

---

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

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

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

```http
POST /api/smm/analytics/collect-now
```

**Ответ:**

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

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

---

## Типы данных

### CampaignStatus

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

### ChannelType

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

### ContentStatus

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

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

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

---

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

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

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

```javascript
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'
    })
});
```

2. **Создать канал:**

```javascript
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
    })
});
```

3. **Создать контент:**

```javascript
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
    })
});
```

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

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

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

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

---

## Примечания

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