Документация REST API

1. Авторизация (JWT)

Защищённые методы требуют заголовок Authorization: Bearer <access_token> (именно префикс Bearer и пробел, затем токен).

• Получите OAuth-токен Яндекса (мобильное приложение или OAuth-кабинет для отладки).
• POST /api/auth/yandex с телом {"yandexToken":"…","deviceId":"…"} — без JWT. В ответе поля accessToken и refreshToken.
• Дальше передавайте accessToken в заголовке Authorization как указано выше.
• Продление: POST /api/auth/refresh с тем же deviceId, телом с refreshToken.

2. Спецификация OpenAPI (схемы и список операций)

Машиночитаемое описание всех путей, параметров и тел запросов в формате OpenAPI 3: /swagger/v1/swagger.json (удобно импортировать в Postman, Insomnia, codegen и т.п.). Доступно только в окружении Development.

В описании операций заданы теги вида Роль: … — по ним видно, для какой роли сессии метод предназначен. У одной операции может быть несколько тегов.

3. Маркетплейс

• GET /api/marketplace/posts — лента (без JWT).
• GET /api/marketplace/posts/{id} — один пост (без JWT).
• POST /api/marketplace/posts — создание поста (JWT, в сессии роль Seller). Тело JSON, например:

  {
    "title": "Заголовок",
    "description": "Текст",
    "photos": ["/api/files/content/…"],
    "priceInfo": "Цена и условия",
    "contacts": "Телефон или мессенджер"
  }

• GET /api/users/{userId}/organizer-rating — публичный «паспорт СП»: средний балл, число оценок, блокировка на создание закупок (без JWT).

4. Файлы и чат

• POST /api/files/upload — загрузка изображения (JWT), в ответе URL для поля photos поста.
• GET /api/files/content/{id} — выдача файла, без JWT (для ссылок в постах и тегов <img>).
• Чат в реальном времени: SignalR hub /hubs/chat — JWT в query-параметре access_token или в заголовке (см. настройки клиента SignalR).

5. Закупки

Группа /api/purchases — полные пути, тела и коды ответов в OpenAPI. Ниже — краткая шпаргалка по веб-панелям. Пользовательские сценарии — в справке.

Участник (Member)

• GET /api/purchases, GET /api/purchases/{id} — список и детали с позициями
• POST /api/purchases/{id}/join/{code} — вступить
• POST …/lines — новая строка списка; PUT …/lines/{id}/my-quantity — ваш объём
• GET / POST /api/purchases/{id}/messages — чат (REST; реал-тайм — см. § 4)
• POST /api/purchases/{id}/rate-organizer — оценка организатора после Completed (три критерия 1–5; не организатор; 14 дней с completed_at)

Организатор (Organizer)

• POST /api/purchases — создать закупку (description, deliveryAddress, deliveryCost — оценка доставки); при активной блокировке рейтинга — 403
• PATCH /api/purchases/{id} — описание и адрес раздачи
• POST /api/purchases/{id}/invite — новый код
• PATCH /api/purchases/{id}/status — статус
• PATCH /api/purchases/{id}/lines/{lineId} — estimatedPrice (₽/ед., только организатор)
• Остальные операции участника — как у Member

Закупщик (Buyer)

• PATCH /api/purchases/{id}/status — перевод статуса
• PATCH /api/purchases/{id}/lines/{lineId} — actualPrice (₽ за единицу), isBought

6. Талоны раздачи

Группа /api/purchases/{id}/tickets. Доступна в статусе закупки Distributing (Раздача).

• POST …/generate — сформировать / перегенерировать талоны (только Организатор). С параметром force=true аннулирует старые активные талоны.
• GET …/ — список талонов (Организатор или Закупщик).
• GET …/summary — сводка: всего / погашено / активно (Организатор или Закупщик).
• GET …/pdf?perPage=8 — PDF для печати (perPage = 4, 6 или 8; сетка 2×N на A4). Участник получает только свой талон, Организатор и Закупщик — все.
• GET …/my — актуальный талон текущего участника.
• GET …/redeem/by-barcode/{barcode} — проверить по штрихкоду без погашения (Организатор или Закупщик).
• POST …/redeem — погасить талон. Тело: {"barcode":"…"} (Организатор или Закупщик).
• POST …/{ticketId}/cancel — аннулировать талон до выдачи (только Организатор). Ответ 204.

7. Поддержка

Группа /api/support/tickets. Работает как анонимно, так и с JWT.

• POST /api/support/tickets — создать обращение. Тело: {"email":"…","message":"…"}. Без JWT — гостевое; с JWT — привязывается к аккаунту. Ответ: 201 {"id","publicNumber"} — публичный номер вида PP-A1B2C3.
• GET /api/support/tickets — мои обращения (JWT). Ответ: массив {"publicNumber","createdAt","hasStaffReply"}.
• GET /api/support/tickets/{publicNumber}/thread — переписка. Доступ: JWT владельца или query-параметр ?email= (гостевой доступ). Ответ: {"publicNumber","createdAt","messages[]"}.
• POST /api/support/tickets/{publicNumber}/messages — дополнить обращение. Тело: {"message":"…"}. Те же правила доступа, что у GET …/thread. Ответ 204.

8. Подписка

• POST /api/subscription/checkout — создать счёт на оплату подписки (JWT). Ответ: {"paymentUrl":"…"} — URL страницы оплаты Selfwork. После успешной оплаты Selfwork пришлёт вебхук и подписка активируется автоматически.
• POST /api/webhook/selfwork — вебхук оплаты (без JWT, служебный). Требует заголовок X-Webhook-Signature (HMAC-SHA256 от Selfwork). Обрабатывает статусы Paid и Cancelled.

9. Мониторинг

GET /health/live — проверка живости процесса (для балансировщиков и healthcheck в Docker).