openapi.yml

openapi: 3.0.3
info:
  title: Vindec Public API
  version: "1.0.0"
  description: |
    Public VIN decoder API — vehicle identification from a 17-character VIN.

    A single public endpoint, `GET /decode/{vin}`, returns a slim vehicle
    card: brand, model, modification, basic technical attributes and a
    `confidence` level describing how complete the decoding result is.

    No authentication is required. The endpoint is rate-limited by client
    IP — see the `429` response. Error messages are returned in Russian
    (see `ErrorResponse`).

    Vindec is a paid B2B service — there is no free tier or shared demo
    key. To request access, write to `fapi@iisis.ru` with company name,
    use-case and estimated monthly request volume.
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

servers:
  - url: https://api.fapi.iisis.ru/vindec/v1
    description: Production

paths:
  /decode/{vin}:
    get:
      summary: Decode a VIN
      description: |
        Returns a vehicle card for a 17-character VIN. The VIN is
        automatically uppercased and trimmed. The response is always
        `200 OK` for a structurally valid VIN, even when the model cannot
        be identified — in that case only `vin`, `brand_name` and
        `confidence = brand_only` are populated.
      operationId: decodeVIN
      tags: [decode]
      parameters:
        - name: vin
          in: path
          required: true
          description: 17-character VIN. Letters `I`, `O`, `Q` are not allowed (ISO 3779).
          schema:
            type: string
            minLength: 17
            maxLength: 17
            pattern: '^[A-HJ-NPR-Z0-9]{17}$'
          examples:
            opelAstra:
              value: XWF0AHL35D0011102
              summary: Opel Astra H Family (Avtotor, exact)
            vwJetta:
              value: 3VWSC29M4YM168618
              summary: VW Jetta IV (Mexico, partial)
            ladaSamara:
              value: XTA21099050000001
              summary: Lada Samara (brand_only)
      responses:
        "200":
          description: VIN decoded. The set of returned fields depends on `confidence`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicDecodeResult'
              examples:
                exact:
                  summary: Full card (`confidence=exact`)
                  value:
                    vin: XWF0AHL35D0011102
                    brand_name: OPEL
                    model_name: ASTRA H FAMILY
                    modification_name: 1.6 (Z16XEP)
                    model_year: 2013
                    body_type: Sedan
                    fuel_type: Petrol
                    displacement_cc: 1598
                    power_kw: 85
                    transmission: Manual
                    drive_type: FWD
                    confidence: exact
                partial:
                  summary: Brand and model only (`confidence=partial`)
                  value:
                    vin: 3VWSC29M4YM168618
                    brand_name: VW
                    model_name: JETTA IV I (1J2)
                    model_year: 2000
                    body_type: Sedan
                    fuel_type: Petrol
                    confidence: partial
                brandOnly:
                  summary: Brand only (`confidence=brand_only`)
                  value:
                    vin: XTA21099050000001
                    brand_name: LADA
                    confidence: brand_only
        "400":
          description: Invalid VIN — wrong length, disallowed characters or empty value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                empty:
                  value: { error: "VIN не указан", code: 400 }
                badChars:
                  value: { error: "VIN должен содержать 17 символов", code: 400 }
        "429":
          description: Rate limit exceeded for the caller IP (default 20 requests / minute).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: too many requests
                code: 429
        "500":
          description: Internal decoder error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: ошибка декодирования
                code: 500

components:
  schemas:
    PublicDecodeResult:
      type: object
      description: |
        Slim public decoder response. Every field except `vin` and
        `confidence` may be absent (`omitempty`) — absence means the data
        is unknown, not that the value is zero or an empty string.
      required: [vin, confidence]
      properties:
        vin:
          type: string
          description: Normalised (uppercased) VIN.
          minLength: 17
          maxLength: 17
          example: XWF0AHL35D0011102
        brand_name:
          type: string
          description: Vehicle brand. May differ from the physical assembler — for example, an OPEL car physically built by Avtotor.
          example: OPEL
        model_name:
          type: string
          description: Vehicle model from the FAPI catalog reference.
          example: ASTRA H FAMILY
        modification_name:
          type: string
          description: Modification (trim level, engine code).
          example: 1.6 (Z16XEP)
        model_year:
          type: integer
          description: Model year (10th VIN position). May differ from the calendar production date.
          minimum: 1980
          maximum: 2099
          example: 2013
        body_type:
          type: string
          description: Body type.
          example: Sedan
        fuel_type:
          type: string
          description: Fuel type.
          example: Petrol
        displacement_cc:
          type: integer
          description: Engine displacement, cm³.
          minimum: 0
          example: 1598
        power_kw:
          type: integer
          description: Engine power, kW. Multiply by 1.36 to convert to horsepower.
          minimum: 0
          example: 85
        transmission:
          type: string
          description: Transmission type.
          example: Manual
        drive_type:
          type: string
          description: Drive type.
          example: FWD
        confidence:
          type: string
          description: |
            Decoding confidence level:
            - `exact` — an exact pattern match was found in the catalog and full technical attributes are available;
            - `partial` — brand and model were identified, but technical attributes are missing;
            - `brand_only` — only the brand could be identified, via the WMI prefix.
          enum: [exact, partial, brand_only]
          example: exact

    ErrorResponse:
      type: object
      description: Standard error envelope. The `error` field is a human-readable message in Russian.
      required: [error, code]
      properties:
        error:
          type: string
          description: Human-readable error message (Russian).
          example: VIN не указан
        code:
          type: integer
          description: Mirrors the HTTP status code of the response.
          example: 400