codeword/docs/openapi.yaml

openapi: 3.0.0
info:
  title: Codeword Recovery Service API
  version: 1.0.0
  description: API for handling password recovery for the Codeword service.


paths:
  /liveness:
    get:
      summary: Роут проверки активности
      responses:
        '200':
          description: Успех – сервис запущен

  /readiness:
    get:
      summary: Роут проверки базы данных
      responses:
        '200':
          description: Успех — сервис готов и соединение с БД живо
        '503':
          description: Служба недоступна — не удалось выполнить проверку связи с БД

  /recover:
    post:
      summary: Запустите процесс восстановления пароля
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  description: Электронная почта, на которую нужно отправить инструкции по восстановлению
                Referrer:
                  type: string
                  description: URL-адрес referral, если он доступен
                RedirectionURL:
                  type: string
                  description: URL-адрес, на который перенаправляется пользователь после отправки электронного письма

      responses:
        '200':
          description: Запрос на восстановление принят, и возвращен идентификатор записи восстановления
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Идентификатор запроса на восстановление
        '404':
          description: Пользователь не найден по электронной почте
        '500':
          description: Внутренняя ошибка сервера – разные причины

  /recover/{sign}:
    get:
      summary: Обработать ссылку восстановления, в которой содержится подпись и обменять ее на токены
      parameters:
        - in: path
          name: sign
          required: true
          schema:
            type: string
          description: Подпись восстановления как часть URL-адреса восстановления
      responses:
        '200':
          description: Восстановление успешно, информация для обмена токенов возвращена
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessToken:
                    type: string
                  refreshToken:
                    type: string
        '406':
          description: NotAcceptable - срок действия ссылки для восстановления истек или она недействительна
        '500':
          description: Внутренняя ошибка сервера – разные причины

  /promocode/create:
    post:
      summary: Создать новый промокод
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromoCodeRequest'
      responses:
        '201':
          description: Новый промокод успешно создан
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoCodeResponse'
        '400':
          description: Invalid request payload / Duplicate Codeword
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '500':
          description: Внутренняя ошибка сервера
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string

  /promocode/edit:
    put:
      summary: Обновить существующий промокод
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReqEditPromoCode'
      responses:
        '200':
          description: Промокод успешно обновлен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoCodeResponse'
        '400':
          description: Неверный формат запроса
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '404':
          description: Промокод не найден
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '500':
          description: Внутренняя ошибка сервера
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string

  /promocode/getList:
    post:
      summary: Получить список промокодов
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetPromoCodesListReq'
      responses:
        '200':
          description: Список промокодов и общее количество успешно получены
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPromoCodesListResp'
        '400':
          description: Неверный запрос из-за невалидных данных
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '500':
          description: Внутренняя ошибка сервера

  /promocode/activate:
    post:
      summary: Активировать промокод
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivateReq'
      responses:
        '200':
          description: Промокод успешно активирован
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivateResp'
        '400':
          description: Невалидный запрос или отсутствует обязательное поле codeword
        '404':
          description: Промокод не найден
        '500':
          description: Внутренняя ошибка сервера

  /promocode/{promocodeID}:
    delete:
      summary: Мягко удалить промокод по его id
      parameters:
        - in: path
          name: promocodeID
          required: true
          schema:
            type: string
          description: Id промокода для удаления
      responses:
        '204':
          description: Промокод успешно помечен как удаленный
        '400':
          description: Неверный запрос, отсутствует идентификатор промокода
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '404':
          description: Промокод не найден
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '500':
          description: Внутренняя ошибка сервера
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string

  /promocode/fastlink:
    post:
      summary: Создать быструю ссылку для промокода
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: string
                  description: ID промокода, для которого нужно создать быструю ссылку
      responses:
        '201':
          description: Быстрая ссылка для промокода успешно создана
          content:
            application/json:
              schema:
                type: object
                properties:
                  fastlink:
                    type: string
                    description: Быстрая ссылка для активации промокода
        '400':
          description: Неверный запрос, отсутствует идентификатор промокода
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '404':
          description: Промокод не найден
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '500':
          description: Внутренняя ошибка сервера
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
  /promocode/stats:
    get:
      summary: Получить статистику промокода
      responses:
        '200':
          description: Статистика промокода успешно получена
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoCodeStats'
        '500':
          description: Внутренняя ошибка сервера
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string

components:
  schemas:
    PromoCodeRequest:
      type: object
      properties:
        codeword:
          type: string
          description: Кодовое слово, которое должен ввести пользователь
        description:
          type: string
          description: Описание, необходимое для администратора в панели управления
        greetings:
          type: string
          description: Текст, который будет отправлен пользователю в ответ на активацию кода
        dueTo:
          type: integer
          format: int64
          description: Временная метка окончания активации кода
        activationCount:
          type: integer
          format: int64
          description: Лимит активации кода
        bonus:
          type: object
          properties:
            privilege:
              type: object
              properties:
                privilegeID:
                  type: string
                  description: Идентификатор привилегии, которую необходимо предоставить
                amount:
                  type: integer
                  format: uint64
                  description: Размер привилегии
            discount:
              type: object
              properties:
                layer:
                  type: integer
                factor:
                  type: number
                target:
                  type: string
                threshold:
                  type: integer
          description: Информация о бонусах
        outdated:
          type: boolean
        offLimit:
          type: boolean
        delete:
          type: boolean

    PromoCodeResponse:
      type: object
      properties:
        id:
          type: string
          description: ID созданного промокода
        codeword:
          type: string
          description: Кодовое слово промокода
        description:
          type: string
          description: Описание промокода
        greetings:
          type: string
          description: Текст, который будет отправлен пользователю в ответ на активацию кода
        dueTo:
          type: integer
          format: int64
          description: Временная метка окончания активации кода
        activationCount:
          type: integer
          format: int64
          description: Лимит активации кода
        bonus:
          type: object
          properties:
            privilege:
              type: object
              properties:
                privilegeID:
                  type: string
                  description: Идентификатор привилегии, которую необходимо предоставить
                amount:
                  type: integer
                  format: uint64
                  description: Размер привилегии
            discount:
              type: object
              properties:
                layer:
                  type: integer
                factor:
                  type: number
                target:
                  type: string
                threshold:
                  type: integer
          description: Информация о бонусах
        outdated:
          type: boolean
        offLimit:
          type: boolean
        delete:
          type: boolean
        createdAt:
          type: string
          format: date-time
          description: Время создания промокода

    ReqEditPromoCode:
      type: object
      properties:
        id:
          type: string
          description: ID промокода, который обновляем
        description:
          type: string
          description: Описание, необходимое менеджеру в админке
        greetings:
          type: string
          description: Текст, выдаваемый пользователю в ответ на активацию промокода
        dueTo:
          type: integer
          format: int64
          description: Временная метка окончания активации кода
        activationCount:
          type: integer
          format: int64
          description: Предел количества активаций промокода
        delete:
          type: boolean
          description: Флаг удаления промокода
      required:
        - id
    GetPromoCodesListReq:
      type: object
      required:
        - page
        - limit
        - filter
      properties:
        page:
          type: integer
          description: Номер страницы выборки, начиная с 0
        limit:
          type: integer
          description: Размер страницы выборки
        filter:
          $ref: '#/components/schemas/GetPromoCodesListReqFilter'

    GetPromoCodesListReqFilter:
      type: object
      properties:
        text:
          type: string
          description: Полнотекстовый поиск по полям Codeword, Description, Greetings
        active:
          type: boolean
          description: Если true, выбираются записи, где delete, outdated и offLimit равны false

    GetPromoCodesListResp:
      type: object
      properties:
        count:
          type: integer
          format: int64
          description: Общее количество промокодов в выборке
        items:
          type: array
          items:
            $ref: '#/components/schemas/PromoCodeResponse'

    ActivateReq:
      type: object
      properties:
        codeword:
          type: string
          description: Кодовое слово промокода, которое требуется активировать
        fastLink:
          type: string
          description: Быстрая ссылка для активации промокода

    ActivateResp:
      type: object
      properties:
        greetings:
          type: string
          description: Поле из активированного промокода

    PromoCodeStats:
      type: object
      properties:
        id:
          type: string
          description: ID промокода
        usageCount:
          type: object
          description: Количество использований промокода для каждого пользователя
        usageHistory:
          type: object
          description: История использования промокода для каждого пользователя