## Коллекция запросов

У API-документации есть [коллекция запросов с примерами](https://openapi-v2.gravityfield.ai/).

Один и тот же API V2 Gateway используется для сценариев персонализации Gravity Field и рекламной платформы Gravity Ads. Различие обычно не в базовом URL, а в сценарии запроса: персонализация чаще использует `selector` или `campaignId`, рекламная платформа - `placementId`.

---

## Базовый URL

Используйте базовый URL:

```text
https://evs-01.gravityfield.ai/v2
```

Все endpoint-ы V2 вызываются без префикса `/ssapi`:

```text
POST https://evs-01.gravityfield.ai/v2/visit
POST https://evs-01.gravityfield.ai/v2/event
POST https://evs-01.gravityfield.ai/v2/choose
```

## Авторизация

API V2 использует bearer authentication. Передавайте API-ключ в заголовке `Authorization`:

```bash
--header 'Authorization: Bearer YOUR_API_KEY'
```

API-ключ создаётся в аккаунте Gravity Field. Подробнее: [Управление API-ключами](../manage_api_keys.md).

---

## `sec`: идентификатор секции

В каждом основном POST-запросе передавайте `sec` - идентификатор секции Gravity Field.

```json
{
  "sec": "YOUR_SECTION_ID"
}
```

Если API-ключ не относится к указанной секции, API вернёт ошибку авторизации.

---

## Идентификация пользователя

В V2 пользователь и сессия передаются в объекте `user`:

```json
{
  "user": {
    "uid": "USER_UID",
    "ses": "SESSION_ID"
  }
}
```

Правила хранения:

- `uid` храните между сессиями пользователя;
- `ses` храните для текущей сессии приложения или сайта;
- после ответов `/user`, `/visit`, `/event` и `/choose` обновляйте локально значения `user.uid` и `user.ses`, если они пришли в ответе.

Если пользователь новый, первый запрос можно отправить без `uid` и `ses`. Gateway создаст пользователя и вернёт актуальные идентификаторы в ответе.

Если у вас есть собственный внешний идентификатор пользователя, передавайте его в `user.custom`. Для `user.custom` нужно также передавать `user.ses`.

### Когда передавать `uid` и `ses`

| Ситуация | Что передавать |
| :--- | :--- |
| Новый пользователь | Можно передать пустой `user` или не передавать `uid`/`ses`. |
| Пользователь уже был на сайте или в приложении | Передайте сохранённый `uid`. |
| Продолжается та же сессия | Передайте сохранённый `uid` и текущий `ses`. |
| Началась новая app/browser session | Передайте `uid`, а `ses` можно не передавать, чтобы API выдал новую сессию. |
| Используется внешний ID клиента | Передайте `user.custom` и `user.ses`. |

`uid` нужен для непрерывности истории пользователя. `ses` нужен для группировки действий внутри текущей сессии. В мобильных приложениях обычно `uid` хранится в persistent storage, а `ses` - только в памяти текущего запуска приложения.

### Когда `uid` и `ses` возвращаются в ответе

API может вернуть объект `user` в ответах `/user`, `/visit`, `/event` и `/choose`.

Обычно `user.uid` и `user.ses` возвращаются, когда:

- пользователь новый и API создал для него идентификаторы;
- запрос пришёл с `uid`, но без `ses`, и API создал новую сессию;
- API обновил состояние пользователя или сессии;
- endpoint возвращает `user` вместе с `campaigns[]` или `data[]`.

Если в ответе нет `user`, `uid` или `ses`, это не означает ошибку. Оставьте локально сохранённые значения без изменений и используйте их в следующих запросах.

Правило обновления простое:

```js
if (response.user?.uid) {
  saveUid(response.user.uid);
}

if (response.user?.ses) {
  saveSession(response.user.ses);
}
```

Подробные примеры первого запроса: [`POST /user` для персонализации](./personalization/user.md) и [`POST /user` для рекламной платформы](./retail_media/user.md).

---

## Общий контекст

В V2 контекст страницы, экрана или текущих условий запроса передаётся в `ctx`:

```json
{
  "ctx": {
    "type": "PRODUCT",
    "data": ["sku-123"],
    "location": "https://example.com/product/sku-123"
  }
}
```

`ctx` используется для таргетинга, активации кампаний, рекомендаций, рекламы и аналитики. Поддерживаемые типы: `HOMEPAGE`, `SEARCH`, `PRODUCT`, `CATEGORY`, `CART`, `OTHER`.

Подробно о структуре `ctx`, формате `ctx.data` для каждого типа контекста и правилах качества данных: [Контекст](./context.md).

---

## Device

В каждом основном POST-запросе передавайте объект `device`. Минимально полезный набор:

```json
{
  "device": {
    "ua": "Mozilla/5.0 ...",
    "ip": "192.168.0.1",
    "userTime": "2026-06-03T15:00:00+03:00"
  }
}
```

Для мобильных приложений также можно передавать `device.id`, tracking status и permission status, если эти данные доступны.

---

## Опции

В `options` можно запросить дополнительные данные или изменить поведение endpoint-а:

| Опция | Где используется | Назначение |
| :--- | :--- | :--- |
| `isReturnCounter` | `/user`, `/visit`, `/event`, `/choose` | Вернуть сегменты и условия пользователя. |
| `isReturnUserInfo` | `/user`, `/visit`, `/event`, `/choose` | Вернуть расширенную информацию о пользователе. |
| `isReturnAnalyticsMetadata` | `/choose` | Вернуть дополнительные аналитические метаданные. |
| `isBuildEngagementUrl` | `/choose` | Сгенерировать tracking URL в `content.events[].urls[]` и `products.slots[].events[].urls[]`. |
| `isImplicitPageview` | `/choose` | Учесть pageview вместе с запросом контента. |
| `isImplicitImpression` | `/choose` | Учесть impression вместе с запросом рекламы для поддерживаемых рекламных плейсментов. |

Для manual rendering обычно включают `isBuildEngagementUrl: true`, чтобы не собирать engagement-запросы вручную. Подробнее: [взаимодействия с кампаниями персонализации](./personalization/engagement.md) и [взаимодействия с рекламой](./retail_media/engagement.md).