openapi: 3.0.3
info:
  title: AvtoVinCod API
  description: >
    Проверка транспортного средства по VIN на основе данных ГИБДД:
    характеристики, история регистрации и периоды владения, данные ПТС/СТС,
    ограничения на регистрационные действия и розыск.
    Списание только при получении данных от ГИБДД; success=0 бесплатно.
  version: "1.0"
  contact:
    name: AvtoVinCod
    email: api@avtovincod.ru
    url: https://avtovincod.ru
servers:
  - url: https://api.avtovincod.ru
security:
  - bearerAuth: []
paths:
  /score:
    get:
      summary: Полная проверка ТС по VIN
      description: >
        Возвращает характеристики ТС, историю владения, данные ПТС/СТС,
        действующие ограничения и статус розыска. Обработка асинхронная,
        до 45 секунд — рекомендуемый таймаут клиента 60 секунд.
        VIN нормализуется автоматически (кириллические двойники заменяются
        на латиницу, регистр приводится к верхнему).
      operationId: checkVehicle
      parameters:
        - name: vin
          in: query
          required: true
          description: VIN-номер, 17 символов (латиница A–Z без I/O/Q, цифры 0–9)
          schema:
            type: string
            minLength: 17
            maxLength: 17
            example: Z94K241BBJR061674
        - name: token
          in: query
          required: false
          description: Bearer-токен, если не передан в заголовке Authorization
          schema:
            type: string
        - name: force_refresh
          in: query
          required: false
          description: Значение "1" — игнорировать кэш
          schema:
            type: string
            enum: ["1"]
      responses:
        "200":
          description: Успешный ответ (success=1) либо данные не найдены (success=0, бесплатно)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScoreResponse"
        "400":
          description: "VIN_INVALID — некорректный формат VIN"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: "NO_TOKEN / TOKEN_INVALID — проблема с токеном"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "402":
          description: "INSUFFICIENT_BALANCE — недостаточно средств"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: "SCORE_NOT_ALLOWED / IP_NOT_ALLOWED"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: "RATE_LIMIT / SCORE_LIMIT_DAY / SCORE_LIMIT_MONTH / SCORE_LIMIT_YEAR"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "503":
          description: Технические работы на сервисе
  /stats.php:
    get:
      summary: Статистика и баланс клиента
      operationId: getStats
      responses:
        "200":
          description: Текущий баланс и статистика запросов
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer-токен (96 символов hex), выдаётся при подключении
  schemas:
    ScoreResponse:
      type: object
      properties:
        success:
          type: integer
          enum: [0, 1]
          description: 1 — запрос выполнен, 0 — ошибка или данные не найдены
        record:
          $ref: "#/components/schemas/VehicleRecord"
        restrictions:
          type: array
          items:
            $ref: "#/components/schemas/Restriction"
        searches:
          type: array
          items:
            $ref: "#/components/schemas/SearchEntry"
        status:
          $ref: "#/components/schemas/QuickStatus"
    VehicleRecord:
      type: object
      nullable: true
      properties:
        vin:
          type: string
          nullable: true
          description: VIN из базы ГИБДД, нормализованный
        bodyNumber:
          type: string
          nullable: true
          description: Номер кузова
        regNumber:
          type: string
          nullable: true
          description: Государственный регистрационный номер
        sts:
          type: object
          properties:
            num:
              type: string
              nullable: true
            date:
              type: string
              nullable: true
              description: Дата выдачи СТС (YYYY-MM-DD)
        pts:
          type: object
          properties:
            num:
              type: string
              nullable: true
            date:
              type: string
              nullable: true
              description: Дата выдачи ПТС (YYYY-MM-DD)
        model:
          type: string
          nullable: true
          description: Марка и модель
        engineVolume:
          type: string
          nullable: true
          description: Объём двигателя, куб. см
        color:
          type: string
          nullable: true
        powerHp:
          type: string
          nullable: true
          description: Мощность, л.с.
        powerKwt:
          type: string
          nullable: true
          description: Мощность, кВт
        year:
          type: string
          nullable: true
        maxWeight:
          type: string
          nullable: true
          description: Максимальная масса, кг
        weightWithoutLoading:
          type: string
          nullable: true
          description: Масса без нагрузки, кг
        category:
          type: string
          nullable: true
          description: Категория ТС (A, B, C, D)
        lastRegAction:
          type: string
          nullable: true
          description: Последнее регистрационное действие
        recordStatus:
          type: string
          nullable: true
          description: действующая / архивная
        ownershipPeriods:
          type: array
          items:
            $ref: "#/components/schemas/OwnershipPeriod"
    OwnershipPeriod:
      type: object
      properties:
        personType:
          type: string
          description: Физическое лицо / Юридическое лицо
        from:
          type: string
          nullable: true
          description: Дата начала владения (YYYY-MM-DD)
        to:
          type: string
          nullable: true
          description: Дата окончания; null — текущий владелец
    Restriction:
      type: object
      properties:
        restriction_name:
          type: string
          description: Вид ограничения
        region:
          type: string
          nullable: true
        organization_name:
          type: string
          nullable: true
        reasons:
          type: string
          nullable: true
          description: Основание; ФИО маскируется автоматически
        enforcement_number:
          type: string
          nullable: true
          description: Номер исполнительного производства
        enforcement_date:
          type: string
          nullable: true
          description: Дата ИП (YYYY-MM-DD)
        osp_address:
          type: string
          nullable: true
          description: Адрес отдела судебных приставов
    SearchEntry:
      type: object
      properties:
        model:
          type: string
          nullable: true
        model_year:
          type: string
          nullable: true
        region:
          type: string
          nullable: true
        search_date:
          type: string
          nullable: true
          description: Дата постановки на учёт в розыске
    QuickStatus:
      type: object
      properties:
        restricted:
          type: boolean
          description: true — есть ограничения на рег. действия
        wanted:
          type: boolean
          description: true — ТС находится в розыске
        spec_wanted:
          type: boolean
          description: true — ТС в спецрозыске
    ErrorResponse:
      type: object
      properties:
        success:
          type: integer
          enum: [0]
        error:
          type: string
          description: Описание ошибки
        code:
          type: string
          description: Код ошибки
          enum:
            - VIN_INVALID
            - NO_TOKEN
            - TOKEN_INVALID
            - INSUFFICIENT_BALANCE
            - SCORE_NOT_ALLOWED
            - IP_NOT_ALLOWED
            - RATE_LIMIT
            - SCORE_LIMIT_DAY
            - SCORE_LIMIT_MONTH
            - SCORE_LIMIT_YEAR
