marketing-parser/SOCIAL_MEDIA_CREDENTIALS_API_FRONTEND.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

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

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

```json
{
  "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):**

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

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

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

**Response 200 OK:**

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

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

```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:**

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

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

**Endpoint:** `GET /api/social-media/credentials`

**Headers:**

```
Authorization: Bearer <token>
```

**Response 200 OK:**

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

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

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

### Facebook

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

### LinkedIn

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

### Telegram

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

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

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

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

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

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

### 401 Unauthorized

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

### 500 Internal Server Error

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

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

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

**Старый код:**

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

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

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

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

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

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

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

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

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

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

## Примеры для TypeScript

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