specs/openspec/changes/stock-screener/system-analysis/contracts/stock-screener.openapi.yaml

openapi: 3.0.3
info:
  title: WealthLedger stock screener target contract
  version: 1.0.0
  description: Целевой контракт change; исполняемый HTTP-контракт после реализации генерирует backend.
paths:
  /api/v1/stocks/screener/search:
    post:
      operationId: createStockScreenerSearch
      summary: Получить новый результат скринера по полному каталогу акций
      security:
        - bearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StockScreenerCriteria'
      responses:
        '200':
          description: Первая страница нового результата, включая подтверждённый пустой список
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockScreenerPage'
        '400':
          $ref: '#/components/responses/Problem'
        '401':
          $ref: '#/components/responses/Problem'
        '503':
          $ref: '#/components/responses/Problem'
  /api/v1/stocks/screener/search/{searchId}:
    get:
      operationId: readStockScreenerPage
      summary: Прочитать страницу того же зафиксированного результата
      security:
        - bearer: []
      parameters:
        - name: searchId
          in: path
          required: true
          schema:
            type: string
          description: Непрозрачный идентификатор результата; не является полномочием доступа.
        - name: page
          in: query
          required: true
          schema:
            type: integer
            minimum: 1
          description: Номер страницы с единицы. Условия поиска при чтении страницы не меняются.
      responses:
        '200':
          description: Страница зафиксированного результата с тем же временем получения каталога
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockScreenerPage'
        '400':
          $ref: '#/components/responses/Problem'
        '401':
          $ref: '#/components/responses/Problem'
        '404':
          $ref: '#/components/responses/Problem'
        '503':
          $ref: '#/components/responses/Problem'
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
  responses:
    Problem:
      description: Ошибка в текущем публичном профиле WealthLedger; отсутствие результата не кодируется пустым списком.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  schemas:
    Problem:
      type: object
      required: [status, code]
      properties:
        status:
          type: integer
        code:
          type: string
        title:
          type: string
        detail:
          type: string
    StockScreenerCriteria:
      type: object
      description: Все условия необязательны; отсутствие полей означает поиск по всем доступным к покупке акциям каталога.
      additionalProperties: false
      properties:
        query:
          type: string
          maxLength: 80
          description: Необязательная подстрока названия или тикера; пустая строка равнозначна отсутствию условия.
        sector:
          type: string
          minLength: 1
        shareType:
          type: string
          minLength: 1
        currency:
          type: string
          minLength: 1
        realExchange:
          type: string
          minLength: 1
          description: Реальная площадка исполнения, не код торгового режима.
        countryOfRisk:
          type: string
          minLength: 1
          description: Код страны основного бизнеса.
        maxLot:
          type: integer
          minimum: 1
          description: Включительная верхняя граница числа бумаг в лоте.
    StockScreenerPage:
      type: object
      required: [searchId, asOf, page, hasNext, items]
      properties:
        searchId:
          type: string
          description: Идентификатор только этого поиска, ограничен пользователем и подключением.
        asOf:
          type: string
          format: date-time
          description: Время получения полного списка акций от T-Invest, одинаковое на всех страницах результата.
        page:
          type: integer
          minimum: 1
        hasNext:
          type: boolean
        items:
          type: array
          maxItems: 30
          items:
            $ref: '#/components/schemas/StockScreenerItem'
    StockScreenerItem:
      type: object
      required: [instrumentUid, name, ticker, isin, shareType, sector, currency, realExchange, countryOfRisk, lot]
      properties:
        instrumentUid:
          type: string
          format: uuid
          description: Точный выбранный инструмент для ссылки на страницу акции; нельзя подменять неоднозначным тикером.
        name:
          type: string
        ticker:
          type: string
          nullable: true
        isin:
          type: string
          nullable: true
        shareType:
          type: string
          nullable: true
        sector:
          type: string
          nullable: true
        currency:
          type: string
          nullable: true
        realExchange:
          type: string
          nullable: true
        countryOfRisk:
          type: string
          nullable: true
        lot:
          type: integer
          minimum: 1
          nullable: true