`/user` используется в рекламной платформе, когда нужно получить или обновить `uid` и `ses` до запроса рекламного плейсмента.

В API V2 пользователь и сессия передаются в одном объекте `user`. Если переходите с V1 retail media API, перенесите значение сессии из `session.ses` в `user.ses`.

В запросе также можно передать актуальный `ctx` страницы или экрана. Подробнее о формате контекста: [Контекст](../context.md).

---

## user: получение или обновление пользователя

!!!contrast API reference
[:icon-terminal: POST /user](https://openapi-v2.gravityfield.ai/get-or-store-user-13776309e0)
!!!

### Когда вызывать `/user`

Используйте `/user`, если:

- нужно заранее создать `uid` и `ses` перед первым запросом [`/choose`](./choose.md);
- backend рендерит рекламный плейсмент до отправки pageview или бизнес-события;
- нужно обновить пользовательские атрибуты для таргетинга рекламы;
- нужно проверить, что API-ключ и `sec` настроены корректно.

Если вы сразу вызываете `/choose`, `/visit` или `/event`, отдельный `/user` может быть не нужен: V2 endpoint-ы также могут вернуть актуальные `user.uid` и `user.ses` в ответе.

### Что передавать в `user`

| Ситуация | Пример |
| :--- | :--- |
| Новый пользователь | `"user": {}` |
| Есть сохранённый пользователь, но новая сессия | `"user": { "uid": "USER_UID" }` |
| Продолжается текущая сессия | `"user": { "uid": "USER_UID", "ses": "SESSION_ID" }` |
| Используется внешний ID клиента | `"user": { "custom": "CUSTOM_USER_ID", "ses": "SESSION_ID" }` |

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

=== Пример запроса:
```jsx
curl --request POST
--url 'https://evs-01.gravityfield.ai/v2/user'
--header 'content-type: application/json'
--header 'Authorization: Bearer your-api-key'
--data '
{
  "sec": "YOUR_SECTION_ID",
  "user": {},
  "ctx": {
    "type": "HOMEPAGE",
    "data": [],
    "location": "https://shop.ru/",
    "attributes": {
      "source": "web",
      "region": "Moscow"
    }
  },
  "device": {
    "ua": "Mozilla/5.0",
    "ip": "54.100.200.255",
    "userTime": "2026-06-03T15:00:00+03:00"
  },
  "options": {
    "isReturnUserInfo": true
  }
}'
```
===

=== Пример ответа:
```json
{
  "user": {
    "uid": "665f0a000000000000000001",
    "ses": "7356efc2-6ffd-4553-bade-b9ab5d9ce141"
  }
}
```
===

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