codeword/docs/openapi.yaml

openapi: 3.0.0
info:
  title: Codeword Recovery Service API
  version: 1.0.0
  description: API для обработки восстановления паролей для сервиса Codeword.

tags:
  - name: recover
    description: Операции связанные с восстановлением пароля
  - name: promocode
    description: Операции связанные с промокодами
  - name: stats
    description: Операции связанные со статистикой

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

  /readiness:
    get:
      operationId: Readiness
      summary: Роут проверки баз данных
      tags:
        - recover
      responses:
        '200':
          description: Успех — сервис готов и соединение с БД живо
        '503':
          description: Служба недоступна — не удалось выполнить проверку связи с БД
  /recover:
    post:
      operationId: Recovery
      summary: Восстановления пароля
      tags:
        - recover
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecoveryReq'
      responses:
        '200':
          description: Запрос на восстановление принят
        '404':
          description: Пользователь не найден по электронной почте
        '500':
          description: Внутренняя ошибка сервера

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

  /promocode/create:
    post:
      operationId: CreatePromoCode
      summary: Создать новый промокод
      tags:
        - promocode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromoCodeReq'
      responses:
        '200':
          description: Новый промокод успешно создан
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoCode'
        '400':
          description: Неверный формат запроса или дублирующийся codeword
        '500':
          description: Внутренняя ошибка сервера
  /promocode/edit:
    put:
      operationId: EditPromoCode
      summary: Обновить существующий промокод
      tags:
        - promocode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditPromoCodeReq'
      responses:
        '200':
          description: Промокод успешно обновлен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoCode'
        '400':
          description: Неверный формат запроса
        '404':
          description: Промокод не найден
        '500':
          description: Внутренняя ошибка сервера

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

  /promocode/activate:
    post:
      operationId: Activate
      summary: Активировать промокод
      tags:
        - promocode
      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 или fastLink
        '404':
          description: Промокод не найден
        '500':
          description: Внутренняя ошибка сервера

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

  /promocode/fastlink:
    post:
      operationId: CreateFastLink
      summary: Создать быструю ссылку для промокода
      tags:
        - promocode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFastLinkReq'
      responses:
        '200':
          description: Быстрая ссылка для промокода успешно создана
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateFastLinkResp'
        '400':
          description: Неверный запрос, отсутствует идентификатор промокода
        '404':
          description: Промокод не найден
        '500':
          description: Внутренняя ошибка сервера

  /promocode/stats:
    post:
      operationId: GetStats
      summary: Получить статистику промокода
      tags:
        - stats
      description: Идентификатор промокода и временной интерфал от до unix
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromoCodeStatsReq'
      responses:
        '200':
          description: Статистика промокода успешно получена
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoCodeStatsResp'
        '400':
          description: Неверный запрос
        '500':
          description: Внутренняя ошибка сервера


components:
  schemas:
    RecoveryReq:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: Электронная почта, на которую нужно отправить инструкции по восстановлению
        redirectionURL:
          type: string
          description: URL-адрес, на который перенаправляется пользователь
    PromoCodeStatsReq:
      type: object
      properties:
        id:
          type: string
        from:
          type: integer
        to:
          type: integer
      required:
        - id
    PromoCodeStatsResp:
      type: object
      properties:
        id:
          type: string
          description: id промокода
        usageCount:
          type: integer
          description: общее количество использований промокода
          example: 18
        usageMap:
          type: object
          description: мапа использования промокода ранжированая по способу
          additionalProperties:
            type: integer
          example:
            "-": 10
            "fastlinkID1": 5
            "fastlinkID2": 3


    CreateFastLinkReq:
      type: object
      properties:
        id:
          type: string
          description: ID промокода, для которого нужно создать быструю ссылку
      required:
        - id

    CreateFastLinkResp:
      type: object
      properties:
        fastlink:
          type: string
          description: Быстрая ссылка для активации промокода

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

    ActivateResp:
      type: object
      properties:
        greetings:
          type: string
          description: Слово успешной активации промокода

    GetPromoCodesListReq:
      type: object
      required:
        - page
        - limit
      properties:
        page:
          type: integer
          description: Номер страницы
        limit:
          type: integer
          description: Максимальное количество элементов на странице
        filter:
          $ref: '#/components/schemas/Filter'

    Filter:
      type: object
      properties:
        text:
          type: string
          description: Текстовый фильтр для поиска промокодов
        active:
          type: boolean
          description: Флаг для фильтрации активных промокодов

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

    PromoCode:
      type: object
      properties:
        id:
          type: string
          description: Идентификатор промокода
        codeword:
          type: string
          description: Кодовое слово для активации промокода
        description:
          type: string
          description: Описание промокода
        greetings:
          type: string
          description: Приветственное сообщение после активации промокода
        dueTo:
          type: integer
          description: Дата истечения действия промокода в формате Unix time
        activationCount:
          type: integer
          description: Количество активаций промокода
        bonus:
          type: object
          description: Бонус, предоставляемый с промокодом
          items:
            $ref: '#/components/schemas/Bonus'
        outdated:
          type: boolean
          description: Флаг
        offLimit:
          type: boolean
          description: Флаг
        delete:
          type: boolean
          description: Флаг
        createdAt:
          type: string
          format: date-time
          description: Дата и время создания промокода
        fastLinks:
          type: array
          items:
            type: string
          description: Список быстрых ссылок для активации промокода

    EditPromoCodeReq:
      type: object
      properties:
        ID:
          type: string
          description: Идентификатор промокода, который требуется обновить
        Description:
          type: string
          nullable: true
          description: Описание промокода
        Greetings:
          type: string
          nullable: true
          description:  Приветственное сообщение после активации промокода
        DueTo:
          type: integer
          nullable: true
          description: Дата окончания промокода в формате Unix time
        ActivationCount:
          type: integer
          nullable: true
          description: Количество активаций промокода
        ActivationLimit:
          type: integer
          description: Лимит, есть или нет если 0 то нет
        Delete:
          type: boolean
          nullable: true
          description: Флаг удаления промокода
    PromoCodeReq:
      type: object
      properties:
        codeword:
          type: string
          description: Кодовое слово для активации промокода
        description:
          type: string
          description: Описание промокода
        greetings:
          type: string
          description: Приветственное сообщение после активации промокода
        dueTo:
          type: integer
          description: Дата истечения действия промокода в формате Unix time
        activationCount:
          type: integer
          description: Количество активаций промокода
        activationLimit:
          type: integer
          description: Лимит, есть или нет если 0 то нет
        bonus:
          type: object
          description: Бонус
          items:
            $ref: '#/components/schemas/Bonus'
        fastLinks:
          type: array
          items:
            type: string
          description: Список быстрых ссылок для активации промокода

    Bonus:
      type: object
      description: Бонус
      properties:
        privilege:
          $ref: '#/components/schemas/Privilege'
        discount:
          $ref: '#/components/schemas/Discount'

    Privilege:
      type: object
      description: Привилегия
      properties:
        privilegeID:
          type: string
          description: Идентификатор привилегии
        amount:
          type: integer
          description: Количество привилегии
        serviceKey:
          type: string
          description: Тип сервиса

    Discount:
      type: object
      description: Скидка
      properties:
        layer:
          type: integer
          description: Уровень скидки
        factor:
          type: integer
          description: Множитель скидки
        target:
          type: string
          description: Цель скидки
        threshold:
          type: integer
          description: Порог скидки