marketing-parser/docs/api/strategy-execution.md

API для запуска стратегий продвижения

Обзор

Данный документ описывает API для управления credentials социальных сетей и запуска маркетинговых стратегий с автоматической публикацией постов.

Базовый URL

http://your-server:port/api

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

Все endpoints требуют JWT токен в заголовке Authorization:

Authorization: Bearer <your-jwt-token>

Управление Credentials социальных сетей

1. Сохранение/обновление credentials

Сохраняет или обновляет credentials для указанной платформы. Credentials автоматически шифруются перед сохранением.

Endpoint: POST /api/social-media/credentials

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "platform": "facebook",
  "credentials": "your-facebook-access-token"
}

Параметры:

• platform (string, required) - Название платформы (например: "facebook", "instagram")
• credentials (string, required) - Access token или другие credentials для платформы

Response 200 OK:

{
  "success": true,
  "message": "Credentials успешно сохранены для платформы facebook",
  "data": {
    "platform": "facebook",
    "hasCredentials": true,
    "createdAt": "2024-01-15T10:30:00",
    "updatedAt": "2024-01-15T10:30:00"
  }
}

Response 400 Bad Request:

{
  "success": false,
  "message": "Ошибка валидации",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Platform is required",
    "details": {
      "platform": "Platform is required"
    }
  }
}

Response 401 Unauthorized:

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

Пример запроса (JavaScript):

const saveCredentials = async (platform, accessToken) => {
  const response = await fetch('/api/social-media/credentials', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      platform: platform,
      credentials: accessToken,
    }),
  });

  const data = await response.json();
  return data;
};

// Использование
await saveCredentials('facebook', 'EAABwzLix...');

---

2. Получение информации о credentials

Проверяет наличие credentials для указанной платформы.

Endpoint: GET /api/social-media/credentials/{platform}

Headers:

Authorization: Bearer <token>

Path Parameters:

• platform (string) - Название платформы

Response 200 OK:

{
  "success": true,
  "message": "Операция выполнена успешно",
  "data": {
    "platform": "facebook",
    "hasCredentials": true
  }
}

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

const checkCredentials = async (platform) => {
  const response = await fetch(`/api/social-media/credentials/${platform}`, {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
    },
  });

  const data = await response.json();
  return data.data.hasCredentials;
};

---

3. Получение списка всех credentials

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

Endpoint: GET /api/social-media/credentials

Headers:

Authorization: Bearer <token>

Response 200 OK:

{
  "success": true,
  "message": "Операция выполнена успешно",
  "data": [
    {
      "platform": "facebook",
      "hasCredentials": true,
      "createdAt": "2024-01-15T10:30:00",
      "updatedAt": "2024-01-15T10:30:00"
    }
  ]
}

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

const getAllCredentials = async () => {
  const response = await fetch('/api/social-media/credentials', {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
    },
  });

  const data = await response.json();
  return data.data;
};

---

4. Удаление credentials

Удаляет credentials для указанной платформы.

Endpoint: DELETE /api/social-media/credentials/{platform}

Headers:

Authorization: Bearer <token>

Path Parameters:

• platform (string) - Название платформы

Response 200 OK:

{
  "success": true,
  "message": "Credentials для платформы facebook успешно удалены",
  "data": null
}

Response 404 Not Found:

{
  "success": false,
  "message": "Credentials не найдены",
  "error": {
    "code": "NOT_FOUND",
    "message": "Credentials для платформы facebook не найдены"
  }
}

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

const deleteCredentials = async (platform) => {
  const response = await fetch(`/api/social-media/credentials/${platform}`, {
    method: 'DELETE',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
    },
  });

  const data = await response.json();
  return data;
};

---

Запуск стратегии продвижения

Запуск стратегии

Запускает выполнение маркетинговой стратегии. Система автоматически создает задачи публикации из календаря постов стратегии и добавляет их в очередь для выполнения.

Endpoint: POST /api/marketing/analysis/strategy/{strategyId}/start

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Path Parameters:

• strategyId (string) - ID стратегии для запуска

Request Body (опционально):

{}

Response 200 OK:

{
  "success": true,
  "message": "Стратегия успешно запущена",
  "data": {
    "strategyId": "67890abcdef",
    "tasksCreated": 12,
    "platforms": ["facebook", "instagram"],
    "message": "Стратегия успешно запущена. Создано задач: 12"
  }
}

Response 400 Bad Request (стратегия не завершена):

{
  "success": false,
  "message": "Стратегия не готова к запуску",
  "error": {
    "code": "INVALID_STATUS",
    "message": "Стратегия еще не завершена. Статус: processing"
  }
}

Response 400 Bad Request (нет credentials):

{
  "success": false,
  "message": "Не удалось запустить стратегию",
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "Credentials not found for platform: facebook. Please configure credentials first."
  }
}

Response 404 Not Found:

{
  "success": false,
  "message": "Стратегия не найдена",
  "error": {
    "code": "NOT_FOUND",
    "message": "Стратегия с указанным ID не найдена"
  }
}

Response 403 Forbidden:

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

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

const startStrategy = async (strategyId) => {
  const response = await fetch(
    `/api/marketing/analysis/strategy/${strategyId}/start`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${jwtToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({}),
    }
  );

  const data = await response.json();

  if (data.success) {
    console.log(`Создано задач: ${data.data.tasksCreated}`);
    console.log(`Платформы: ${data.data.platforms.join(', ')}`);
  } else {
    console.error('Ошибка:', data.error.message);
  }

  return data;
};

---

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

Шаг 1: Настройка credentials для Facebook

// Сохраняем Facebook Access Token
const facebookToken = 'EAABwzLix...'; // Получить из Facebook Developer Console

const result = await saveCredentials('facebook', facebookToken);
if (result.success) {
  console.log('Facebook credentials сохранены');
}

Шаг 2: Получение стратегии

// Получаем список стратегий пользователя
const response = await fetch('/api/marketing/analysis/strategy/my', {
  headers: {
    Authorization: `Bearer ${jwtToken}`,
  },
});

const data = await response.json();
const strategies = data.data;

// Выбираем завершенную стратегию
const completedStrategy = strategies.find((s) => s.status === 'completed');

Шаг 3: Запуск стратегии

if (completedStrategy) {
  // Проверяем наличие credentials для платформ стратегии
  const platforms = completedStrategy.priorityPlatforms || [];

  for (const platform of platforms) {
    const hasCreds = await checkCredentials(platform);
    if (!hasCreds) {
      console.warn(`Необходимо настроить credentials для ${platform}`);
      // Показать пользователю форму для ввода credentials
    }
  }

  // Запускаем стратегию
  const startResult = await startStrategy(completedStrategy.strategyId);

  if (startResult.success) {
    console.log(
      `Стратегия запущена! Создано ${startResult.data.tasksCreated} задач`
    );
    // Показать уведомление пользователю
  }
}

---

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

Типичные ошибки и их обработка

1. UNAUTHORIZED (401)

   • Причина: Невалидный или отсутствующий JWT токен
   • Решение: Обновить токен или перенаправить на страницу входа

2. VALIDATION_ERROR (400)

   • Причина: Невалидные данные в запросе
   • Решение: Проверить обязательные поля и их формат

3. MISSING_CREDENTIALS (400)

   • Причина: Не настроены credentials для платформы
   • Решение: Предложить пользователю настроить credentials

4. INVALID_STATUS (400)

   • Причина: Стратегия еще не завершена
   • Решение: Дождаться завершения генерации стратегии

5. NOT_FOUND (404)

   • Причина: Стратегия или credentials не найдены
   • Решение: Проверить правильность ID

6. FORBIDDEN (403)

   • Причина: Пользователь не имеет доступа к ресурсу
   • Решение: Проверить права доступа

Пример обработки ошибок

const handleApiError = (error) => {
  switch (error.code) {
    case 'UNAUTHORIZED':
      // Перенаправить на страницу входа
      window.location.href = '/login';
      break;

    case 'MISSING_CREDENTIALS':
      // Показать модальное окно для настройки credentials
      showCredentialsModal(error.message);
      break;

    case 'INVALID_STATUS':
      // Показать сообщение о том, что стратегия еще не готова
      showNotification(
        'Стратегия еще не завершена. Пожалуйста, подождите.',
        'warning'
      );
      break;

    case 'VALIDATION_ERROR':
      // Показать ошибки валидации
      showValidationErrors(error.details);
      break;

    default:
      showNotification('Произошла ошибка. Попробуйте позже.', 'error');
  }
};

// Использование
try {
  const result = await startStrategy(strategyId);
  if (!result.success) {
    handleApiError(result.error);
  }
} catch (error) {
  console.error('Network error:', error);
  showNotification('Ошибка сети. Проверьте подключение.', 'error');
}

---

Статусы задач публикации

После запуска стратегии создаются задачи со следующими статусами:

• pending - Задача ожидает выполнения (дата публикации еще не наступила)
• processing - Задача выполняется в данный момент
• completed - Задача успешно выполнена
• failed - Задача не выполнена из-за ошибки

Примечание: Задачи с датой публикации в прошлом выполняются сразу после создания.

---

Планировщик задач

Система автоматически проверяет очередь задач каждую минуту и выполняет задачи, у которых наступило время публикации.

• Планировщик включен по умолчанию
• Можно отключить через настройку posting.scheduler.enabled=false
• Задачи выполняются асинхронно

---

Поддерживаемые платформы

На данный момент поддерживается:

• Facebook - через Facebook Graph API v18.0

В будущем планируется поддержка:

• Instagram
• LinkedIn
• Telegram
• TikTok
• YouTube

---

Получение Facebook Access Token

Для получения Facebook Access Token:

1. Перейдите на Facebook Developers
2. Создайте приложение
3. Добавьте продукт "Facebook Login"
4. Настройте OAuth и получите Access Token
5. Используйте полученный токен в API

Важно:

• Access Token имеет срок действия
• Для долгосрочного использования рекомендуется использовать Long-Lived Token
• Токен должен иметь разрешения pages_manage_posts для публикации

Для запуска рекламных кампаний в Facebook требуется дополнительная настройка:

📖 Подробная инструкция: См. facebook-setup.md

Для рекламы нужны:

• Access Token с разрешениями ads_management, ads_read, business_management
• Ad Account ID (формат: act_XXXXXXXXX)
• App ID и App Secret
• Page ID (опционально)

---

Примеры React компонентов

Компонент для настройки credentials

import React, { useState } from 'react';

const CredentialsForm = ({ platform, onSave }) => {
  const [token, setToken] = useState('');
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  const handleSubmit = async (e) => {
    e.preventDefault();
    setLoading(true);
    setError(null);

    try {
      const response = await fetch('/api/social-media/credentials', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${jwtToken}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          platform: platform,
          credentials: token,
        }),
      });

      const data = await response.json();

      if (data.success) {
        onSave();
        setToken('');
      } else {
        setError(data.error.message);
      }
    } catch (err) {
      setError('Ошибка сети');
    } finally {
      setLoading(false);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <div>
        <label>Access Token для {platform}:</label>
        <input
          type='text'
          value={token}
          onChange={(e) => setToken(e.target.value)}
          required
        />
      </div>
      {error && <div className='error'>{error}</div>}
      <button type='submit' disabled={loading}>
        {loading ? 'Сохранение...' : 'Сохранить'}
      </button>
    </form>
  );
};

export default CredentialsForm;

Компонент для запуска стратегии

import React, { useState } from 'react';

const StartStrategyButton = ({ strategyId, onStart }) => {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  const handleStart = async () => {
    setLoading(true);
    setError(null);

    try {
      const response = await fetch(
        `/api/marketing/analysis/strategy/${strategyId}/start`,
        {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${jwtToken}`,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({}),
        }
      );

      const data = await response.json();

      if (data.success) {
        onStart(data.data);
      } else {
        setError(data.error.message);
      }
    } catch (err) {
      setError('Ошибка сети');
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <button onClick={handleStart} disabled={loading}>
        {loading ? 'Запуск...' : 'Запустить стратегию'}
      </button>
      {error && <div className='error'>{error}</div>}
    </div>
  );
};

export default StartStrategyButton;

---

Часто задаваемые вопросы

Q: Как часто проверяются задачи на выполнение?

A: Планировщик проверяет очередь каждую минуту.

Q: Что происходит, если credentials истекли?

A: Задача получит статус failed с сообщением об ошибке. Необходимо обновить credentials и перезапустить стратегию.

Q: Можно ли отменить выполнение стратегии?

A: На данный момент нет, но можно удалить credentials для платформы, что предотвратит выполнение будущих задач.

Q: Как узнать статус выполнения задач?

A: Статусы задач можно получить через API (будет добавлено в будущих версиях).

Q: Поддерживается ли публикация с изображениями?

A: На данный момент поддерживается только текстовая публикация. Поддержка изображений планируется в будущем.

---

Версионирование API

Текущая версия: v1

Все endpoints могут изменяться в будущих версиях. При изменении API будет указана новая версия.

---

Поддержка

При возникновении проблем:

1. Проверьте логи в консоли браузера
2. Убедитесь, что JWT токен валиден
3. Проверьте формат запросов согласно документации
4. Обратитесь к разработчикам с описанием проблемы