marketing-parser/docs/api/social-media-credentials.md

Social Media Credentials API - Frontend Guide

Обзор изменений

API для управления credentials социальных сетей был обновлен для поддержки разных форматов данных в зависимости от платформы. Поле credentials теперь может принимать как простую строку (токен), так и JSON объект для платформ, требующих несколько параметров.

Базовый URL

http://your-server:port/api/social-media/credentials

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

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

Authorization: Bearer <your-jwt-token>

Изменения в API

Поле credentials теперь поддерживает разные типы

До изменений:

• credentials был только String (токен)

После изменений:

• credentials может быть String (для простых токенов) или Object (для сложных структур)

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

1. Простой токен (String) - для Facebook, LinkedIn

{
  "platform": "facebook",
  "credentials": "EAABwzLix..."
}

2. JSON объект (Object) - для Telegram и других платформ с несколькими параметрами

{
  "platform": "telegram",
  "credentials": {
    "botToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
    "chatId": "-1001234567890"
  }
}

Endpoints

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

Endpoint: POST /api/social-media/credentials

Headers:

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

Request Body для простого токена (Facebook/LinkedIn):

{
  "platform": "facebook",
  "credentials": "EAABwzLix..."
}

Request Body для JSON объекта (Telegram):

{
  "platform": "telegram",
  "credentials": {
    "botToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
    "chatId": "-1001234567890"
  }
}

Response 200 OK:

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

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

// Сохранение простого токена (Facebook/LinkedIn)
const saveFacebookCredentials = async (accessToken) => {
  const response = await fetch('/api/social-media/credentials', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      platform: 'facebook',
      credentials: accessToken, // Простая строка
    }),
  });

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

// Сохранение JSON объекта (Telegram)
const saveTelegramCredentials = async (botToken, chatId) => {
  const response = await fetch('/api/social-media/credentials', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      platform: 'telegram',
      credentials: {
        // JSON объект
        botToken: botToken,
        chatId: chatId,
      },
    }),
  });

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

// Использование
await saveFacebookCredentials('EAABwzLix...');
await saveTelegramCredentials('123456789:ABC...', '-1001234567890');

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

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

Headers:

Authorization: Bearer <token>

Path Parameters:

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

Response 200 OK:

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

3. Получение списка всех 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"
    },
    {
      "platform": "telegram",
      "hasCredentials": true,
      "createdAt": "2024-01-15T11:00:00",
      "updatedAt": "2024-01-15T11:00:00"
    }
  ]
}

4. Удаление credentials

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

Headers:

Authorization: Bearer <token>

Path Parameters:

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

Response 200 OK:

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

Форматы credentials по платформам

Facebook

{
  "platform": "facebook",
  "credentials": "EAABwzLix..." // Access Token
}

LinkedIn

{
  "platform": "linkedin",
  "credentials": "AQV..." // Access Token
}

Telegram

{
  "platform": "telegram",
  "credentials": {
    "botToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
    "chatId": "-1001234567890"
  }
}

Примечание для Telegram:

• botToken - токен бота, полученный от @BotFather
• chatId - ID чата/канала (может быть отрицательным для групп и каналов)
• Формат: -1001234567890 для супергрупп и каналов

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

400 Bad Request - Ошибка валидации

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

401 Unauthorized

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

500 Internal Server Error

{
  "success": false,
  "message": "Внутренняя ошибка сервера",
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "Произошла ошибка при сохранении credentials"
  }
}

Миграция с старого API

Если вы использовали старый API, где credentials был только строкой, изменения минимальны:

Старый код:

body: JSON.stringify({
  platform: 'facebook',
  credentials: 'EAABwzLix...',
});

Новый код (без изменений для простых токенов):

// Работает как раньше
body: JSON.stringify({
  platform: 'facebook',
  credentials: 'EAABwzLix...', // String по-прежнему поддерживается
});

Для Telegram (новый формат):

body: JSON.stringify({
  platform: 'telegram',
  credentials: {
    // Теперь можно передавать объект
    botToken: '...',
    chatId: '...',
  },
});

Важные замечания

1. Обратная совместимость: API полностью обратно совместим. Старый формат (String) продолжает работать.

2. Автоматическая конвертация: Если вы передаете объект, он автоматически сериализуется в JSON строку перед сохранением.

3. Безопасность: Все credentials автоматически шифруются перед сохранением в базе данных.

4. Валидация: Поле credentials обязательно (@NotNull), но может быть как строкой, так и объектом.

Примеры для TypeScript

interface SimpleCredentials {
  platform: string;
  credentials: string; // Для Facebook, LinkedIn
}

interface TelegramCredentials {
  platform: 'telegram';
  credentials: {
    botToken: string;
    chatId: string;
  };
}

type CredentialsRequest = SimpleCredentials | TelegramCredentials;

// Использование
const saveCredentials = async (request: CredentialsRequest) => {
  const response = await fetch('/api/social-media/credentials', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(request),
  });

  return response.json();
};