openapi: 3.0.3
info:
  title: TENDEX API
  description: |
    API для поиска государственных и коммерческих закупок.
    
    ## Возможности
    - Семантический поиск по 6.3M+ тендеров
    - Аналитика рынка закупок
    - Проверка контрагентов
    - AI-прогнозы и рекомендации
    
    ## Аутентификация
    Большинство endpoints публичные. Для расширенного доступа используйте Bearer токен.
  version: 1.0.0
  contact:
    name: TENDEX Support
    url: https://aitx.one
  license:
    name: Proprietary

servers:
  - url: https://aitx.one/api
    description: Production

tags:
  - name: health
    description: Health checks
  - name: contragents
    description: Контрагенты
  - name: search
    description: Поиск тендеров
  - name: analytics
    description: Аналитика
  - name: ai
    description: AI Analytics

paths:
  /health:
    get:
      tags: [health]
      summary: Статус системы
      responses:
        '200':
          description: Система работает
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [healthy, degraded]
                  checks:
                    type: object

  /contragents/top-customers:
    get:
      tags: [contragents]
      summary: ТОП заказчиков по сумме закупок
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Список топ заказчиков
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TopCustomer'

  /contragents/search:
    get:
      tags: [contragents]
      summary: Поиск контрагентов
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
            minLength: 2
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Результаты поиска
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContragentShort'

  /contragents/{inn}:
    get:
      tags: [contragents]
      summary: Карточка контрагента
      parameters:
        - name: inn
          in: path
          required: true
          schema:
            type: string
            pattern: '^\d{10,12}$'
      responses:
        '200':
          description: Данные контрагента
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Contragent'
        '404':
          description: Контрагент не найден

  /contragents/{inn}/as-customer:
    get:
      tags: [contragents]
      summary: Статистика как заказчика
      parameters:
        - name: inn
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Статистика закупок
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/CustomerStats'

  /contragents/{inn}/history:
    get:
      tags: [contragents]
      summary: История контрактов
      parameters:
        - name: inn
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 200
      responses:
        '200':
          description: Список контрактов
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contract'

  /contragents/{inn}/reliability:
    get:
      tags: [contragents]
      summary: Оценка надёжности
      parameters:
        - name: inn
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Оценка надёжности
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Reliability'

  /search/semantic:
    get:
      tags: [search]
      summary: Семантический поиск
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Результаты поиска
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tender'

  /analytics/overview:
    get:
      tags: [analytics]
      summary: Обзор рынка
      responses:
        '200':
          description: Статистика рынка
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/MarketOverview'

components:
  schemas:
    TopCustomer:
      type: object
      properties:
        inn:
          type: string
        name:
          type: string
        region:
          type: integer
        total_sum:
          type: number
        purchases_count:
          type: integer

    ContragentShort:
      type: object
      properties:
        inn:
          type: string
        name:
          type: string
        region:
          type: integer

    Contragent:
      type: object
      properties:
        inn:
          type: string
        name:
          type: string
        type:
          type: string
          enum: [organization, individual]
        type_text:
          type: string
        region:
          type: integer
        is_customer:
          type: boolean
        is_supplier:
          type: boolean
        reliability_score:
          type: integer
          minimum: 0
          maximum: 100
        reliability_level:
          type: string
          enum: [high, medium, low, very_low]
        last_activity:
          type: string
          format: date
        first_activity:
          type: string
          format: date

    CustomerStats:
      type: object
      properties:
        total_purchases:
          type: integer
        total_sum:
          type: number
        avg_price:
          type: number
        by_stage:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              count:
                type: integer
        by_fz_type:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              count:
                type: integer

    Contract:
      type: object
      properties:
        id:
          type: string
        purchase_number:
          type: string
        name:
          type: string
        price:
          type: number
        stage:
          type: string
        date:
          type: string
          format: date
        fz_type:
          type: string
        role:
          type: string
        role_text:
          type: string

    Reliability:
      type: object
      properties:
        inn:
          type: string
        name:
          type: string
        score:
          type: integer
        level:
          type: string
        level_text:
          type: string
        total_contracts:
          type: integer
        total_sum:
          type: number

    Tender:
      type: object
      properties:
        id:
          type: string
        purchase_number:
          type: string
        name:
          type: string
        max_price:
          type: number
        stage:
          type: string
        fz_type:
          type: string
        published_at:
          type: string
          format: date
        region:
          type: integer

    MarketOverview:
      type: object
      properties:
        total_tenders:
          type: integer
        total_sum:
          type: number
        by_fz_type:
          type: object
        by_stage:
          type: object
