.

2025-12-07 18:28:41 +05:00
parent 855a0d595e
commit 4ced171011
5 changed files with 597 additions and 88 deletions
@@ -0,0 +1,396 @@
+# 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();
+};
+```