openapi: 3.0.1
info:
  title: Vincario VIN Decoder Account Market Value API
  description: 'REST API for the vindecoder.eu service operated by Vincario. The API decodes a Vehicle Identification Number (VIN) into a full vehicle specification and also provides vehicle market value, real-time stolen-vehicle checks, the list of decodable vehicle details, and the remaining account balance.


    Authentication uses an API key (id) and a secret key. Each request carries a per-request control sum in the URL path. The control sum is the first 10 characters of the SHA1 hash of the pipe-delimited string `{lookup}|{id}|{apikey}|{secretkey}`, where `{lookup}` is the uppercased VIN for VIN-based endpoints (decode, vininfo, vehicle-market-value, stolencheck) and the API key itself for the balance endpoint, and `{id}` is the endpoint identifier (for example `decode`, `vininfo`, `vehicle-market-value`, `stolencheck`, `balance`). The secret key is never transmitted; it is only used to derive the control sum. The path layout is `/{apikey}/{controlsum}/{id}/{vin}.json`.'
  termsOfService: https://vindecoder.eu/terms
  contact:
    name: Vincario Support
    url: https://vincario.com
  version: '3.2'
servers:
- url: https://api.vindecoder.eu/3.2
  description: Vincario VIN Decoder API v3.2
security:
- signedPath: []
tags:
- name: Market Value
paths:
  /{apikey}/{controlsum}/vehicle-market-value/{vin}.json:
    get:
      operationId: vehicleMarketValue
      tags:
      - Market Value
      summary: Get statistical market value for a vehicle.
      description: Returns statistical data about the price and odometer of vehicles on the market matching the decoded VIN, together with the input parameters used for the computation. The control sum is computed from `{VIN}|vehicle-market-value|{apikey}|{secretkey}`.
      parameters:
      - $ref: '#/components/parameters/ApiKey'
      - $ref: '#/components/parameters/ControlSum'
      - $ref: '#/components/parameters/Vin'
      responses:
        '200':
          description: Market value statistics for the vehicle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketValueResponse'
        '400':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
components:
  schemas:
    MarketValueResponse:
      type: object
      properties:
        vin:
          type: string
          example: WF0MXXGBWM8R43240
        price:
          type: object
          description: Statistical price data for matching vehicles on the market.
          properties:
            currency:
              type: string
              example: EUR
            count:
              type: integer
              example: 124
            market_price_min:
              type: number
              example: 6500
            market_price_max:
              type: number
              example: 12900
            market_price_mean:
              type: number
              example: 9100
        odometer:
          type: object
          description: Statistical odometer data for matching vehicles on the market.
          properties:
            unit:
              type: string
              example: km
            count:
              type: integer
              example: 124
            odometer_min:
              type: number
              example: 45000
            odometer_max:
              type: number
              example: 280000
            odometer_mean:
              type: number
              example: 160000
        input:
          type: object
          description: Input parameters used for the market value computation.
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
          example: Invalid VIN
        code:
          type: integer
          description: Error code.
          example: 400
  parameters:
    ApiKey:
      name: apikey
      in: path
      required: true
      description: The account API key (id).
      schema:
        type: string
    Vin:
      name: vin
      in: path
      required: true
      description: The 17-character Vehicle Identification Number (uppercase).
      schema:
        type: string
        minLength: 11
        maxLength: 17
        example: WF0MXXGBWM8R43240
    ControlSum:
      name: controlsum
      in: path
      required: true
      description: First 10 characters of `sha1("{lookup}|{id}|{apikey}|{secretkey}")`.
      schema:
        type: string
        minLength: 10
        maxLength: 10
  responses:
    Error:
      description: Error response (invalid VIN, bad control sum, or insufficient balance).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    signedPath:
      type: apiKey
      in: query
      name: controlsum
      description: Path-signed authentication. The API key (id) and a per-request SHA1 control sum are passed as URL path segments rather than headers or query parameters; this scheme is declared as a placeholder because OpenAPI 3.0 cannot natively express path-segment-based signed credentials. The control sum is `substr(sha1("{lookup}|{id}|{apikey}|{secretkey}"), 0, 10)`. The secret key is never sent over the wire.