marketing-parser/FACEBOOK_ADS_CREDENTIALS.md

# Учетные данные Facebook для запуска рекламы

## Обзор

Для запуска рекламных кампаний в Facebook через Marketing API (ранее Ads API) требуются специальные учетные данные, которые отличаются от простого Access Token для публикации постов.

---

## Необходимые учетные данные

### 1. **Access Token (обязательно)**

Access Token с расширенными разрешениями для управления рекламой.

**Требуемые разрешения (Permissions):**

- `ads_management` - Управление рекламными кампаниями
- `ads_read` - Чтение данных о рекламе
- `business_management` - Управление бизнес-аккаунтом
- `pages_read_engagement` - Чтение данных страниц (опционально)

**Типы токенов:**

- **User Access Token** - краткосрочный (1-2 часа)
- **Long-Lived User Access Token** - долгосрочный (60 дней)
- **Page Access Token** - для управления страницами
- **System User Access Token** - для серверных приложений (рекомендуется для продакшена)

---

### 2. **Ad Account ID (обязательно)**

ID рекламного аккаунта Facebook, в котором будут создаваться кампании.

**Формат:** `act_XXXXXXXXX` (например: `act_123456789`)

**Где найти:**

1. Перейдите в [Facebook Ads Manager](https://business.facebook.com/adsmanager)
2. В настройках аккаунта найдите "Account ID"
3. Или используйте API: `GET /me/adaccounts`

---

### 3. **App ID и App Secret (обязательно для серверных приложений)**

Учетные данные Facebook приложения.

**Где найти:**

1. Перейдите на [Facebook Developers](https://developers.facebook.com/)
2. Выберите ваше приложение
3. В разделе "Settings" → "Basic" найдите:
   - **App ID**
   - **App Secret** (нажмите "Show" для отображения)

**Важно:** App Secret должен храниться в безопасности и никогда не передаваться на клиент.

---

### 4. **Page ID (опционально, но рекомендуется)**

ID страницы Facebook, связанной с рекламным аккаунтом.

**Где найти:**

1. Перейдите на вашу страницу Facebook
2. В настройках страницы найдите "Page ID"
3. Или используйте API: `GET /me/accounts`

---

## Пошаговая инструкция получения учетных данных

### Шаг 1: Создание Facebook приложения

1. Перейдите на [Facebook Developers](https://developers.facebook.com/)
2. Нажмите "My Apps" → "Create App"
3. Выберите тип приложения: **"Business"** или **"Other"**
4. Заполните название и контактный email
5. Нажмите "Create App"

### Шаг 2: Добавление продукта "Marketing API"

1. В панели управления приложением найдите раздел "Add Products"
2. Найдите "Marketing API" и нажмите "Set Up"
3. Следуйте инструкциям для настройки

### Шаг 3: Получение App ID и App Secret

1. В левом меню выберите "Settings" → "Basic"
2. Скопируйте **App ID**
3. Нажмите "Show" рядом с **App Secret** и скопируйте его
4. **Сохраните эти данные в безопасном месте**

### Шаг 4: Настройка разрешений (Permissions)

1. В левом меню выберите "Settings" → "Advanced"
2. Добавьте в "Valid OAuth Redirect URIs" ваш callback URL
3. В разделе "Permissions and Features" запросите:
   - `ads_management`
   - `ads_read`
   - `business_management`
   - `pages_read_engagement`

### Шаг 5: Получение Access Token

#### Вариант A: User Access Token (для тестирования)

1. Перейдите в [Graph API Explorer](https://developers.facebook.com/tools/explorer/)
2. Выберите ваше приложение
3. Нажмите "Generate Access Token"
4. Выберите необходимые разрешения
5. Скопируйте полученный токен

#### Вариант B: Long-Lived Token (для разработки)

```bash
# Обмен краткосрочного токена на долгосрочный
curl -X GET "https://graph.facebook.com/v18.0/oauth/access_token?grant_type=fb_exchange_token&client_id={app-id}&client_secret={app-secret}&fb_exchange_token={short-lived-token}"
```

#### Вариант C: System User Token (для продакшена - рекомендуется)

1. В панели управления приложением перейдите в "Business Settings"
2. Создайте System User
3. Назначьте ему доступ к рекламному аккаунту
4. Сгенерируйте токен для System User

### Шаг 6: Получение Ad Account ID

**Через Ads Manager:**

1. Перейдите в [Facebook Ads Manager](https://business.facebook.com/adsmanager)
2. В настройках аккаунта найдите "Account ID"

**Через API:**

```bash
curl -X GET "https://graph.facebook.com/v18.0/me/adaccounts?access_token={access-token}"
```

Ответ будет содержать массив с `id` в формате `act_XXXXXXXXX`.

---

## Структура учетных данных для вашего API

Для интеграции с вашей системой, учетные данные Facebook для рекламы должны быть сохранены в следующем формате:

### Формат JSON для сохранения credentials

```json
{
  "platform": "facebook_ads",
  "credentials": {
    "accessToken": "EAABwzLix...",
    "adAccountId": "act_123456789",
    "appId": "1234567890123456",
    "appSecret": "your-app-secret-here",
    "pageId": "1234567890123456",
    "tokenType": "LONG_LIVED",
    "expiresAt": "2024-12-31T23:59:59Z"
  }
}
```

### Пример сохранения через API

```javascript
const facebookAdsCredentials = {
  platform: 'facebook_ads',
  credentials: JSON.stringify({
    accessToken: 'EAABwzLix...',
    adAccountId: 'act_123456789',
    appId: '1234567890123456',
    appSecret: 'your-app-secret-here',
    pageId: '1234567890123456',
    tokenType: 'LONG_LIVED',
    expiresAt: '2024-12-31T23:59:59Z',
  }),
};

// Сохранение через ваш API
const response = await fetch('/api/social-media/credentials', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${jwtToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(facebookAdsCredentials),
});
```

---

## Требования и ограничения

### Ограничения Facebook Marketing API

1. **Rate Limits:**

   - 200 вызовов в час на пользователя
   - 4800 вызовов в час на приложение

2. **Минимальные требования:**

   - Рекламный аккаунт должен быть активен
   - У пользователя должны быть права администратора на аккаунте
   - Приложение должно пройти ревью Facebook (для продакшена)

3. **Версия API:**
   - Текущая версия: v18.0
   - Facebook регулярно обновляет API, следите за изменениями

### Безопасность

1. **Никогда не храните App Secret в открытом виде**
2. **Используйте шифрование для хранения credentials** (ваша система уже использует шифрование)
3. **Регулярно обновляйте токены** (Long-Lived токены истекают через 60 дней)
4. **Используйте System User Token для продакшена** вместо User Token

---

## Проверка учетных данных

### Проверка Access Token

```bash
curl -X GET "https://graph.facebook.com/v18.0/me?access_token={access-token}"
```

Если токен валиден, вы получите информацию о пользователе.

### Проверка доступа к Ad Account

```bash
curl -X GET "https://graph.facebook.com/v18.0/{ad-account-id}?access_token={access-token}&fields=id,name,account_id"
```

Если доступ есть, вы получите информацию об аккаунте.

### Проверка разрешений

```bash
curl -X GET "https://graph.facebook.com/v18.0/me/permissions?access_token={access-token}"
```

Проверьте, что в ответе есть:

- `ads_management` со статусом `granted`
- `ads_read` со статусом `granted`
- `business_management` со статусом `granted`

---

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

### Создание кампании

```bash
curl -X POST "https://graph.facebook.com/v18.0/{ad-account-id}/campaigns" \
  -d "name=Test Campaign" \
  -d "objective=OUTCOME_TRAFFIC" \
  -d "status=PAUSED" \
  -d "access_token={access-token}"
```

### Создание Ad Set

```bash
curl -X POST "https://graph.facebook.com/v18.0/{ad-account-id}/adsets" \
  -d "name=Test Ad Set" \
  -d "campaign_id={campaign-id}" \
  -d "billing_event=IMPRESSIONS" \
  -d "optimization_goal=REACH" \
  -d "bid_amount=100" \
  -d "daily_budget=1000" \
  -d "targeting={'geo_locations':{'countries':['KZ']}}" \
  -d "access_token={access-token}"
```

---

## Обновление токенов

Access Token имеет срок действия. Для автоматического обновления:

1. **Отслеживайте срок действия токена** (`expiresAt`)
2. **Используйте refresh token** (если доступен)
3. **Или запросите новый токен** перед истечением старого

### Обмен краткосрочного токена на долгосрочный

```javascript
async function exchangeToken(shortLivedToken, appId, appSecret) {
  const response = await fetch(
    `https://graph.facebook.com/v18.0/oauth/access_token?grant_type=fb_exchange_token&client_id=${appId}&client_secret=${appSecret}&fb_exchange_token=${shortLivedToken}`
  );

  const data = await response.json();
  return {
    accessToken: data.access_token,
    expiresIn: data.expires_in, // в секундах
    expiresAt: new Date(Date.now() + data.expires_in * 1000).toISOString(),
  };
}
```

---

## Рекомендации

1. **Для разработки:** Используйте Long-Lived User Access Token
2. **Для продакшена:** Используйте System User Access Token
3. **Храните credentials в зашифрованном виде** (ваша система уже это делает)
4. **Реализуйте автоматическое обновление токенов**
5. **Логируйте все операции с рекламой** для отладки
6. **Обрабатывайте ошибки API** (rate limits, invalid tokens, etc.)

---

## Полезные ссылки

- [Facebook Marketing API Documentation](https://developers.facebook.com/docs/marketing-apis)
- [Facebook Graph API Explorer](https://developers.facebook.com/tools/explorer/)
- [Facebook Business Settings](https://business.facebook.com/settings)
- [Facebook Ads Manager](https://business.facebook.com/adsmanager)
- [Access Token Debugger](https://developers.facebook.com/tools/debug/accesstoken/)

---

## Поддержка

При возникновении проблем с получением или использованием учетных данных:

1. Проверьте документацию Facebook Marketing API
2. Используйте [Access Token Debugger](https://developers.facebook.com/tools/debug/accesstoken/) для проверки токена
3. Убедитесь, что все разрешения запрошены и одобрены
4. Проверьте, что рекламный аккаунт активен и имеет необходимые права