# 🌐 API интеграция

Процесс интеграции включает несколько ключевых шагов. Убедитесь, что каждый из них выполнен:

---

## Версии API

В документации доступны два API-контура:

- **API V1** - текущие страницы этого раздела с endpoint-ами `/ssapi/*`. Используйте их для существующих интеграций и поддержки уже запущенных сценариев.
- **API V2** - новый Gateway API для server-side, web, mobile SDK и headless-сценариев. Он использует endpoints `/user`, `/visit`, `/event`, `/choose`, `/strategy` и `/engagement`.

📖 Подробнее: [API V2](./v2/index.md)

!!!contrast API reference
[:icon-terminal: OpenAPI V2](https://openapi-v2.gravityfield.ai/)
!!!

---

## Shopping Assistant

Shopping Assistant можно подключить по отдельному API-контуру, когда клиентское приложение само реализует UI/UX чата и напрямую вызывает `POST /shopping/generate`.

📖 Подробнее: [Интеграция Shopping Assistant по API](/shopping_assistant/integration.md)

---

## 🔑 Создание API-ключа

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

📖 Подробнее: [Управление API-ключами](./manage_api_keys.md)

---

## 📂 Передача продуктового фида

Передайте фид с информацией о продуктах и услугах, которые вы планируете использовать в товарных кампаниях.

Фид должен содержать:
- Названия товаров и услуг.  
- Описание.  
- URL, изображения, цены и другие характеристики.  

📖 Подробнее: [Требования к продуктовому фиду](../products_catalogues/general_reqs.md)

---

## Базовые методы

### 📜 Передача контекста страниц

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

📖 Подробнее: [Как настроить контекст страниц](./personalization/page_context.md)

### 🛒 Передача информации о действиях пользователей

Отслеживайте минимальный набор событий для e-commerce:
- **Добавление в корзину**.  
- **Покупка**.  

Эти события необходимы для:  
- Понимания поведения пользователей.  
- Оптимизации кампаний.  
- Корректного измерения эффективности.

📖 Подробнее: [Руководство по событиям](./personalization/events.md)

---

## Персонализация

### 🎯 Получение кампаний персонализации

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

📖 Подробнее: [Получение кампаний](./personalization/choose.md)

### 📊 Передача данных о взаимодействии пользователей

Фиксируйте ключевые действия пользователей:
- Просмотры виджетов.  
- Клики по товарам.  
- Прочие действия.  

Эти данные помогают анализировать поведение пользователей и оптимизировать персонализацию.

📖 Подробнее: [Передача данных о взаимодействии](./personalization/engagement.md)

---

## Retail Media

### 🎯 Получение рекламных кампаний

Запрашивайте рекламные кампании для плейсмента через API.

📖 Подробнее: [Получение кампаний](./retail_media/choose.md)

### 📊 Передача данных о взаимодействии пользователей c рекламой

Фиксируйте ключевые действия пользователей:
- Просмотры виджетов.  
- Клики по рекламе и клики по товарам.  
- Прочие действия.  

Эти данные помогают анализировать эффективность и оптимизировать кампании.

📖 Подробнее: [Передача данных о взаимодействии](./retail_media/engagement.md)