287 lines
11 KiB
Markdown
287 lines
11 KiB
Markdown
# API Документация: Управление задачами публикации (Frontend/AI Agent)
|
|
|
|
## Базовый URL
|
|
|
|
```
|
|
https://api.konturai.kz
|
|
```
|
|
|
|
## Обзор
|
|
|
|
API для управления задачами публикации постов в социальных сетях. Позволяет запускать задачи публикации вручную, не дожидаясь времени выполнения через шедулер.
|
|
|
|
**Важно**:
|
|
|
|
- Для выполнения задачи требуются настроенные credentials для соответствующей платформы
|
|
- Задачи создаются автоматически при запуске стратегии через `/api/marketing/analysis/strategy/{strategyId}/start`
|
|
- Каждая задача связана с элементом календаря постов в стратегии
|
|
|
|
---
|
|
|
|
## Изменения в существующих эндпоинтах
|
|
|
|
### Обновление: Получение стратегии по ID анализа
|
|
|
|
**GET** `/api/marketing/analysis/{analysisId}/strategy`
|
|
|
|
Теперь каждый элемент в `postCalendar` содержит поле `taskId`, если задача была создана для этого элемента.
|
|
|
|
#### Пример ответа (обновленный формат)
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"strategyId": "507f1f77bcf86cd799439012",
|
|
"analysisId": "507f1f77bcf86cd799439011",
|
|
"status": "completed",
|
|
"strategy": {
|
|
"postCalendar": [
|
|
{
|
|
"publishDate": "2025-01-25T10:00:00",
|
|
"platform": "Facebook",
|
|
"contentType": "пост",
|
|
"theme": "Презентация продукта",
|
|
"postText": "Добро пожаловать в наш новый продукт!",
|
|
"hashtags": ["#маркетинг", "#бизнес"],
|
|
"publishTime": "10:00",
|
|
"imageUrl": "post_image_1234567890.png",
|
|
"imageFilename": "post_image_1234567890.png",
|
|
"taskId": "507f1f77bcf86cd799439013"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Новое поле:**
|
|
|
|
- `taskId` (string, опциональное) - ID задачи публикации, если задача была создана. Может быть `null`, если стратегия еще не была запущена.
|
|
|
|
---
|
|
|
|
## Новые эндпоинты
|
|
|
|
### 1. Ручной запуск задачи публикации
|
|
|
|
**POST** `/api/marketing/analysis/tasks/{taskId}/execute`
|
|
|
|
Запускает задачу публикации немедленно, не дожидаясь времени публикации через шедулер. Позволяет выполнить задачу вручную или повторить выполнение неудачной задачи.
|
|
|
|
#### Параметры запроса
|
|
|
|
| Параметр | Тип | Расположение | Обязательный | Описание |
|
|
| -------- | ------ | ------------ | ------------ | -------------------- |
|
|
| `taskId` | string | Path | ✅ | ID задачи публикации |
|
|
|
|
#### Заголовки запроса
|
|
|
|
```
|
|
Authorization: Bearer <your-jwt-token>
|
|
Content-Type: application/json
|
|
```
|
|
|
|
#### Пример запроса
|
|
|
|
```http
|
|
POST /api/marketing/analysis/tasks/507f1f77bcf86cd799439013/execute
|
|
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
|
Content-Type: application/json
|
|
```
|
|
|
|
#### Пример успешного ответа (200 OK)
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Задача успешно запущена",
|
|
"data": {
|
|
"taskId": "507f1f77bcf86cd799439013",
|
|
"status": "processing",
|
|
"platform": "Facebook",
|
|
"publishDate": "2025-01-25T10:00:00"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Описание полей ответа
|
|
|
|
| Поле | Тип | Описание |
|
|
| ------------- | ------ | ----------------------------------------------------- |
|
|
| `taskId` | string | ID задачи публикации |
|
|
| `status` | string | Статус задачи: `processing`, `completed` или `failed` |
|
|
| `platform` | string | Платформа для публикации (например, `Facebook`) |
|
|
| `publishDate` | string | Дата и время публикации в формате ISO 8601 |
|
|
|
|
#### Ошибки
|
|
|
|
**401 Unauthorized** - Требуется аутентификация
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"message": "Не авторизован",
|
|
"error": {
|
|
"code": "UNAUTHORIZED",
|
|
"message": "Требуется аутентификация. Пожалуйста, предоставьте валидный JWT токен."
|
|
}
|
|
}
|
|
```
|
|
|
|
**403 Forbidden** - Пользователь не является владельцем задачи
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"message": "Доступ запрещен",
|
|
"error": {
|
|
"code": "FORBIDDEN",
|
|
"message": "У вас нет доступа к этой задаче"
|
|
}
|
|
}
|
|
```
|
|
|
|
**404 Not Found** - Задача не найдена
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"message": "Задача не найдена",
|
|
"error": {
|
|
"code": "NOT_FOUND",
|
|
"message": "Задача с указанным ID не найдена"
|
|
}
|
|
}
|
|
```
|
|
|
|
**400 Bad Request** - Задача не может быть запущена
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"message": "Задача не может быть запущена",
|
|
"error": {
|
|
"code": "INVALID_STATUS",
|
|
"message": "Task cannot be executed manually. Current status: completed. Only tasks with status 'pending' or 'failed' can be executed manually."
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Правила выполнения
|
|
|
|
1. **Статусы задач:**
|
|
|
|
- `pending` - задача ожидает выполнения (может быть запущена вручную)
|
|
- `failed` - задача завершилась с ошибкой (может быть запущена повторно вручную)
|
|
- `processing` - задача выполняется (не может быть запущена повторно)
|
|
- `completed` - задача успешно выполнена (не может быть запущена повторно)
|
|
|
|
2. **Повторное выполнение:**
|
|
|
|
- Задачи со статусом `failed` автоматически сбрасываются на `pending` перед повторным выполнением
|
|
- Ошибка из предыдущего выполнения очищается
|
|
|
|
3. **Асинхронное выполнение:**
|
|
- Задача запускается асинхронно
|
|
- Ответ возвращается сразу после начала выполнения
|
|
- Для проверки статуса задачи используйте соответствующие эндпоинты (если доступны)
|
|
|
|
#### Примеры использования
|
|
|
|
**Пример 1: Запуск задачи, которая еще не была выполнена**
|
|
|
|
```javascript
|
|
// Получаем стратегию
|
|
const strategyResponse = await fetch(
|
|
`/api/marketing/analysis/${analysisId}/strategy`,
|
|
{
|
|
headers: {
|
|
Authorization: `Bearer ${token}`,
|
|
},
|
|
}
|
|
);
|
|
|
|
const strategy = await strategyResponse.json();
|
|
const taskId = strategy.data.strategy.postCalendar[0].taskId;
|
|
|
|
// Запускаем задачу вручную
|
|
const executeResponse = await fetch(
|
|
`/api/marketing/analysis/tasks/${taskId}/execute`,
|
|
{
|
|
method: 'POST',
|
|
headers: {
|
|
Authorization: `Bearer ${token}`,
|
|
'Content-Type': 'application/json',
|
|
},
|
|
}
|
|
);
|
|
|
|
const result = await executeResponse.json();
|
|
console.log('Задача запущена:', result.data);
|
|
```
|
|
|
|
**Пример 2: Повторное выполнение неудачной задачи**
|
|
|
|
```javascript
|
|
// Если задача завершилась с ошибкой (status: "failed")
|
|
// можно повторить её выполнение
|
|
const retryResponse = await fetch(
|
|
`/api/marketing/analysis/tasks/${failedTaskId}/execute`,
|
|
{
|
|
method: 'POST',
|
|
headers: {
|
|
Authorization: `Bearer ${token}`,
|
|
'Content-Type': 'application/json',
|
|
},
|
|
}
|
|
);
|
|
|
|
const retryResult = await retryResponse.json();
|
|
if (retryResult.success) {
|
|
console.log('Повторная попытка запущена:', retryResult.data);
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Интеграция с существующим workflow
|
|
|
|
### Типичный сценарий использования
|
|
|
|
1. **Создание анализа** → `POST /api/marketing/analysis/start`
|
|
2. **Генерация стратегии** → `POST /api/marketing/analysis/strategy/generate`
|
|
3. **Получение стратегии** → `GET /api/marketing/analysis/{analysisId}/strategy`
|
|
- Теперь содержит `taskId` для каждого элемента календаря
|
|
4. **Запуск стратегии** → `POST /api/marketing/analysis/strategy/{strategyId}/start`
|
|
- Создает задачи публикации для всех элементов календаря
|
|
5. **Ручной запуск задачи** (опционально) → `POST /api/marketing/analysis/tasks/{taskId}/execute`
|
|
- Запускает задачу немедленно, не дожидаясь времени публикации
|
|
|
|
### Когда использовать ручной запуск
|
|
|
|
- **Тестирование**: Проверить публикацию поста перед запланированным временем
|
|
- **Повторная попытка**: Повторить выполнение задачи, которая завершилась с ошибкой
|
|
- **Срочная публикация**: Опубликовать пост раньше запланированного времени
|
|
- **Отладка**: Проверить работу системы публикации
|
|
|
|
---
|
|
|
|
## Примечания
|
|
|
|
1. **Аутентификация**: Все эндпоинты требуют валидный JWT токен в заголовке `Authorization`
|
|
2. **Права доступа**: Пользователь может запускать только свои собственные задачи
|
|
3. **Статусы задач**: Проверяйте статус задачи перед попыткой ручного запуска
|
|
4. **Асинхронность**: Выполнение задачи происходит асинхронно, ответ возвращается сразу
|
|
5. **Ошибки выполнения**: Если задача завершится с ошибкой, её можно запустить повторно
|
|
|
|
---
|
|
|
|
## Версия API
|
|
|
|
- **Версия документа**: 1.0
|
|
- **Дата обновления**: 2025-01-20
|
|
- **Изменения**:
|
|
- Добавлен эндпоинт для ручного запуска задач публикации
|
|
- Добавлено поле `taskId` в элементы календаря постов при получении стратегии
|