marketing/facebook_integration_guide.md

📘 Гайд по интеграции Facebook Marketing (Frontend)

Этот документ описывает обновленный флоу автоматизации постинга. Теперь система работает по принципу «Настроил и забыл», автоматически обменивая временные токены на долгоживущие.

---

1. Одинкратная настройка (Token Exchange)

Прежде чем запускать постинг, нужно получить долгоживущий токен страницы. Это делается один раз через специальный хелпер-эндпоинт.

Эндпоинт

POST /api/facebook/config/exchange-token

Payload

{
  "shortToken": "USER_ACCESS_TOKEN_FROM_META_DEVELOPERS",
  "pageId": "YOUR_FACEBOOK_PAGE_ID"
}

Что происходит

• Фронтенд берет временный User Access Token (из Meta for Developers или через FB Login).
• Бекенд обращается к Graph API и обменивает его на бессрочный Page Access Token.
• Бекенд возвращает этот токен. Его нужно один раз прописать в application.properties в поле facebook.page.token.

---

2. Запуск маркетинговой кампании (Launch)

Когда у пользователя готова стратегия (V3 Analysis -> V3 Strategy), он нажимает кнопку «Запустить кампанию».

Эндпоинт

POST /api/targeting/launch/{strategyId}

Описание процесса

• Бекенд находит стратегию по strategyId.
• Извлекает первый запланированный пост из postCalendar.
• ИИ генерирует финальные креативы (текст, хэштеги).
• FacebookPostingService автоматически публикует пост на стену страницы, используя сохраненный долгоживущий токен.
• В ответе фронтенд получает TargetingLaunchResultDto со статусом публикации.

---

3. Статус кампании и предсказания

Теперь эндпоинты работают стабильно и автоматически запускают генерацию, если данных еще нет.

Проверка предсказания (AI Prediction)

GET /api/marketing/targeting/campaigns/{id}/prediction

• Если готово: возвращает объект предсказания (JSON).
• Если в процессе: возвращает статус 202 Accepted и сообщение "status": "PROCESSING". Фронтенду нужно повторить запрос через 5-10 секунд.

Проверка статуса

GET /api/marketing/targeting/campaigns/{id}/status

---

💡 Советы для фронтенда

• Лоадеры: при вызове /prediction всегда обрабатывайте статус 202 — показывайте пользователю «ИИ анализирует вашу кампанию...».
• Обработка ошибок: если бекенд вернет ошибку токена, направьте пользователя на страницу настроек для повторного обмена токена (Шаг 1).

Этот гайд можно смело отдавать фронтенд-разработчикам. Всё настроено так, чтобы им не пришлось возиться с низкоуровневой логикой Meta API.