# API для разработчиков: параметры пользователя

Документ описывает операции для записи и чтения пользовательских параметров.

Текущие операции:

- `UpsertUserParam`
- `GetUserParam`
- `ListUserParams`

## 1. `UpsertUserParam`

### Запрос

```json
{
  "op": "UpsertUserParam",
  "requestId": "param-upsert-001",
  "payload": {
    "login": "alice",
    "param": "display_name",
    "time_ms": 1774700000123,
    "value": "Alice",
    "device_key": "BASE64_DEVICE_PUBLIC_KEY",
    "signature": "BASE64_SIGNATURE"
  }
}
```

### Успешный ответ

```json
{
  "op": "UpsertUserParam",
  "requestId": "param-upsert-001",
  "status": 200,
  "ok": true,
  "payload": {
  }
}
```

### Типовые ошибки

- `400 / BAD_FIELDS` — некорректные обязательные поля.
- `422 / BAD_SIGNATURE` — подпись не прошла проверку.
- `501 / DB_ERROR` — ошибка БД.

---

## 2. `GetUserParam`

### Запрос

```json
{
  "op": "GetUserParam",
  "requestId": "param-get-001",
  "payload": {
    "login": "alice",
    "param": "display_name"
  }
}
```

### Успешный ответ

```json
{
  "op": "GetUserParam",
  "requestId": "param-get-001",
  "status": 200,
  "ok": true,
  "payload": {
    "login": "alice",
    "param": "display_name",
    "time_ms": 1774700000123,
    "value": "Alice",
    "device_key": "BASE64_DEVICE_PUBLIC_KEY",
    "signature": "BASE64_SIGNATURE"
  }
}
```

Если параметр не найден, сервер возвращает `404` с пустым `payload`; отдельный прикладной код ошибки текущий handler не задаёт.

---

## 3. `ListUserParams`

### Запрос

```json
{
  "op": "ListUserParams",
  "requestId": "param-list-001",
  "payload": {
    "login": "alice"
  }
}
```

### Успешный ответ

```json
{
  "op": "ListUserParams",
  "requestId": "param-list-001",
  "status": 200,
  "ok": true,
  "payload": {
    "login": "alice",
    "params": [
      {
        "login": "alice",
        "param": "display_name",
        "time_ms": 1774700000123,
        "value": "Alice",
        "device_key": "BASE64_DEVICE_PUBLIC_KEY",
        "signature": "BASE64_SIGNATURE"
      }
    ]
  }
}
```

## Примечание

Имена JSON-полей `time_ms` и `device_key` сейчас соответствуют Java-модели ответа/запроса и должны передаваться именно в таком виде.