Карта API-маршрутов

Паспорт документа

• Статус документа: living document
• Актуально на: 2 апреля 2026 года
• Владелец: backend/platform-команда
• Пересмотр: при изменении endpoint'ов, auth-flow или API-контракта
• Область применения: обзорная карта живого backend API и точек входа OpenAPI/Swagger
• Связанные документы:
  • Памятка для frontend-команды
  • Change Log для frontend-команды
  • Платформенный implementation status

Base prefix: /api/v1/

---

Авторизация и токены

Web-клиент использует httpOnly cookies. Дополнительно JwtAuthGuard умеет читать Bearer token из Authorization header, что используется для non-web клиентов и служебных сценариев.

JwtAuthGuard применён глобально (APP_GUARD). Сначала читает Bearer token из Authorization, если его нет — fallback на cookie qadam_at. Затем проверяет подпись и tokenType === 'access'. Маршруты с @Public() пропускают проверку.

Роли проверяются в контроллерах через assertSeller(user) / assertBuyer(user) и аналогичные проверки по типу пользователя, без отдельного role-guard слоя. При несоответствии бросается ForbiddenException.

Ротация токена: POST /auth/refresh читает qadam_rt из cookie или refreshToken из body, верифицирует его, проверяет jti, генерирует оба новых токена и для web-клиента заново устанавливает cookies.

qadam_rt теперь intentionally доступна всему web runtime по path=/, чтобы server-side proxy и server components могли читать refresh cookie при полной перезагрузке страницы. При выдаче новой пары токенов backend дополнительно чистит legacy qadam_rt с path=/api/v1/auth, чтобы не оставлять дублирующую refresh-cookie после миграции.

---

OpenAPI и Swagger

Backend теперь публикует машиночитаемый и человекочитаемый API-контур:

Именно OpenAPI JSON должен использоваться как источник истины для frontend codegen, contract review и дальнейшего выноса frontend в отдельный репозиторий. docs/architecture/api-routes.md остаётся обзорной картой маршрутов, но не заменяет машиночитаемый контракт.

Дополнительно в репозитории зафиксирован versioned artifact:

• apps/api/openapi/openapi.json — канонический snapshot контракта для CI и frontend codegen;
• apps/web/src/shared/api/generated/openapi.d.ts — generated TypeScript contract для web;
• pnpm sync:api-contract — обновить artifact и generated types;
• pnpm check:api-contract — проверить drift между backend-кодом, artifact и generated types.

---

Health

GET /metrics публикуется в OpenAPI как часть system API, но runtime сознательно режет его на 403, если запрос пришёл не с loopback-адреса сервера. Это инженерный endpoint для локального scrape и operational диагностики, а не публичный маршрут для браузера.

---

Auth

---

Buyer (роль: BUYER)

Review flow больше не подразумевает немедленную публикацию: новые отзывы создаются в PENDING, GET /me/reviews публикует status и moderationNote, а публичные страницы и агрегаты учитывают только PUBLISHED.

---

Seller (роль: SELLER)

Для PATCH /seller/profile backend возвращает специфичные PHONE_TAKEN и EMAIL_TAKEN, если contact phone/email конфликтуют с другим аккаунтом. GET /seller/telegram/connect-link отдаёт готовый deep link с коротким signed token; frontend больше не должен собирать bot URL вручную. POST /seller/telegram/verify и DELETE /seller/telegram возвращают { success, username }, где username может быть null.

Seller item status-модель теперь включает DRAFT, PENDING, ACTIVE, REJECTED. GET /seller/items и GET /seller/items/:id дополнительно публикуют latestModerationRecord, чтобы frontend мог показать последнюю seller-visible причину/комментарий модерации. PUT /seller/items/:id больше не разрешён для PENDING айтемов: seller должен сначала вызвать POST /seller/items/:id/withdraw.

Seller review surface теперь публикуется отдельно: GET /seller/reviews отдаёт список отзывов по айтемам продавца со статусом, sellerReply, sellerReplyAt, canReply, canEditReply и activeComplaint. POST /seller/reviews/:id/complaint доступен только для PUBLISHED-отзывов, переводит отзыв в PENDING_MODERATION и временно убирает его из public aggregates, а PATCH /seller/reviews/:id/reply разрешён только в течение 48 часов после последнего ответа продавца.

Seller notification baseline теперь публикует GET/PATCH /seller/notification-settings с полями notifyNewLeadTelegram, notifyNewLeadEmail, notifyStatusChangeTelegram, telegramConnected, telegramUsername, sellerEmail. После создания лида LeadService сначала пытается Telegram-доставку продавцу, а при её отказе/невозможности и включённом notifyNewLeadEmail переходит на SMTP-capable email fallback; если SMTP не настроен на конкретном окружении, backend фиксирует SKIPPED, но не ломает создание лида. sellerEmail теперь резолвится из seller profile email с fallback на account email. Для owner-facing status-change notifications notifyStatusChangeTelegram больше не является пустым флагом: если статус меняет активный SELLER_STAFF, backend шлёт owner-уведомление по выбранным статусам из SELLER_STATUS_CHANGE_NOTIFY_STATUSES и при недоступном Telegram так же переходит на email fallback.

---

Catalog (Public)

---

GET /sellers/:id теперь публикует не только витринные поля seller и список опубликованных айтемов, но и явный seo block (title, description, canonicalUrl, openGraph, jsonLd) для SSR/metadata слоя. Профиль отдаётся только для ACTIVE seller-аккаунтов; несуществующий или непубличный seller должен давать 404.

---

Admin (роль: ADMIN)

---

GET /admin/sellers принимает фильтры search, status, sellerType, page, limit и возвращает seller summary с displayName, accountStatus, contact fields и item counters (totalItems, pendingItems, activeItems), чтобы admin мог работать со статусами без ручного знания sellerId.

После PATCH /admin/sellers/:sellerId/status seller-facing защищённые маршруты больше не маскируют статус аккаунта под generic token error: backend отдаёт явные 403 ACCOUNT_UNDER_REVIEW или 403 ACCOUNT_BLOCKED, если seller пытается идти в защищённый контур со старым access token.

Review moderation теперь живёт на отдельном backend-срезе: ReviewStatus включает PENDING, PUBLISHED, REJECTED, PENDING_MODERATION; admin принимает решение через PATCH /admin/moderation/reviews/:id, catalog/public seller aggregates считают только PUBLISHED, а seller complaint flow переводит спорный отзыв обратно в PENDING_MODERATION.

---

Uploads

Текущий production уже переведён на S3-compatible storage DigitalOcean Spaces, поэтому новые upload'ы обычно возвращают абсолютный публичный URL. Локальный /uploads/images/<fileName> остаётся compatibility/fallback-вариантом для OBJECT_STORAGE_DRIVER=local и старых локальных файлов. Canonical transport contract для upload endpoint остаётся тем же: { url: string }, где url является готовым публичным URL.

---

Tracking

Admin moderation endpoints теперь принимают решение только по PENDING айтемам. Если айтем уже ушёл в ACTIVE или REJECTED, backend возвращает конфликт статуса, а GET /admin/moderation/items/:id публикует latestModerationRecord и moderationHistory.