openapi: 3.0.0
info:
  title: Fleet Remarketing External API
  version: 0.0.1
  description: >
    The Fleet Remarketing External API it's a set of services to share our data
    with interested external partners
  contact:
    name: Ana Costa
    url: https://finn-mobility.slack.com/team/U04PLDDE4AC
    email: ana.costa@finn.com
servers:
  - url: https://partners.finn.com/api/v1
    description: Production environment
tags:
  - name: Cars
    description: Operations related to cars
security:
  - ApiKeyAuth: []
    Actor: []
    BearerAuth: []
paths:
  /cars:
    get:
      tags:
        - Cars
      summary: List car inventory by filter
      description: >
        Lists all car inventory for remarketing that meets the filter criteria. 

        You can use a range of filters on the list returned, including filtering
        by:

        * Brand name

        * Color

        * Expected return date

        * Model name

        * Vehicle identification number (VIN)

        * Model Year

        * Configuration ID

        * Trim

        * Registration Dates

        * Engine

        * Latest Mileages

        * Fuel

        * Co2 emission

        * Car lifecycle status


        You can also apply sorting on the list returned by the following
        properties:

        * Expected return date

        * Date First Registration

        * Damage Deductible

        * Latest Mileage

        * Brand Name

        * Model Name

        * Vin

        * Location Name

        * Color

        * Trim

        * Engine

        * Latest Mileage

        * Shift

        * Fuel Name

        * Model Year

        * Offer Statuses
      operationId: GetCarInventory
      parameters:
        - in: query
          name: brandNames
          schema:
            type: string
          description: Filter by Brand names
          example: Tesla,Audi
        - in: query
          name: modelNames
          schema:
            type: string
          description: Filter by Model names
          example: Grand Cherokee L,C5 Aircross
        - in: query
          name: colorName
          schema:
            type: string
          description: Filter by Color
          example: Diamond Black Crystal Pearl Coat
        - in: query
          name: expectedReturnDate
          schema:
            type: string
          description: >-
            Filter by Expected Return Date date range. Can filter by initial or
            end date, or date range.
          example: \%2023-10-30
        - in: query
          name: vins
          schema:
            type: array
            items:
              type: string
          description: >-
            Filter by multple VINs, This filter takes the next precedence after
            finnCarIds.
          example: VXKUPHNKSM4280660,VXKUPHNKSM4280661
        - in: query
          name: trim
          schema:
            type: string
          description: Filter by Trim
          example: LT
        - in: query
          name: registrationDate
          schema:
            type: string
          description: >-
            Filter by Registration Dates date range. Can filter by initial or
            end date, or date range.
          example: 2023-01-30%2023-10-30
        - in: query
          name: engine
          schema:
            type: string
          description: Filter by Engine
          example: 1.2 Turbo
        - in: query
          name: shift
          schema:
            type: string
          description: Filter by Gear
          example: Automatic
        - in: query
          name: latestMileage
          schema:
            type: string
          description: >-
            Filter by latest mileages range. Can filter by initial or end
            mileage, or mileage range.
          example: 10000%15000
        - in: query
          name: fuelName
          schema:
            type: string
          description: Filter by Fuel Type
          example: Diesel
        - in: query
          name: modelYear
          schema:
            type: number
          description: Filter by Model Year
          example: 2023
        - in: query
          name: co2Emission
          schema:
            type: string
          description: >-
            Filter by co2Emission range. Can filter by initial or end
            co2Emission, or co2Emission range.
          example: 100%150
        - in: query
          name: offerStatuses
          schema:
            type: string
          description: Filter by offer statuses
          example: open,lost
        - in: query
          name: sortBy
          schema:
            type: string
            enum:
              - expectedDefleetingDate
              - dateFirstRegistration
              - damageDeductible
              - latestMileage
              - brandName
              - modelName
              - vin
              - locationName
              - defleetingCompound
              - color
              - trim
              - engine
              - signedBy
              - shift
              - fuelName
              - tcoTiresPlanned
              - modelYear
          description: >-
            Sort by a property, add (-) in front of the property to sort
            descending
          example: '-expectedDefleetingDate'
        - $ref: '#/components/parameters/PaginationCurrentPageParameter'
        - $ref: '#/components/parameters/PaginationPerPageParameter'
      responses:
        '200':
          description: Inventory
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarInventoryPaginated'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/NotAllowedError'
        '500':
          $ref: '#/components/responses/InternalError'
  /cars/{finnCarId}:
    get:
      tags:
        - Cars
      summary: Gets all configuration information available for a specific car.
      operationId: GetCarConfigurationByCarId
      parameters:
        - $ref: '#/components/parameters/finnCarId'
      responses:
        '200':
          $ref: '#/components/responses/GetCarConfigurationByFinnCarIdSuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '403':
          $ref: '#/components/responses/NotAllowedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        Generated through the API Gateway console. Each service uses the
        separate key.
    Actor:
      type: apiKey
      in: header
      name: X-Finn-Actor
      description: Identifies who has made the request.
    BearerAuth:
      type: http
      description: Authenticates the identified actor who has made the request.
      scheme: bearer
  responses:
    GetCarConfigurationByFinnCarIdSuccessResponse:
      description: CarConfiguration
      content:
        application/json:
          schema:
            type: object
            required:
              - data
            properties:
              data:
                $ref: '#/components/schemas/CarConfiguration'
    InternalError:
      description: Internal error
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                type: string
                example: internal error
    FailedDependency:
      description: Failed Dependency
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                type: string
                example: failed Noco dependency
    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                type: string
                example: not found
    BadRequestError:
      description: Invalid operation params
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                type: string
                example: bad request
    NotAllowedError:
      description: Action on operation denied
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                type: string
                example: Forbidden to continue
  parameters:
    finnCarId:
      name: finnCarId
      in: path
      required: true
      schema:
        type: string
        example: 34nk23on
    PaginationCurrentPageParameter:
      name: currentPage
      in: query
      schema:
        type: integer
        description: The current page of the list, for pagination purposes. Defaults to 1
    PaginationPerPageParameter:
      name: perPage
      in: query
      schema:
        type: integer
        description: The amount of items per page, for pagination purposes. Defaults to 25
  schemas:
    Pagination:
      type: object
      required:
        - current_page
        - last_page
        - per_page
        - total
      properties:
        current_page:
          type: integer
          example: 1
        last_page:
          type: integer
          example: 2
        per_page:
          type: integer
          example: 25
        total:
          type: integer
          example: 26
    CarInventoryPaginated:
      type: object
      required:
        - data
      properties:
        inventory:
          type: array
          items:
            $ref: '#/components/schemas/CarInventory'
        pagination:
          $ref: '#/components/schemas/Pagination'
    CarInventory:
      type: object
      required:
        - finn_car_id
        - config_id
        - brand_name
        - model_name
        - vin
      properties:
        finn_car_id:
          type: string
          example: abc123
        config_id:
          type: integer
          example: 100
        brand_name:
          type: string
          example: Jeep
        model_name:
          type: string
          example: Grand Cherokee L
        vin:
          type: string
          example: ABC123456789
        model_year:
          type: integer
          example: 2022
          nullable: true
        location_name:
          type: integer
          description: Location where the car is
          example: compound_glovis_philadelphia
          nullable: true
        color:
          type: string
          example: Diamond Black Crystal Pearl Coat
          nullable: true
        trim:
          type: string
          example: Laredo
          nullable: true
        engine:
          type: string
          example: 3.6L V6
          nullable: true
        car_lifecycle_status:
          $ref: '#/components/schemas/CarLifecycleStatus'
        msrp_incl_options_net:
          type: number
          example: 46675
          nullable: true
        date_first_registration:
          type: string
          nullable: true
          example: '2022-10-10'
        latest_mileage:
          type: integer
          example: 0
          nullable: true
        shift:
          type: string
          example: A
          nullable: true
        fuel_name:
          type: string
          example: Elektro
          nullable: true
        power:
          type: integer
          example: 378
          nullable: true
        has_hitch:
          type: boolean
          example: true
          nullable: true
        tco_tires_planned:
          type: string
          example: all-season
          nullable: true
        expected_defleeting_date:
          type: string
          nullable: true
          example: '2022-10-10'
        tco_purchase_price_final_incl_bafa_net:
          type: number
          example: 16197.4
          nullable: true
        model_body_type:
          type: string
          example: SUV
          nullable: true
        deregistration_date:
          type: string
          example: '2022-12-19'
        offers:
          type: array
          description: Array of offers for this car
          items:
            $ref: '#/components/schemas/PartnerOffer'
        end_location:
          type: string
          example: AKB Dortmund
          nullable: true
        damage_deductible:
          type: number
          example: 5000
        expected_return_mileage:
          type: integer
          example: 8500
          nullable: true
        drive:
          type: string
          example: four_wheel_drive
        co2_emission:
          type: number
          example: 62
          nullable: true
    CarConfiguration:
      type: object
      properties:
        config_id:
          type: integer
          example: 1
        brand_name:
          type: string
          nullable: true
          example: Tesla
        model_name:
          type: string
          nullable: true
          example: Model 3
        model_year:
          type: integer
          nullable: true
          example: 2022
        trim_name:
          type: string
          nullable: true
          example: Long Range
        engine_name:
          type: string
          nullable: true
          example: Long Range AWD
        consumption_combined:
          type: number
          nullable: true
          example: 25
        consumption_city:
          type: number
          nullable: true
          example: 22
        consumption_highway:
          type: number
          nullable: true
          example: 30
        fuel:
          type: string
          nullable: true
          example: Electric
        gearshift:
          type: string
          nullable: true
          example: Automatic
        power_kw:
          type: number
          nullable: true
          example: 258 (KW)
        co2_emission:
          type: number
          nullable: true
          example: 123
        co2_class:
          type: string
          nullable: true
          example: A
          enum:
            - A
            - B
            - C
            - D
            - E
            - F
            - G
        ev_range:
          type: number
          nullable: true
          example: 200
        hybrid_electric_range:
          type: number
          nullable: true
          example: 234
        variant_id:
          type: integer
          nullable: true
          example: 22
        doors:
          type: integer
          nullable: true
          example: 5
        body_type:
          type: string
          nullable: true
          example: Sedan
        drive:
          type: string
          nullable: true
          example: All-Wheel Drive
        has_hitch:
          type: boolean
          example: true
        seats:
          type: integer
          nullable: true
          example: 5
        version_name:
          type: string
          nullable: true
          example: 2.8 D-4D Comfort
        exterior_color:
          $ref: '#/components/schemas/WebsiteColor'
        interior_color:
          $ref: '#/components/schemas/WebsiteColor'
        msrp:
          type: number
          nullable: true
          example: 51440
        equipments:
          type: array
          items:
            $ref: '#/components/schemas/WebsiteEquipment'
        description:
          type: string
          nullable: true
          example: This is a really nice car
        car_images:
          $ref: '#/components/schemas/CarImages'
        config_attachment:
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Attachment'
        energy_label:
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/Attachment'
    CarLifecycleStatus:
      type: string
      nullable: true
      enum:
        - ordered
        - produced
        - arrived_from_supplier
        - in_technical_preparations
        - ready_to_deliver
        - in_subscription
        - returned
        - in_repossession_process
        - in_defleeting_preparations
        - ready_to_defleet
        - defleeted
        - cancelled
    PartnerOffer:
      type: object
      properties:
        offer_id:
          type: integer
          example: 1
        offer_status:
          type: string
          example: signed
          enum:
            - open
            - agreed
            - signed
            - lost
            - invalid
        partner_name:
          type: string
          example: Walser
        clearing_sales_amount:
          type: number
          nullable: true
          format: float
          example: 899.99
        start_datetime:
          type: string
          nullable: true
          example: '2022-10-10'
        end_datetime:
          type: string
          nullable: true
          example: '2022-10-10'
    WebsiteColor:
      type: object
      properties:
        color_exact:
          type: string
          nullable: true
          example: Diamond Black
        primary_color:
          $ref: '#/components/schemas/NormedColor'
        secondary_color:
          $ref: '#/components/schemas/NormedColor'
    NormedColor:
      type: object
      properties:
        color:
          type: string
          nullable: true
          example: Black
        color_hex:
          type: string
          nullable: true
          example: '#FFFFFF'
    WebsiteEquipment:
      type: object
      properties:
        category:
          type: string
          example: Comfort | Safety | Interieur | Multimedia | Exterior
        full_text:
          type: string
          example: Music and media over Bluetooth
        highlight_text:
          type: string
          nullable: true
          example: This is super special
        option_id:
          type: integer
          nullable: true
          example: 123
        option_type:
          type: string
          nullable: true
          example: standard | optional
    CarImages:
      type: array
      items:
        type: object
        required:
          - image_angle_name
          - file_url
        properties:
          image_angle_name:
            type: string
            nullable: true
            example: picture_frontal
          file_url:
            type: string
            nullable: true
            example: >-
              https://dataops-nocodb-s3-bucket-production.s3.eu-central-1.amazonaws.com/nc/uploads/noco/fleet_blue_dragon_develop/car_images/image/XWqGHN.png
    Attachment:
      type: object
      properties:
        file_name:
          type: string
          example: config-attachment.pdf
        file_url:
          type: string
          example: https://s3-path-to-download-for-2-hours.com
