# Полная документация Backend API

> **Последнее обновление:** Февраль 2026
> **Фронтенд:** Angular 21 · Два бренда (Dexar + Novo)
> **Охватывает:** Каталог, Корзина, Оплата, Отзывы, Регионы, Авторизация, i18n, BackOffice

---

## Базовые URL

| Бренд  | Dev                              | Production                       |
|--------|----------------------------------|----------------------------------|
| Dexar  | `https://api.dexarmarket.ru:445` | `https://api.dexarmarket.ru:445` |
| Novo   | `https://api.novo.market:444`    | `https://api.novo.market:444`    |

---

## Глобальные HTTP-заголовки

Фронтенд **автоматически добавляет** два кастомных заголовка к **каждому API-запросу** через interceptor. Бэкенд должен читать эти заголовки и использовать для фильтрации/перевода ответов.

| Заголовок     | Пример значения | Описание                                                          |
|---------------|-----------------|-------------------------------------------------------------------|
| `X-Region`    | `moscow`        | ID региона, выбранного пользователем. **Отсутствует** = все регионы. |
| `X-Language`  | `ru`            | Активный язык интерфейса: `ru`, `en` или `hy`.                   |

### Поведение бэкенда

- **`X-Region`**: Если присутствует — фильтровать товары/категории только по этому региону. Если отсутствует — возвращать всё (глобальный каталог).
- **`X-Language`**: Если присутствует — возвращать переведённые `name`, `description` и т.д., если переводы существуют. Если отсутствует или `ru` — возвращать на русском (по умолчанию).

### Требования CORS для этих заголовков

```
Access-Control-Allow-Headers: Content-Type, X-Region, X-Language
```

---

## 1. Проверка состояния

### `GET /ping`

Простая проверка работоспособности.

**Ответ `200`:**
```json
{ "message": "pong" }
```

---

## 2. Каталог — Категории

### `GET /category`

Возвращает все категории верхнего уровня. Учитывает заголовки `X-Region` и `X-Language`.

**Ответ `200`:**
```json
[
  {
    "categoryID": 1,
    "name": "Электроника",
    "parentID": 0,
    "icon": "https://...",
    "wideBanner": "https://...",
    "itemCount": 42,
    "priority": 10,

    "id": "cat_abc123",
    "visible": true,
    "img": "https://...",
    "projectId": "proj_xyz",
    "subcategories": [
      {
        "id": "sub_001",
        "name": "Смартфоны",
        "visible": true,
        "priority": 5,
        "img": "https://...",
        "categoryId": "cat_abc123",
        "parentId": "cat_abc123",
        "itemCount": 20,
        "hasItems": true,
        "subcategories": []
      }
    ]
  }
]
```

**Объект Category:**

| Поле             | Тип           | Обязат. | Описание                                           |
|------------------|---------------|---------|-----------------------------------------------------|
| `categoryID`     | number        | да      | Числовой ID (legacy)                                |
| `name`           | string        | да      | Название категории (переведённое если `X-Language`) |
| `parentID`       | number        | да      | ID родительской категории (`0` = верхний уровень)   |
| `icon`           | string        | нет     | URL иконки категории                                |
| `wideBanner`     | string        | нет     | URL широкого баннера                                 |
| `itemCount`      | number        | нет     | Количество товаров в категории                       |
| `priority`       | number        | нет     | Приоритет сортировки (больше = выше)                 |
| `id`             | string        | нет     | Строковый ID из BackOffice                           |
| `visible`        | boolean       | нет     | Видима ли категория (по умолч. `true`)              |
| `img`            | string        | нет     | URL изображения из BackOffice (маппится на `icon`)  |
| `projectId`      | string        | нет     | Ссылка на проект в BackOffice                        |
| `subcategories`  | Subcategory[] | нет     | Вложенные подкатегории                               |

**Объект Subcategory:**

| Поле             | Тип           | Обязат. | Описание                        |
|------------------|---------------|---------|----------------------------------|
| `id`             | string        | да      | ID подкатегории                  |
| `name`           | string        | да      | Отображаемое название            |
| `visible`        | boolean       | нет     | Видима ли                        |
| `priority`       | number        | нет     | Приоритет сортировки             |
| `img`            | string        | нет     | URL изображения                  |
| `categoryId`     | string        | да      | ID родительской категории        |
| `parentId`       | string        | да      | ID прямого родителя              |
| `itemCount`      | number        | нет     | Количество товаров               |
| `hasItems`       | boolean       | нет     | Есть ли товары                   |
| `subcategories`  | Subcategory[] | нет     | Вложенные дочерние подкатегории  |

---

### `GET /category/:categoryID`

Возвращает товары определённой категории. Учитывает заголовки `X-Region` и `X-Language`.

**Query-параметры:**

| Параметр | Тип    | По умолч. | Описание              |
|----------|--------|-----------|-----------------------|
| `count`  | number | `50`      | Товаров на страницу   |
| `skip`   | number | `0`       | Смещение для пагинации |

**Ответ `200`:** Массив объектов [Item](#объект-item).

---

## 3. Товары

### `GET /item/:itemID`

Возвращает один товар. Учитывает заголовки `X-Region` и `X-Language`.

**Ответ `200`:** Один объект [Item](#объект-item).

---

### `GET /searchitems`

Полнотекстовый поиск по товарам. Учитывает заголовки `X-Region` и `X-Language`.

**Query-параметры:**

| Параметр | Тип    | По умолч. | Описание                      |
|----------|--------|-----------|-------------------------------|
| `search` | string | —         | Поисковый запрос (обязателен) |
| `count`  | number | `50`      | Товаров на страницу           |
| `skip`   | number | `0`       | Смещение для пагинации        |

**Ответ `200`:**
```json
{
  "items": [ /* объекты Item */ ],
  "total": 128,
  "count": 50,
  "skip": 0
}
```

---

### `GET /randomitems`

Возвращает случайные товары для карусели/рекомендаций. Учитывает заголовки `X-Region` и `X-Language`.

**Query-параметры:**

| Параметр   | Тип    | По умолч. | Описание                             |
|------------|--------|-----------|--------------------------------------|
| `count`    | number | `5`       | Количество товаров                   |
| `category` | number | —         | Ограничить данной категорией (опц.)  |

**Ответ `200`:** Массив объектов [Item](#объект-item).

---

### Объект Item

Бэкенд может возвращать товары в **любом** из двух форматов — legacy или BackOffice. Фронтенд нормализует оба варианта.

```json
{
  "categoryID": 1,
  "itemID": 123,
  "name": "iPhone 15 Pro",
  "photos": [{ "url": "https://..." }],
  "description": "Описание товара",
  "currency": "RUB",
  "price": 89990,
  "discount": 10,
  "remainings": "high",
  "rating": 4.5,
  "callbacks": [
    {
      "rating": 5,
      "content": "Отличный товар!",
      "userID": "user_123",
      "timestamp": "2026-02-01T12:00:00Z"
    }
  ],
  "questions": [
    {
      "question": "Есть ли гарантия?",
      "answer": "Да, 12 месяцев",
      "upvotes": 5,
      "downvotes": 0
    }
  ],

  "id": "item_abc123",
  "visible": true,
  "priority": 10,
  "imgs": ["https://img1.jpg", "https://img2.jpg"],
  "tags": ["new", "popular"],
  "badges": ["bestseller", "sale"],
  "simpleDescription": "Краткое описание",
  "descriptionFields": [
    { "key": "Процессор", "value": "A17 Pro" },
    { "key": "Память", "value": "256 GB" }
  ],
  "subcategoryId": "sub_001",
  "translations": {
    "en": {
      "name": "iPhone 15 Pro",
      "simpleDescription": "Short description",
      "description": [
        { "key": "Processor", "value": "A17 Pro" }
      ]
    },
    "hy": {
      "name": "iPhone 15 Pro",
      "simpleDescription": "Կարcheck check"
    }
  },
  "comments": [
    {
      "id": "cmt_001",
      "text": "Отличный товар!",
      "author": "user_123",
      "stars": 5,
      "createdAt": "2026-02-01T12:00:00Z"
    }
  ],
  "quantity": 50
}
```

**Все поля Item:**

| Поле                | Тип               | Обязат. | Описание                                                  |
|---------------------|-------------------|---------|-----------------------------------------------------------|
| `categoryID`        | number            | да      | Категория, к которой принадлежит товар                    |
| `itemID`            | number            | да      | Числовой ID товара (legacy)                               |
| `name`              | string            | да      | Название товара                                           |
| `photos`            | Photo[]           | нет     | Массив фотографий `[{ url }]` (legacy)                    |
| `description`       | string            | да      | Текстовое описание                                        |
| `currency`          | string            | да      | Код валюты (по умолч. `RUB`)                              |
| `price`             | number            | да      | Цена                                                      |
| `discount`          | number            | да      | Процент скидки (`0`–`100`)                                |
| `remainings`        | string            | нет     | Уровень остатка: `high`, `medium`, `low`, `out`           |
| `rating`            | number            | да      | Средний рейтинг (`0`–`5`)                                 |
| `callbacks`         | Review[]          | нет     | Отзывы (legacy формат)                                    |
| `questions`         | Question[]        | нет     | Вопросы и ответы                                          |
| `id`                | string            | нет     | Строковый ID из BackOffice                                |
| `visible`           | boolean           | нет     | Виден ли товар (по умолч. `true`)                         |
| `priority`          | number            | нет     | Приоритет сортировки (больше = выше)                      |
| `imgs`              | string[]          | нет     | URL картинок из BackOffice (маппится на `photos`)         |
| `tags`              | string[]          | нет     | Теги для фильтрации                                      |
| `badges`            | string[]          | нет     | Бейджи (`bestseller`, `sale` и т.д.)                      |
| `simpleDescription` | string            | нет     | Краткое текстовое описание                                |
| `descriptionFields` | DescriptionField[]| нет     | Структурированное описание `[{ key, value }]`             |
| `subcategoryId`     | string            | нет     | Ссылка на подкатегорию из BackOffice                      |
| `translations`      | Record            | нет     | Переводы по ключу языка (см. ниже)                        |
| `comments`          | Comment[]         | нет     | Комментарии в формате BackOffice                          |
| `quantity`          | number            | нет     | Числовое кол-во на складе (маппится на `remainings`)      |

**Вложенные типы:**

| Тип                | Поля                                                            |
|--------------------|-----------------------------------------------------------------|
| `Photo`            | `url: string`, `photo?: string`, `video?: string`, `type?: string` |
| `DescriptionField` | `key: string`, `value: string`                                  |
| `Comment`          | `id?: string`, `text: string`, `author?: string`, `stars?: number`, `createdAt?: string` |
| `Review`           | `rating?: number`, `content?: string`, `userID?: string`, `answer?: string`, `timestamp?: string` |
| `Question`         | `question: string`, `answer: string`, `upvotes: number`, `downvotes: number` |
| `ItemTranslation`  | `name?: string`, `simpleDescription?: string`, `description?: DescriptionField[]` |

---

## 4. Корзина

### `POST /cart` — Добавить товар в корзину

**Тело запроса:**
```json
{ "itemID": 123, "quantity": 1 }
```

**Ответ `200`:**
```json
{ "message": "Added to cart" }
```

---

### `PATCH /cart` — Обновить количество товара

**Тело запроса:**
```json
{ "itemID": 123, "quantity": 3 }
```

**Ответ `200`:**
```json
{ "message": "Updated" }
```

---

### `DELETE /cart` — Удалить товары из корзины

**Тело запроса:** Массив ID товаров
```json
[123, 456]
```

**Ответ `200`:**
```json
{ "message": "Removed" }
```

---

### `GET /cart` — Получить содержимое корзины

**Ответ `200`:** Массив объектов [Item](#объект-item) (каждый с полем `quantity`).

---

## 5. Оплата (СБП / QR)

### `POST /cart` — Создать платёж (СБП QR)

> Примечание: Тот же эндпоинт что и добавление в корзину, но с другой схемой тела запроса.

**Тело запроса:**
```json
{
  "amount": 89990,
  "currency": "RUB",
  "siteuserID": "tg_123456789",
  "siteorderID": "order_abc123",
  "redirectUrl": "",
  "telegramUsername": "john_doe",
  "items": [
    { "itemID": 123, "price": 89990, "name": "iPhone 15 Pro" }
  ]
}
```

**Ответ `200`:**
```json
{
  "qrId": "qr_abc123",
  "qrStatus": "CREATED",
  "qrExpirationDate": "2026-02-28T13:00:00Z",
  "payload": "https://qr.nspk.ru/...",
  "qrUrl": "https://qr.nspk.ru/..."
}
```

---

### `GET /qr/payment/:qrId` — Проверить статус оплаты

**Ответ `200`:**
```json
{
  "additionalInfo": "",
  "paymentPurpose": "Order #order_abc123",
  "amount": 89990,
  "code": "SUCCESS",
  "createDate": "2026-02-28T12:00:00Z",
  "currency": "RUB",
  "order": "order_abc123",
  "paymentStatus": "COMPLETED",
  "qrId": "qr_abc123",
  "transactionDate": "2026-02-28T12:01:00Z",
  "transactionId": 999,
  "qrExpirationDate": "2026-02-28T13:00:00Z",
  "phoneNumber": "+7XXXXXXXXXX"
}
```

| Значение `paymentStatus` | Значение                     |
|--------------------------|------------------------------|
| `CREATED`                | QR создан, не оплачен        |
| `WAITING`                | Оплата в процессе            |
| `COMPLETED`              | Оплата успешна               |
| `EXPIRED`                | QR-код истёк                 |
| `CANCELLED`              | Оплата отменена              |

---

### `POST /purchase-email` — Отправить email после оплаты

**Тело запроса:**
```json
{
  "email": "user@example.com",
  "telegramUserId": "123456789",
  "items": [
    { "itemID": 123, "name": "iPhone 15 Pro", "price": 89990, "currency": "RUB" }
  ]
}
```

**Ответ `200`:**
```json
{ "message": "Email sent" }
```

---

## 6. Отзывы / Комментарии

### `POST /comment` — Оставить отзыв

**Тело запроса:**
```json
{
  "itemID": 123,
  "rating": 5,
  "comment": "Отличный товар!",
  "username": "john_doe",
  "userId": 123456789,
  "timestamp": "2026-02-28T12:00:00Z"
}
```

**Ответ `200`:**
```json
{ "message": "Review submitted" }
```

---

## 7. Регионы

### `GET /regions` — Список доступных регионов

Возвращает регионы, в которых работает маркетплейс.

**Ответ `200`:**
```json
[
  {
    "id": "moscow",
    "city": "Москва",
    "country": "Россия",
    "countryCode": "RU",
    "timezone": "Europe/Moscow"
  },
  {
    "id": "spb",
    "city": "Санкт-Петербург",
    "country": "Россия",
    "countryCode": "RU",
    "timezone": "Europe/Moscow"
  },
  {
    "id": "yerevan",
    "city": "Ереван",
    "country": "Армения",
    "countryCode": "AM",
    "timezone": "Asia/Yerevan"
  }
]
```

**Объект Region:**

| Поле          | Тип    | Обязат. | Описание                        |
|---------------|--------|---------|----------------------------------|
| `id`          | string | да      | Уникальный идентификатор региона |
| `city`        | string | да      | Название города                  |
| `country`     | string | да      | Название страны                  |
| `countryCode` | string | да      | Код страны ISO 3166-1 alpha-2    |
| `timezone`    | string | нет     | Часовой пояс IANA                |

> **Фоллбэк:** Если эндпоинт недоступен, фронтенд использует 6 захардкоженных значений: Москва, СПб, Ереван, Минск, Алматы, Тбилиси.

---

## 8. Авторизация (вход через Telegram)

Авторизация **через Telegram** с **cookie-сессиями** (HttpOnly, Secure, SameSite=None).

Все auth-эндпоинты должны поддерживать CORS с `credentials: true`.

### Процесс авторизации

```
1. Пользователь нажимает «Оформить заказ» → не авторизован → показывается диалог входа
2. Нажимает «Войти через Telegram» → открывается https://t.me/{bot}?start=auth_{callback}
3. Пользователь запускает бота в Telegram
4. Бот отправляет данные пользователя → бэкенд /auth/telegram/callback
5. Бэкенд создаёт сессию → устанавливает Set-Cookie
6. Фронтенд опрашивает GET /auth/session каждые 3 секунды
7. Сессия обнаружена → диалог закрывается → оформление заказа продолжается
```

---

### `GET /auth/session` — Проверить текущую сессию

**Запрос:** Только cookie (сессионная cookie, установленная бэкендом).

**Ответ `200`** (авторизован):
```json
{
  "sessionId": "sess_abc123",
  "telegramUserId": 123456789,
  "username": "john_doe",
  "displayName": "John Doe",
  "active": true,
  "expiresAt": "2026-03-01T12:00:00Z"
}
```

**Ответ `200`** (сессия истекла):
```json
{
  "sessionId": "sess_abc123",
  "telegramUserId": 123456789,
  "username": "john_doe",
  "displayName": "John Doe",
  "active": false,
  "expiresAt": "2026-02-27T12:00:00Z"
}
```

**Ответ `401`** (нет сессии):
```json
{ "error": "No active session" }
```

**Объект AuthSession:**

| Поле             | Тип     | Обязат. | Описание                                  |
|------------------|---------|---------|-------------------------------------------|
| `sessionId`      | string  | да      | Уникальный ID сессии                      |
| `telegramUserId` | number  | да      | ID пользователя в Telegram                |
| `username`       | string? | нет     | @username в Telegram (может быть null)    |
| `displayName`    | string  | да      | Отображаемое имя (имя + фамилия)          |
| `active`         | boolean | да      | Действительна ли сессия                   |
| `expiresAt`      | string  | да      | Дата истечения в формате ISO 8601         |

---

### `GET /auth/telegram/callback` — Callback авторизации Telegram-бота

Вызывается Telegram-ботом после авторизации пользователя.

**Тело запроса (от бота):**
```json
{
  "id": 123456789,
  "first_name": "John",
  "last_name": "Doe",
  "username": "john_doe",
  "photo_url": "https://t.me/i/userpic/...",
  "auth_date": 1709100000,
  "hash": "abc123def456..."
}
```

**Ответ:** Должен установить cookie сессии и вернуть:
```json
{
  "sessionId": "sess_abc123",
  "message": "Authenticated successfully"
}
```

**Требования к cookie:**

| Атрибут    | Значение       | Примечание                                          |
|------------|----------------|-----------------------------------------------------|
| `HttpOnly` | `true`         | Недоступна из JavaScript                            |
| `Secure`   | `true`         | Только HTTPS                                       |
| `SameSite` | `None`         | Обязательно для cross-origin (API ≠ фронтенд)      |
| `Path`     | `/`            |                                                     |
| `Max-Age`  | `86400` (24ч)  | Или по необходимости                                |

---

### `POST /auth/logout` — Завершить сессию

**Запрос:** Только cookie, пустое тело `{}`

**Ответ `200`:**
```json
{ "message": "Logged out" }
```

Должен очистить/инвалидировать cookie сессии.

---

### Обновление сессии

Фронтенд повторно проверяет сессию за **60 секунд до `expiresAt`**. Если бэкенд поддерживает скользящий срок действия (sliding expiration), можно обновлять `Max-Age` cookie при каждом вызове `GET /auth/session`.

---

## 9. i18n / Переводы

Фронтенд поддерживает 3 языка: **Русский (ru)**, **Английский (en)**, **Армянский (hy)**.

Активный язык отправляется через HTTP-заголовок `X-Language` с каждым запросом.

### Что бэкенд должен делать с `X-Language`

1. **Категории и товары**: Если для запрошенного языка есть поле `translations`, вернуть переведённые `name`, `description` и т.д. ИЛИ бэкенд может применять переводы на стороне сервера и возвращать уже переведённые поля.

2. **Поле `translations`** на товарах (опциональный подход):
   ```json
   {
     "translations": {
       "en": {
         "name": "iPhone 15 Pro",
         "simpleDescription": "Short desc in English",
         "description": [{ "key": "Processor", "value": "A17 Pro" }]
       },
       "hy": {
         "name": "iPhone 15 Pro",
         "simpleDescription": "Կarcheck check"
       }
     }
   }
   ```

3. **Рекомендуемый подход**: Читать заголовок `X-Language` и возвращать `name`/`description` на этом языке напрямую. Если перевода нет — возвращать русский вариант по умолчанию.

---

## 10. Настройка CORS

Для работы auth-cookie и кастомных заголовков конфигурация CORS бэкенда должна включать:

```
Access-Control-Allow-Origin: https://dexarmarket.ru    (НЕ wildcard *)
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Content-Type, X-Region, X-Language
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS
```

> **Важно:** `Access-Control-Allow-Origin` не может быть `*` при `Allow-Credentials: true`. Должен быть точный origin фронтенда.

**Разрешённые origins:**
- `https://dexarmarket.ru`
- `https://novo.market`
- `http://localhost:4200` (dev)
- `http://localhost:4201` (dev, Novo)

---

## 11. Настройка Telegram-бота

Каждому бренду нужен свой бот:
- **Dexar:** `@dexarmarket_bot`
- **Novo:** `@novomarket_bot`

Бот должен:
1. Слушать команду `/start auth_{callbackUrl}`
2. Извлечь callback URL
3. Отправить данные пользователя (`id`, `first_name`, `username` и т.д.) на этот callback URL
4. Callback URL: `{apiUrl}/auth/telegram/callback`

---

## Полный справочник эндпоинтов

### Новые эндпоинты

| Метод  | Путь                      | Описание                        | Авторизация |
|--------|---------------------------|---------------------------------|-------------|
| `GET`  | `/regions`                | Список доступных регионов       | Нет         |
| `GET`  | `/auth/session`           | Проверка текущей сессии         | Cookie      |
| `GET`  | `/auth/telegram/callback` | Callback авторизации через бота | Нет (бот)   |
| `POST` | `/auth/logout`            | Завершение сессии               | Cookie      |

### Существующие эндпоинты

| Метод    | Путь                  | Описание                  | Авт. | Заголовки          |
|----------|-----------------------|---------------------------|------|--------------------|
| `GET`    | `/ping`               | Проверка состояния        | Нет  | —                  |
| `GET`    | `/category`           | Список категорий          | Нет  | X-Region, X-Language |
| `GET`    | `/category/:id`       | Товары категории          | Нет  | X-Region, X-Language |
| `GET`    | `/item/:id`           | Один товар                | Нет  | X-Region, X-Language |
| `GET`    | `/searchitems`        | Поиск товаров             | Нет  | X-Region, X-Language |
| `GET`    | `/randomitems`        | Случайные товары          | Нет  | X-Region, X-Language |
| `POST`   | `/cart`               | Добавить в корзину / Оплата | Нет* | —                |
| `PATCH`  | `/cart`               | Обновить кол-во           | Нет* | —                  |
| `DELETE` | `/cart`               | Удалить из корзины        | Нет* | —                  |
| `GET`    | `/cart`               | Содержимое корзины        | Нет* | —                  |
| `POST`   | `/comment`            | Оставить отзыв            | Нет  | —                  |
| `GET`    | `/qr/payment/:qrId`  | Статус оплаты             | Нет  | —                  |
| `POST`   | `/purchase-email`     | Отправить email после оплаты | Нет | —               |

> \* Эндпоинты корзины/оплаты могут использовать cookie сессии (если есть) для привязки к заказу, но не требуют авторизации строго. Фронтенд проверяет авторизацию перед оформлением заказа.