marketing/docs/POSTING_TASKS_API_FRONTEND.md

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, если задача была создана для этого элемента.

Пример ответа (обновленный формат)

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

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

POST /api/marketing/analysis/tasks/507f1f77bcf86cd799439013/execute
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

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

{
  "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 - Требуется аутентификация

{
  "success": false,
  "message": "Не авторизован",
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Требуется аутентификация. Пожалуйста, предоставьте валидный JWT токен."
  }
}

403 Forbidden - Пользователь не является владельцем задачи

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

404 Not Found - Задача не найдена

{
  "success": false,
  "message": "Задача не найдена",
  "error": {
    "code": "NOT_FOUND",
    "message": "Задача с указанным ID не найдена"
  }
}

400 Bad Request - Задача не может быть запущена

{
  "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: Запуск задачи, которая еще не была выполнена

// Получаем стратегию
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: Повторное выполнение неудачной задачи

// Если задача завершилась с ошибкой (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 в элементы календаря постов при получении стратегии