openapi: 3.1.0
info:
  title: FuelU2 Customer API
  description: >-
    API for handling customer data, relationships, and order interactions within
    the FuelU2 network.
  version: 1.0.0
  contact:
    name: FuelU2 API Support
    email: support@fuelu2.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://api.fuelu2.com
    description: Production server
security:
  - bearerAuth: []
paths:
  /Users/login:
    post:
      summary: User Login
      operationId: userLogin
      description: >-
        Authenticates a user and returns a token that must be included in the
        Authorization header for subsequent requests.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                Email:
                  type: string
                  example: user@example.com
                Method:
                  type: string
                  example: API Call
                Password:
                  type: string
                  example: password123
                UserAgent:
                  type: string
                  example: web
              required:
                - Email
                - Password
      responses:
        '200':
          description: Successful login
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: JWT token to be used in Authorization header.
                  userId:
                    type: string
                    description: ID of the authenticated user
  /Users/logout:
    post:
      summary: User Logout
      operationId: userLogout
      description: >-
        Logs out the currently authenticated user by invalidating their session
        token.
      tags:
        - Authentication
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                UserAgent:
                  type: string
                  example: web
              required:
                - UserAgent
      responses:
        '200':
          description: Successfully logged out
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Successfully logged out
  /Orders:
    post:
      summary: Create/Edit An Order
      operationId: createOrder
      description: >-
        Creates a new order with optional recurring settings and specified
        service quantities.
      tags:
        - Orders
      requestBody:
        required: true
        content:
          application/json-patch+json:
            schema:
              type: object
              properties:
                isBlitz:
                  type: boolean
                  example: true
                fuelT:
                  type: boolean
                  example: true
                fuelType:
                  type: string
                  example: Diesel
                driverId:
                  type: string
                  format: uuid
                  example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                maxFillAmount:
                  type: integer
                  example: 0
                previousOrderId:
                  type: string
                  example: ''
                recurring:
                  type: boolean
                  example: true
                referenceCustomer:
                  type: string
                  example: CustomerRef123
                recurringOrderCustomerId:
                  type: string
                  format: uuid
                  example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                serviceIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  example:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                days:
                  type: integer
                  example: 0
                serviceQuantity:
                  type: integer
                  example: 0
                subContractId:
                  type: string
                  format: uuid
                  example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                supplierDepotId:
                  type: string
                  format: uuid
                  example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                vehicleId:
                  type: string
                  format: uuid
                  example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                servicesWithQuantities:
                  type: array
                  items:
                    type: object
                    properties:
                      serviceId:
                        type: string
                        format: uuid
                        example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                      serviceQuantity:
                        type: integer
                        example: 0
      responses:
        '200':
          description: Success
  /Orders/paged:
    get:
      summary: Get A Paged Orders List
      operationId: getPagedOrders
      description: >-
        Retrieves a paginated list of orders with optional filters for date,
        status, customer, and more.
      tags:
        - Orders
      parameters:
        - name: Page
          in: query
          description: Page number
          required: false
          schema:
            type: integer
        - name: PageSize
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
        - name: CustomerId
          in: query
          description: Single customer ID
          required: false
          schema:
            type: string
            format: uuid
        - name: CustomerIds
          in: query
          description: List of customer IDs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: DateStart
          in: query
          description: Start date for order filtering
          required: false
          schema:
            type: string
            format: date-time
        - name: DateEnd
          in: query
          description: End date for order filtering
          required: false
          schema:
            type: string
            format: date-time
        - name: DriverIds
          in: query
          description: Filter by one or more driver IDs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: InProgress
          in: query
          description: Filter by in-progress status
          required: false
          schema:
            type: boolean
        - name: ProductIds
          in: query
          description: Filter by product IDs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: Status
          in: query
          description: Filter by single status code
          required: false
          schema:
            type: integer
            enum:
              - 0
              - 1
              - 2
              - 3
              - 4
              - 5
              - 6
              - 7
              - 8
              - 9
              - 10
              - 11
              - 12
              - 13
              - 14
              - 15
              - 16
              - 17
              - 18
        - name: Statuses
          in: query
          description: Filter by multiple status codes
          required: false
          schema:
            type: array
            items:
              type: integer
              enum:
                - 0
                - 1
                - 2
                - 3
                - 4
                - 5
                - 6
                - 7
                - 8
                - 9
                - 10
                - 11
                - 12
                - 13
                - 14
                - 15
                - 16
                - 17
                - 18
        - name: SubContractIds
          in: query
          description: Filter by subcontract IDs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: SupplierDepotIds
          in: query
          description: Filter by supplier depot IDs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: SupplierId
          in: query
          description: Filter by supplier ID
          required: false
          schema:
            type: string
            format: uuid
        - name: VehicleIds
          in: query
          description: Filter by vehicle IDs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: Text
          in: query
          description: Free-text search
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  total:
                    type: integer
                    description: Total number of matching records
  /Orders/renewOrder:
    post:
      summary: Renew An Existing Order
      operationId: renewOrder
      description: Renews an existing order by specifying its ID and creation timestamp.
      tags:
        - Orders
      requestBody:
        required: true
        content:
          application/json-patch+json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  example: 0
              required:
                - id
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Order renewed successfully
  /Orders/cancel:
    post:
      summary: Cancel An Existing Order
      operationId: cancelOrder
      description: >-
        Cancels an existing order by specifying its ID, creation timestamp, and
        reason.
      tags:
        - Orders
      requestBody:
        required: true
        content:
          application/json-patch+json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  example: 0
                reason:
                  type: string
                  example: Customer request
              required:
                - id
                - reason
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Order cancelled successfully
  /Drivers:
    post:
      summary: Create/Edit A Driver
      operationId: createDriver
      description: Creates a new driver record for a specific customer.
      tags:
        - Drivers
      security:
        - bearerAuth: []
      parameters:
        - name: AllowBlitz
          in: query
          description: Whether the driver is allowed to blitz
          required: false
          schema:
            type: boolean
        - name: CustomerId
          in: query
          description: CustomerId
          required: true
          schema:
            type: string
            format: uuid
        - name: FirstName
          in: query
          description: FirstName
          required: true
          schema:
            type: string
        - name: IdPassport
          in: query
          description: IdPassport
          required: true
          schema:
            type: string
        - name: LastName
          in: query
          description: LastName
          required: true
          schema:
            type: string
        - name: LicenseExpiryDate
          in: query
          description: LicenseExpiryDate
          required: true
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Driver created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Driver created successfully
    delete:
      summary: Delete A Driver
      description: >-
        Deletes an existing driver by specifying their unique ID and creation
        timestamp.
      tags:
        - Drivers
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json-patch+json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                createdOn:
                  type: string
                  format: date-time
                  example: '2025-10-07T11:28:36.700Z'
              required:
                - id
                - createdOn
      responses:
        '200':
          description: Driver deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Driver deleted successfully
  /Drivers/paged:
    get:
      summary: Get A Paged Drivers List
      operationId: getPagedDrivers
      description: >-
        Retrieves a paginated list of drivers with optional filters for
        customer, subcontract, and search text.
      tags:
        - Drivers
      parameters:
        - name: Page
          in: query
          description: Page number for pagination, default 1
          required: false
          schema:
            type: integer
            format: int32
            example: 1
        - name: PageSize
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
            format: int32
            example: 20
        - name: CustomerId
          in: query
          description: Filter drivers by a specific customer ID
          required: false
          schema:
            type: string
            format: uuid
            example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        - name: SubContractsId
          in: query
          description: Filter drivers by one or more subcontractor IDs
          required: false
          schema:
            type: array
            items:
              type: string
            example:
              - sub_1234
              - sub_5678
        - name: Text
          in: query
          description: Free-text search on driver details
          required: false
          schema:
            type: string
            example: John
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  total:
                    type: integer
                    description: Total number of matching records
                  message:
                    type: string
                    example: Drivers fetched successfully
  /Vehicles:
    post:
      summary: Create/Edit A Vehicle
      operationId: createVehicle
      description: >-
        Creates a new vehicle record with registration details and capacity
        information.
      tags:
        - Vehicles
      security:
        - bearerAuth: []
      parameters:
        - name: AuxiliaryCapacity
          in: query
          description: Auxiliary capacity of the vehicle
          required: false
          schema:
            type: integer
            format: int32
        - name: Capacity
          in: query
          description: Main capacity of the vehicle
          required: false
          schema:
            type: integer
            format: int32
        - name: DriverId
          in: query
          description: ID of the assigned driver
          required: false
          schema:
            type: string
            format: uuid
        - name: Make
          in: query
          description: Vehicle make/manufacturer
          required: false
          schema:
            type: string
        - name: Model
          in: query
          description: Vehicle model
          required: false
          schema:
            type: string
        - name: ProductId
          in: query
          description: Associated product ID
          required: false
          schema:
            type: string
            format: uuid
        - name: RegistrationExpiryDate
          in: query
          description: Registration expiry date
          required: false
          schema:
            type: string
            format: date-time
        - name: RegistrationFile.ContentType
          in: query
          description: Content type of the registration file
          required: false
          schema:
            type: string
        - name: RegistrationFile.Data
          in: query
          description: Base64 encoded registration file data
          required: false
          schema:
            type: string
            format: byte
        - name: RegistrationFile.FileName
          in: query
          description: Name of the registration file
          required: false
          schema:
            type: string
        - name: RegistrationNumber
          in: query
          description: Vehicle registration number
          required: false
          schema:
            type: string
        - name: SubContractId
          in: query
          description: Associated subcontract ID
          required: false
          schema:
            type: string
            format: uuid
        - name: Year
          in: query
          description: Vehicle year
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Vehicle created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Vehicle created successfully
    delete:
      summary: Delete A Vehicle
      description: >-
        Deletes an existing vehicle by specifying its unique ID and creation
        timestamp.
      tags:
        - Vehicles
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json-patch+json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
              required:
                - id
      responses:
        '200':
          description: Vehicle deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
  /Vehicles/paged:
    get:
      summary: Get A Paged Vehicles List
      operationId: getPagedVehicles
      description: >-
        Retrieves a paginated list of vehicles with optional filters for
        customer, product, subcontract, and search text.
      tags:
        - Vehicles
      security:
        - bearerAuth: []
      parameters:
        - name: Page
          in: query
          description: Page number for pagination
          required: false
          schema:
            type: integer
            format: int32
        - name: PageSize
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
            format: int32
        - name: PermanentDriverOnly
          in: query
          description: Filter by vehicles with permanent drivers only
          required: false
          schema:
            type: boolean
        - name: ProductId
          in: query
          description: Filter by product ID
          required: false
          schema:
            type: string
            format: uuid
        - name: SubContractIds
          in: query
          description: Filter by one or more subcontract IDs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: Text
          in: query
          description: Free-text search on vehicle details
          required: false
          schema:
            type: string
        - name: RegistrationFile.FileName
          in: query
          description: Filter by registration file name
          required: false
          schema:
            type: string
        - name: RegistrationFile.Id
          in: query
          description: Filter by registration file ID
          required: false
          schema:
            type: string
            format: uuid
        - name: RegistrationFile.CreatedOn
          in: query
          description: Filter by registration file creation date
          required: false
          schema:
            type: string
            format: date-time
        - name: RegistrationNumber
          in: query
          description: Filter by registration number
          required: false
          schema:
            type: string
        - name: Year
          in: query
          description: Filter by vehicle year
          required: false
          schema:
            type: integer
            format: int32
        - name: Id
          in: query
          description: Filter by vehicle ID
          required: false
          schema:
            type: string
            format: uuid
        - name: CreatedOn
          in: query
          description: Filter by creation date
          required: false
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        auxillaryCapacity:
                          type: integer
                        capacity:
                          type: integer
                        currentLeasePlan:
                          type: string
                        deleted:
                          type: boolean
                        fleetNumber:
                          type: string
                        hasWarrantyOrMaintenance:
                          type: boolean
                        make:
                          type: string
                        model:
                          type: string
                        productId:
                          type: string
                          format: uuid
                        registrationNumber:
                          type: string
                        vinNumber:
                          type: string
                        warrantyExpiryDate:
                          type: string
                          format: date-time
                        warrantyExclusions:
                          type: string
                        year:
                          type: integer
                        customer:
                          type: object
                        driver:
                          type: object
                        subContractNames:
                          type: array
                          items:
                            type: string
                        subContractVehicleMappings:
                          type: array
                          items:
                            type: object
                        registrationExpiryDate:
                          type: string
                          format: date-time
                        registrationFile:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                            createdOn:
                              type: string
                              format: date-time
                            contentType:
                              type: string
                            fileName:
                              type: string
                  page:
                    type: integer
                  pageCount:
                    type: integer
                  total:
                    type: integer
                    description: Total number of matching records
  /SubContracts:
    post:
      summary: Create/Edit a SubContract
      operationId: createSubContract
      description: >
        Creates a new subcontract or updates an existing one.

        The `id` field can be omitted or set to null when adding a new
        subcontract.
      tags:
        - Subcontracts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                markup:
                  type: number
                  example: 0
                name:
                  type: string
                  example: Example SubContract
                driverIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  example:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                userIds:
                  type: array
                  items:
                    type: string
                  example:
                    - string
                vehicleIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  example:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '200':
          description: Successfully created or updated the subcontract
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: SubContract created successfully
  /SubContracts/paged:
    get:
      summary: Get a Paged Subcontracts List
      operationId: getPagedSubContracts
      description: >-
        Retrieves a paginated list of subcontracts with optional filters for
        customer, driver, vehicle, and search text.
      tags:
        - Subcontracts
      parameters:
        - name: Page
          in: query
          description: Page number for pagination
          required: false
          schema:
            type: integer
            format: int32
            example: 1
        - name: PageSize
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
            format: int32
            example: 20
        - name: CustomerId
          in: query
          description: Filter by single customer ID
          required: false
          schema:
            type: string
            format: uuid
        - name: CustomerIds
          in: query
          description: Filter by multiple customer IDs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: DriverIds
          in: query
          description: Filter by driver IDs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: UserIds
          in: query
          description: Filter by user IDs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: VehicleIds
          in: query
          description: Filter by vehicle IDs
          required: false
          schema:
            type: array
            items:
              type: string
        - name: Text
          in: query
          description: Free-text search across subcontract names
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved subcontract list
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        availableCredit:
                          type: number
                        balance:
                          type: number
                        customerAvailableCredit:
                          type: number
                        customerName:
                          type: string
                        fuelU2ToManageMargin:
                          type: boolean
                        subcontractBalance:
                          type: number
                        inProgressBalance:
                          type: number
                        name:
                          type: string
                        number:
                          type: string
                        drivers:
                          type: array
                          items:
                            type: string
                        users:
                          type: array
                          items:
                            type: string
                        vehicles:
                          type: array
                          items:
                            type: string
                        prices:
                          type: array
                          items:
                            type: object
                            properties:
                              productId:
                                type: string
                                format: uuid
                              productName:
                                type: string
                              price:
                                type: number
                              productOutOfStock:
                                type: boolean
                  page:
                    type: integer
                  pageCount:
                    type: integer
                  total:
                    type: integer
  /SubContractMarkups:
    post:
      summary: Adjust Subcontract Markups
      operationId: subcontractMarkups
      description: >-
        Adjusts the markup for a specific product within a subcontract. The
        `subContractId` is required to identify which subcontract’s markup is
        being modified.
      tags:
        - Subcontracts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - subContractId
              properties:
                adjustment:
                  type: number
                  example: 0
                productId:
                  type: string
                  format: uuid
                  example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                subContractId:
                  type: string
                  format: uuid
                  example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '200':
          description: Successfully adjusted subcontract markup
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Markup adjustment saved successfully
  /SubContractOrders:
    post:
      summary: Place Subcontract Order
      operationId: subcontractOrders
      description: >
        Creates a new subcontract order.

        The `customerId` and `subContractId` are automatically assigned on the
        backend.
      tags:
        - Subcontracts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  description: Optional when creating a new order
                orderDate:
                  type: string
                  format: date-time
                  example: '2025-10-14T06:15:00.000Z'
                reference:
                  type: string
                  example: PO-456
                items:
                  type: array
                  items:
                    type: object
                    properties:
                      productId:
                        type: string
                        format: uuid
                        example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                      quantity:
                        type: number
                        example: 1000
                      price:
                        type: number
                        example: 25.5
      responses:
        '200':
          description: Successfully placed subcontract order
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  message:
                    type: string
                    example: Subcontract order created successfully
  /SubContractOrders/paged:
    get:
      summary: List SubContract Orders (Paged)
      operationId: getPagedSubcontractOrders
      description: >
        Retrieves a paginated list of subcontract orders.

        The `customerId` and `subContractId` are set automatically on the
        backend.
      tags:
        - Subcontracts
      parameters:
        - name: Page
          in: query
          schema:
            type: integer
            format: int32
          description: Page number
        - name: PageSize
          in: query
          schema:
            type: integer
            format: int32
          description: Number of items per page
        - name: Text
          in: query
          schema:
            type: string
          description: Search text
        - name: Status
          in: query
          schema:
            type: string
          description: Optional order status filter
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                        number:
                          type: string
                          example: SO-1001
                        status:
                          type: string
                          example: Pending
                        total:
                          type: number
                          example: 2500.5
                  page:
                    type: integer
                    example: 1
                  pageCount:
                    type: integer
                    example: 10
                  total:
                    type: integer
                    example: 100
  /Files/{id}:
    get:
      summary: Get Proforma
      operationId: getProforma
      description: >-
        Retrieves a proforma document using the order's
        `customerSubContractInvoiceId`.
      tags:
        - Subcontracts
      parameters:
        - name: id
          in: path
          description: The unique ID of the file or proforma
          required: true
          schema:
            type: string
            example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: string
                example: File retrieved successfully
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
