`/user` используется, когда нужно получить или создать пользователя и сессию без отправки pageview или бизнес-события.

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

---

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

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

=== Пример запроса:
```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/"
  },
  "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`

`uid` - идентификатор пользователя в Gravity Field. Его нужно сохранять между сессиями, чтобы последующие просмотры, события и запросы кампаний относились к одному пользователю.

`ses` - идентификатор текущей сессии. Его можно хранить только на время текущего запуска приложения или текущей browser session.

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

`/user` полезен, если нужно заранее получить или обновить `uid` и `ses`, но не нужно отправлять pageview или бизнес-событие.

Типичные случаи:

- первый запуск приложения или первый server-side запрос;
- нужно создать новую сессию до вызова `/visit`, `/event` или `/choose`;
- нужно получить расширенную информацию о пользователе через `options.isReturnUserInfo`;
- нужно проверить, что API-ключ и `sec` настроены корректно.

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

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

Если передаёте `user.custom`, передавайте и `user.ses`. Не используйте `custom` как замену `cuid` для омниканальной склейки профиля: для этого используйте события `login-v1` или `signup-v1` с `cuid` и `cuidType`.

### Как обрабатывать ответ

Если ответ содержит `user.uid` или `user.ses`, обновите локальное хранилище:

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

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

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