openapi: 3.0.0
info:
  title: Vehicle API - Apigee
  description: >-
    Vehicle API documentation <h2>Authentication & Authorization</h2> <p>You
    will need to be identified before calling any endpoints. </p> <p>In order to
    be recognized and authorized to access our Vehicle API, we put in place 2
    mechanisms:</p><ul><li>Authentication mechanism is done with a client id
    dedicated to you. <br/>Remember that the client id provided should be shared
    with care.<br/> The client id must be inserted in the header of the request
    in the appropriate field</li><li>Authorization mechanism is done by a
    well-known authorization flow for REST Web API: <strong>Basic auth
    flow.</strong></li></ul>
  license:
    name: Internal usage only
  version: 1.0.3
servers:
  - url: https://indus.api.euromaster.com
    description: APIGEE UAT
  - url: https://api.euromaster.com
    description: APIGEE PROD
tags:
  - name: Vehicles
    description: Vehicles operation with all operation types
paths:
  /vehicle-erm/v1/vehicles:
    summary: Vehicles endpoints
    get:
      summary: Get vehicles data
      description: Get vehicles data filtered by parameters
      operationId: getVehicles
      tags:
        - Vehicles
      parameters:
        - in: query
          name: pageNumber
          schema:
            $ref: '#/components/schemas/PageNumberParam'
          required: true
          description: The page number
        - in: query
          name: pageSize
          schema:
            $ref: '#/components/schemas/PageSizeParam'
          required: true
          description: The page size
        - in: query
          name: lastModifiedDateFrom
          required: false
          description: Date from for last update date of data
          schema:
            $ref: '#/components/schemas/lastModifiedDateFromParam'
        - in: query
          name: lastModifiedDateTo
          required: false
          description: Date to for last update date of data
          schema:
            $ref: '#/components/schemas/lastModifiedDateToParam'
        - in: query
          name: registrationNumber
          required: false
          description: >-
            Registration number, if filled then dates filters will not be taken
            into account
          schema:
            $ref: '#/components/schemas/RegistrationNumberParam'
        - in: query
          name: registrationCountryCode
          required: false
          description: Country code of registration, only used to trigger autoidat calls
          schema:
            $ref: '#/components/schemas/RegistrationCountryCodeParam'
        - in: query
          name: externalRef
          required: false
          description: Identifier of the external reference
          schema:
            $ref: '#/components/schemas/ExternalRefQueryParam'
        - in: query
          name: source
          required: false
          description: Source of the external reference
          schema:
            $ref: '#/components/schemas/SourceQueryParam'
      responses:
        '200':
          $ref: '#/components/responses/VehiclesResponseDTO'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestDTO'
              examples:
                InvalidPageSize:
                  value:
                    errors:
                      - error: must be greater than or equal to 1
                        property: pageSize
                InvalidPageNumber:
                  value:
                    errors:
                      - error: must be greater than or equal to 1
                        property: pageNumber
                InvalidDatesOrder:
                  value:
                    errors:
                      - error: 'dateFrom : 2024-07-01T00:00:00 is greater than dateTo'
                        property: lastModifiedDateFrom
        '500':
          description: Internal error
          $ref: '#/components/responses/InternalErrorDTO'
  /vehicle-erm/v1/vehicles/external:
    summary: Vehicles external endpoints
    post:
      summary: Create vehicles data
      description: Create vehicles
      operationId: createVehicle
      tags:
        - Vehicles
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVehicleQueryDTO'
            examples:
              standardBody:
                summary: Create vehicle
                description: Create a vehicle with the given informations
                value:
                  externalRef: AAA123
                  ownerExternalRef: '20831238'
                  registrationNumber: AA-123-AA
                  registrationDate: '2024-01-01'
                  vin: ''
                  make: Peugeot
                  model: '208'
                  energy: PETROL
                  mileage: 120000
                  mileageUOM: km
                  annualMileage: 20000
                  annualMileageUOM: km
                  nextInspectionDate: '2025-09-10'
      responses:
        '200':
          $ref: '#/components/responses/CreateVehiclesResponseDTO'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestDTO'
              examples:
                missing mandatory field:
                  value:
                    errors:
                      - error: The field 'externalRef' is mandatory
                        property: externalRef
        '500':
          description: Internal error
          $ref: '#/components/responses/InternalErrorDTO'
  /vehicle-erm/v1/vehicles/{vehicleCode}/tyreOptions:
    summary: Tyre options endpoints
    get:
      summary: Get tyre options for a vehicle
      description: Get tyre options for a vehicle
      operationId: getTyreOptions
      tags:
        - Vehicles
      parameters:
        - in: path
          name: vehicleCode
          schema:
            $ref: '#/components/schemas/VehicleCodeParam'
          required: true
          description: The vehicle code
      responses:
        '200':
          $ref: '#/components/responses/TyreOptionsResponseDTO'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestDTO'
              examples:
                vehicleCodeNotFound:
                  value:
                    errors:
                      - error: Vehicle not found with code 2
                        property: vehicleCode
                tyreOptionsNotFound:
                  value:
                    errors:
                      - error: Tyre options not found
                        property: vehicleCode
        '500':
          description: Internal error
          $ref: '#/components/responses/InternalErrorDTO'
  /vehicle-erm/v1/vehicles/state:
    summary: Vehicles state endpoint
    get:
      summary: Get vehicles states
      description: Get vehicles state data filtered by parameters
      operationId: getVehiclesState
      tags:
        - Vehicles
      parameters:
        - in: query
          name: pageNumber
          schema:
            $ref: '#/components/schemas/PageNumberParam'
          required: true
          description: The page number
        - in: query
          name: pageSize
          schema:
            $ref: '#/components/schemas/PageSizeParam'
          required: true
          description: The page size
        - in: query
          name: lastModifiedDateFrom
          required: false
          description: Date from for last update date of data
          schema:
            $ref: '#/components/schemas/lastModifiedDateFromParam'
        - in: query
          name: lastModifiedDateTo
          required: false
          description: Date to for last update date of data
          schema:
            $ref: '#/components/schemas/lastModifiedDateToParam'
      responses:
        '200':
          $ref: '#/components/responses/VehiclesStateResponseDTO'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestDTO'
              examples:
                InvalidPageSize:
                  value:
                    errors:
                      - error: must be greater than or equal to 1
                        property: pageSize
                InvalidPageNumber:
                  value:
                    errors:
                      - error: must be greater than or equal to 1
                        property: pageNumber
                InvalidDatesOrder:
                  value:
                    errors:
                      - error: 'dateFrom : 2024-07-01T00:00:00 is greater than dateTo'
                        property: lastModifiedDateFrom
        '401':
          $ref: '#/components/responses/UnauthorizedDTO'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestDTO'
              examples:
                InvalidPageNumber:
                  value:
                    errors:
                      - error: The pageNumber must be lower than or equals to 3
                        property: pageNumber
        '500':
          $ref: '#/components/responses/InternalErrorDTO'
security:
  - OAuth2: []
    ApiKeyAuth: []
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows: {}
    ApiKeyAuth:
      type: apiKey
      in: header
      name: clientid
  schemas:
    VehiclesResponseDTO:
      type: object
      properties:
        pagination:
          description: Pagination information
          $ref: '#/components/schemas/PaginationDTO'
        vehicles:
          type: array
          maxItems: 1000
          items:
            description: Vehicles information
            $ref: '#/components/schemas/VehicleDTO'
    CreateVehiclesResponseDTO:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/VehicleCode'
    CreateVehicleQueryDTO:
      type: object
      properties:
        externalRef:
          $ref: '#/components/schemas/ExternalRef'
        ownerExternalRef:
          type: string
          example: '20831238'
          maxLength: 255
          description: Owner external Reference
        registrationNumber:
          $ref: '#/components/schemas/RegistrationNumber'
        registrationDate:
          $ref: '#/components/schemas/RegistrationDate'
        vin:
          $ref: '#/components/schemas/VIN'
        make:
          $ref: '#/components/schemas/Make'
        model:
          $ref: '#/components/schemas/Model'
        energy:
          $ref: '#/components/schemas/Energy'
        mileage:
          $ref: '#/components/schemas/Mileage'
        mileageUOM:
          $ref: '#/components/schemas/MileageUOM'
        annualMileage:
          $ref: '#/components/schemas/AnnualMileage'
        annualMileageUOM:
          $ref: '#/components/schemas/AnnualMileageUOM'
        nextInspectionDate:
          $ref: '#/components/schemas/NextInspectionDate'
        active:
          $ref: '#/components/schemas/Active'
      required:
        - externalRef
    VehicleCode:
      type: integer
      format: int32
      example: '1000001'
      description: Vehicle identifier
    VehicleDTO:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/VehicleCode'
        ownerCode:
          type: string
          maxLength: 255
          example: '1000365'
          description: Vehicle owner identifier
        registrationNumber:
          $ref: '#/components/schemas/RegistrationNumber'
        registrationDate:
          $ref: '#/components/schemas/RegistrationDate'
        vin:
          $ref: '#/components/schemas/VIN'
        vrn:
          type: string
          example: AA-123-AA
          maxLength: 255
          description: Vehicle Registration Number
        make:
          $ref: '#/components/schemas/Make'
        model:
          $ref: '#/components/schemas/Model'
        energy:
          $ref: '#/components/schemas/Energy'
        active:
          $ref: '#/components/schemas/Active'
        references:
          type: array
          maxItems: 1000
          items:
            description: Vehicle references
            $ref: '#/components/schemas/VehicleReferenceDTO'
    VehicleReferenceDTO:
      type: object
      properties:
        source:
          type: string
          example: ES_EQUITY
          maxLength: 20
          description: Reference source
        externalRef:
          $ref: '#/components/schemas/ExternalRef'
        countryCode:
          type: string
          example: ES
          maxLength: 255
          description: Reference country code
        lastModifiedDate:
          description: Date when the external reference was last modified.
          type: string
          example: '2024-05-02T10:00:00'
          pattern: >-
            ^([0-9]{4})-(?:[0-9]{2})-([0-9]{2})T([01][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])$
    Active:
      type: boolean
      example: 'true'
      description: true if vehicle is active
    Energy:
      type: string
      example: PETROL
      maxLength: 255
      description: Vehicle energy
    ExternalRef:
      type: string
      example: AAA123
      maxLength: 255
      description: Vehicle reference code of the source
    RegistrationNumber:
      type: string
      example: AA-123-AA
      maxLength: 255
      description: Vehicle registration number
    RegistrationDate:
      type: string
      format: date
      example: '2024-01-01'
      description: Vehicle registration date
    VIN:
      type: string
      example: 1HGCM82633A123456
      maxLength: 255
      description: Vehicle Identification Number
    Make:
      type: string
      example: Peugeot
      maxLength: 255
      description: Vehicle make
    Model:
      type: string
      example: '208'
      maxLength: 255
      description: Vehicle model
    PaginationDTO:
      type: object
      additionalProperties: false
      properties:
        next:
          type: string
          maxLength: 200
          description: Url for next page
          example: /vehicle-erm/v1/vehicles?pageNumber=3&pageSize=50
        previous:
          type: string
          maxLength: 200
          description: Url for previous page
          example: /vehicle-erm/v1/vehicles?pageNumber=1&pageSize=50
        pageTotal:
          type: integer
          format: int32
          example: '2'
          minimum: 0
          maximum: 1000
          description: Number total of page available
        totalElements:
          type: integer
          format: int32
          example: '200'
          minimum: 0
          maximum: 10000
          description: Number total of elements available
    TyreOptionsResponseDTO:
      type: object
      additionalProperties: false
      properties:
        tyreOptions:
          type: array
          maxItems: 1000
          items:
            description: Vehicle references
            $ref: '#/components/schemas/TyreOptionsDTO'
    TyreOptionsDTO:
      type: object
      additionalProperties: false
      properties:
        axlePosition:
          type: integer
          format: int32
          example: '1'
          description: Axle position of tyre
        width:
          type: string
          maxLength: 255
          example: '195'
          description: Width of tyre
        aspectRatio:
          type: string
          maxLength: 255
          example: '65'
          description: Aspect ratio of tyre
        constructionType:
          type: string
          maxLength: 255
          example: R
          description: Construction type of tyre
        diameter:
          type: string
          maxLength: 255
          example: '19'
          description: Diameter of tyre
        loadIndex:
          type: integer
          format: int32
          example: '91'
          description: Load index of tyre
        speedIndex:
          type: string
          maxLength: 255
          example: '19'
          description: Speed index of tyre
        winter:
          type: boolean
          example: false
          description: True if tyre is a winter tyre
        summer:
          type: boolean
          example: false
          description: True if tyre is a summer tyre
    VehicleCodeParam:
      type: integer
      format: int32
      example: '2'
      description: Vehicle code
    PageNumberParam:
      type: integer
      format: int32
      example: '2'
      minimum: 1
      maximum: 1000
      description: Number of the page requested, minimum 1
    PageSizeParam:
      type: integer
      format: int32
      example: '2'
      minimum: 1
      maximum: 1000
      description: Size of the page
    lastModifiedDateFromParam:
      type: string
      format: date-time
      example: '2024-05-02T10:00:00'
      description: Last modified date from, must have the format yyyy-MM-ddTHH:mm:ss
    lastModifiedDateToParam:
      type: string
      format: date-time
      example: '2024-05-02T10:00:00'
      description: Last modified date to, must have the format yyyy-MM-ddTHH:mm:ss
    RegistrationNumberParam:
      type: string
      example: AA-123-AA
      maxLength: 255
      description: Registration number
    RegistrationCountryCodeParam:
      type: string
      example: FR
      maxLength: 255
      description: Country code of registration
    ExternalRefQueryParam:
      type: string
      example: '1000045'
      description: Identifier of the external reference
      maxLength: 255
    SourceQueryParam:
      type: string
      example: GENES
      description: Source of the external reference
      maxLength: 255
    BadRequestDTO:
      type: object
      properties:
        errors:
          type: array
          minItems: 1
          items:
            type: object
            properties:
              error:
                type: string
                format: string
                description: Error message
              property:
                type: string
                format: string
                description: Name of the field affected by the error
    ForbiddenDTO:
      type: object
      properties:
        errors:
          type: array
          minItems: 1
          items:
            type: object
            properties:
              error:
                type: string
                format: string
                description: Error message
              property:
                type: string
                format: string
                description: Name of the field affected by the error
    InternalErrorDTO:
      type: object
      properties:
        error:
          type: string
          example: Unexpected error while booking the appointment
    UnauthorizedDTO:
      type: object
      properties:
        errors:
          type: array
          minItems: 1
          items:
            type: object
            properties:
              error:
                type: string
                format: string
                description: Error message
              property:
                type: string
                format: string
                description: Name of the field affected by the error
    VehiclesStateResponseDTO:
      type: object
      properties:
        pagination:
          description: Pagination information
          $ref: '#/components/schemas/PaginationDTO'
        vehicles:
          type: array
          maxItems: 1000
          items:
            description: Vehicles state information
            $ref: '#/components/schemas/VehicleStateDTO'
    VehicleStateDTO:
      type: object
      properties:
        code:
          description: Vehicle identifier
          type: string
          example: '100001'
          maxLength: 50
        mileage:
          $ref: '#/components/schemas/Mileage'
        mileageUOM:
          $ref: '#/components/schemas/MileageUOM'
        annualMileage:
          $ref: '#/components/schemas/AnnualMileage'
        annualMileageUOM:
          $ref: '#/components/schemas/AnnualMileageUOM'
        nextInspectionDate:
          $ref: '#/components/schemas/NextInspectionDate'
        references:
          description: List of external references associated with the vehicle
          type: array
          items:
            type: object
            properties:
              source:
                description: Source of the external reference
                type: string
                maxLength: 20
                example: GENES
              externalRef:
                description: Identifier of the external reference
                type: string
                maxLength: 255
                example: '12345678'
              countryCode:
                description: Country related to the external reference
                type: string
                maxLength: 255
                example: FR
              lastModifiedDate:
                description: Date when the external reference was last modified.
                type: string
                example: '2024-05-02T10:00:00'
                pattern: >-
                  ^([0-9]{4})-(?:[0-9]{2})-([0-9]{2})T([01][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])$
    Mileage:
      description: Vehicle mileage
      type: integer
      example: 120000
    MileageUOM:
      description: Vehicle mileage unit of measure
      type: string
      example: km
      maxLength: 255
    AnnualMileage:
      description: Vehicle annual mileage
      type: integer
      example: 20000
    AnnualMileageUOM:
      description: Vehicle annual mileage unit of measure
      type: string
      example: km
      maxLength: 255
    NextInspectionDate:
      description: Vehicle next inspection date
      type: string
      format: date
      example: '2028-09-10'
  responses:
    VehiclesResponseDTO:
      description: Vehicles
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VehiclesResponseDTO'
          examples:
            standardResponse:
              value:
                pagination:
                  next: /vehicle-erm/v1/vehicles?pageNumber=3&pageSize=50
                  previous: /vehicle-erm/v1/vehicles?pageNumber=1&pageSize=50
                  pageTotal: '3'
                  totalElements: '125'
                vehicles:
                  - code: '1000001'
                    ownerCode: '1000365'
                    registrationNumber: AA-123-AA
                    registrationDate: '2024-01-01'
                    vin: ''
                    vrn: ''
                    make: Peugeot
                    model: '208'
                    energy: PETROL
                    active: true
                    references:
                      - source: ES_EQUITY
                        externalRef: AAA123
                        countryCode: ES
                        lastModifiedDate: '2024-12-27T12:23:23'
    CreateVehiclesResponseDTO:
      description: Vehicles
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateVehiclesResponseDTO'
          examples:
            standardResponse:
              value:
                code: '1000293'
    TyreOptionsResponseDTO:
      description: Vehicle tyre options
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TyreOptionsResponseDTO'
          examples:
            standardResponse:
              value:
                tyreOptions:
                  - axlePosition: 1
                    width: '195'
                    aspectRatio: '65'
                    constructionType: R
                    diameter: '19'
                    loadIndex: 91
                    speedIndex: V
                    winter: true
                    summer: false
                  - axlePosition: 2
                    width: '195'
                    aspectRatio: '65'
                    constructionType: R
                    diameter: '19'
                    loadIndex: 91
                    speedIndex: V
                    winter: true
                    summer: false
                  - axlePosition: 2
                    width: '225'
                    aspectRatio: '45'
                    constructionType: R
                    diameter: '19'
                    loadIndex: 91
                    speedIndex: V
                    winter: true
                    summer: false
    InternalErrorDTO:
      description: An internal error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalErrorDTO'
          examples:
            internalError:
              summary: An internal error occurred
              value:
                errors:
                  - error: >-
                      An internal error occurred, please try again later. Thank
                      you for your understanding
    UnauthorizedDTO:
      description: The requester is not recognized by our system.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedDTO'
          examples:
            Unknown client id:
              summary: Unknown client id
              value:
                errors:
                  - error: Unknown client id, please contact our API service support
                    property: clientid
            Missing client id:
              summary: Missing client id
              value:
                errors:
                  - error: The client id is missing
                    property: clientid
            Bad credentials:
              summary: The credentials are wrong
              value:
                errors:
                  - error: The credentials are wrong
                    property: Authorization
            Missing credentials:
              summary: The credentials are missing
              value:
                errors:
                  - error: The credentials are missing
                    property: Authorization
    VehiclesStateResponseDTO:
      description: The vehicles state response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VehiclesStateResponseDTO'
          examples:
            standardResponse:
              summary: Vehicles state
              value:
                pagination:
                  next: /vehicle-erm/v1/vehicles/state?page=3&size=50
                  previous: /vehicle-erm/v1/vehicles/state?page=1&size=50
                  pageTotal: '3'
                  totalElements: '125'
                vehicles:
                  - code: '100001'
                    mileage: 120000
                    mileageUOM: km
                    annualMileage: 20000
                    annualMileageUOM: km
                    nextInspectionDate: '2028-09-10'
                    references:
                      - source: ES_EQUITY
                        externalRef: AAA123
                        countryCode: ES
                        lastModifiedDate: '2024-12-27T12:23:23'
