Locus OrderServiceability API

openapi: 3.2.0
info:
  title: Locus HomebaseMaster Order Serviceability API
  description: Manage your deliveries with the Locus API
  version: 1.0.0
servers:
- url: https://oms.locus-api.com/v1
tags:
- name: OrderServiceability
paths:
  /client/{clientId}/get-slots:
    parameters:
    - $ref: '#/components/parameters/ClientIdParam'
    post:
      summary: Get available future slots for the given order
      operationId: getServiceableSlots
      tags:
      - OrderServiceability
      responses:
        '200':
          description: Information with all the available future slots
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSlotsResponse'
      security:
      - locusauth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetServiceableSlotsRequest'
        description: Order Details
        required: true
components:
  schemas:
    SlotSelectionStrategy:
      type: string
      enum:
      - EARLIEST_START
      - LEAST_ENERGY_DELTA
      - LEAST_SCORE
      - CUSTOMER_CHOSEN
      - CUSTOMER_CHOSEN_EARLIEST
      - CUSTOMER_CHOSEN_LEAST_SCORE
      - CUSTOMER_CHOSEN_LEAST_ENERGY_DELTA
    MinimalLatLng:
      description: A latitude, longitude pair
      required:
      - lat
      - lng
      properties:
        lat:
          type: number
          format: double
        lng:
          type: number
          format: double
    TimeSlot:
      $ref: https://swagger.locus-api.com/slots.yaml#/definitions/TimeSlot
    TransitCode:
      properties:
        code:
          type: string
        description:
          type: string
    Weight:
      description: Weight of order
      required:
      - value
      - unit
      properties:
        value:
          description: Value of the weight in the given unit.
          type: string
        unit:
          $ref: '#/components/schemas/WeightUnit'
    AmountTransaction:
      description: Transaction of an amount.
      properties:
        refId:
          description: id of amount transaction
          type: string
        amount:
          $ref: '#/components/schemas/Amount'
        net:
          $ref: '#/components/schemas/BaseAmount'
        gross:
          $ref: '#/components/schemas/BaseAmount'
        exchangeType:
          description: Type of transaction.
          type: string
          enum:
          - COLLECT
          - GIVE
          - NONE
    OrderType:
      $ref: https://swagger.locus-api.com/oms.yaml#/definitions/OrderType
    DlcTimeSlot:
      description: Time slot for a delivery linked checkout (DLC)
      required:
      - score
      properties:
        slotId:
          description: Id for the suggest slot for order
          type: string
        customerSlotId:
          description: Id of the customer slot
          type: string
        timeSlot:
          description: Time slot for the task
          $ref: '#/components/schemas/TimeSlot'
        score:
          description: Score which signifies the difficulty of servicing the task. The higher the number, the more is the difficulty.
          type: integer
          format: int32
          default: 1
        energyDelta:
          description: Energy delta which signifies energy change by servicing the task. The higher the number, the more is the difficulty.
          type: number
          format: double
        arrivedEta:
          type: string
          format: date-time
        completedEta:
          type: string
          format: date-time
        averageSpeed:
          type: number
          format: double
          description: Average tour speed for this promise route
        plannedTreesOffset:
          description: Denotes the trees required per year to offset planned carbon emissions for tour.
          type: number
          format: double
        capacityMetadata:
          $ref: '#/components/schemas/CapacityMetadata'
    CapacityMetadata:
      properties:
        taskCount:
          type: integer
          format: int32
          default: 0
        utilisedVolume:
          type: number
          format: double
          default: 0
        utilisedWeight:
          type: number
          format: double
          default: 0
    LineItemPart:
      description: A part of the line item which can be shipped separately
      required:
      - volume
      properties:
        id:
          type: string
        volume:
          $ref: '#/components/schemas/Volume'
        weight:
          $ref: '#/components/schemas/Weight'
        originalWeight:
          $ref: '#/components/schemas/Weight'
        dimensions:
          $ref: '#/components/schemas/OmsDimensions'
        piecesCount:
          type: integer
          format: int32
          default: 1
    LineItemSummary:
      properties:
        totalWeight:
          description: Sum of individual weights of all parts
          $ref: '#/components/schemas/Weight'
        totalVolume:
          description: Sum of individual volumes of all parts
          $ref: '#/components/schemas/Volume'
        totalReweighCount:
          type: integer
          format: int32
          default: 0
    MinimalLineItem:
      description: A single item contained in the order
      required:
      - name
      - quantity
      properties:
        id:
          description: An identifier for the SKU. If provided, details related to line item will be populated using sku master of the client
          type: string
        lineItemId:
          description: An identifier for the line item.
          type: string
        skuId:
          description: An identifier for the line item.
          type: string
        packId:
          description: A unique identifier of the line item, this is different from sku id. This would be unique across orders and only one qunatity of line item can exist with this id.
          type: string
        name:
          description: Name of the item
          type: string
        description:
          description: description of the item
          type: string
        handlingUnit:
          $ref: '#/components/schemas/HandlingUnitEnum'
          default: QUANTITY
        quantity:
          description: Quantity of the item
          type: integer
          format: int32
          default: 0
        quantityUnit:
          type: string
        price:
          $ref: '#/components/schemas/Amount'
        commodityCode:
          $ref: '#/components/schemas/TransitCode'
        parts:
          type: array
          items:
            $ref: '#/components/schemas/LineItemPart'
        customProperties:
          description: Additional properties which clients wants to have along with standard entity properties
          type: object
          additionalProperties:
            type: string
        summary:
          description: Summarized data of all line item parts
          $ref: '#/components/schemas/LineItemSummary'
        totalVolume:
          description: total volume of the line item multiplied by it's quantity
          $ref: '#/components/schemas/Volume'
        totalWeight:
          description: total weight of the line item multiplied by it's quantity
          $ref: '#/components/schemas/Weight'
        handlingUnits:
          type: array
          items:
            $ref: '#/components/schemas/HandlingUnitEnum'
        boxDetailSummary:
          $ref: '#/components/schemas/BoxDetailSummary'
        canRiderEdit:
          description: flag to denote whether the rider is allowed to edit the line item
          type: boolean
          default: true
    BoxDetailSummary:
      properties:
        totalCases:
          type: integer
          format: int32
        totalPieces:
          type: integer
          format: int32
        quantityUnit:
          type: string
        boxUnit:
          type: string
    BaseAmount:
      description: Amount value of an item
      properties:
        amount:
          type: number
          format: double
    GetSlotsResponse:
      description: Response with available time slots for the drop
      required:
      - slots
      properties:
        id:
          description: Order id if provided
          type: string
        slots:
          description: List of available time slots for the drop
          type: array
          items:
            $ref: '#/components/schemas/DlcTimeSlot'
        bestSlot:
          description: Best available slot based on configured strategy
          $ref: '#/components/schemas/DlcTimeSlot'
    LocationSource:
      description: location provider source.
      type: string
      enum:
      - LOCATION_MASTER
    OmsDimensions:
      description: Dimensions of an item
      properties:
        length:
          description: Length of the item in meters
          type: number
          format: double
        breadth:
          description: Breadth of the item in meters
          type: number
          format: double
        height:
          description: Height of the item in meters
          type: number
          format: double
        unit:
          $ref: '#/components/schemas/LengthUnit'
    Amount:
      description: Amount of an item
      properties:
        amount:
          type: number
          format: double
        currency:
          type: string
          description: Currency for the amount. Value should be one of the active codes of official ISO 4217 currency names. Examples are INR, USD, AED, GBP etc
        symbol:
          type: string
          description: A symbol for the currency. If missing, will default to currency string
    MinimalContactPoint:
      description: Contact point at a visit location.
      properties:
        name:
          description: Name of contact
          type: string
        number:
          description: Number for contact person
          type: string
        alternateNumber:
          description: Alternate number for contact person
          type: string
        email:
          description: Email of contact person
          type: string
        language:
          description: Preferred communication language
          type: string
          default: en-US
    HandlingUnitEnum:
      description: delivery handling units to identify deliverable field
      type: string
      enum:
      - QUANTITY
      - WEIGHT
      - VOLUME
    WeightUnit:
      description: Unit for weight
      type: string
      enum:
      - MG
      - G
      - KG
      - T
      - OZ
      - LB
    Volume:
      description: Volume of an item
      required:
      - value
      - unit
      properties:
        value:
          description: Value of the volume in the given unit.
          type: string
        unit:
          $ref: '#/components/schemas/VolumeUnit'
    VolumeUnit:
      description: Unit for volume
      type: string
      enum:
      - CMM
      - CCM
      - CC
      - CM
      - M3
      - CIN
      - CI
      - CFT
      - CF
      - CYD
      - IC
      - TC
      - L
    GetServiceableSlotsRequest:
      description: Get Serviceable Slot request
      required:
      - teamId
      - type
      - homebaseId
      properties:
        clientId:
          description: Id of the client to which this entity belongs to
          type: string
        id:
          description: A unique identifier for the order
          type: string
        customProperties:
          description: Additional properties which clients wants to have along with standard entity properties
          type: object
          additionalProperties:
            type: string
        teamId:
          description: Team of carrier client to consider for this order assignment
          type: string
        skills:
          description: List of skills
          type: array
          items:
            type: string
        homebaseId:
          description: Master id for the homebase / warehouse
          type: string
        homebaseTransactionDuration:
          description: Duration required for transaction at the pickup location, in seconds
          type: integer
          format: int32
        locationId:
          description: Master location id for the drop location
          type: string
        transactionDuration:
          description: Duration required for transaction at the drop location, in seconds
          type: integer
          format: int32
        contactPoint:
          $ref: '#/components/schemas/MinimalContactPoint'
        priority:
          description: Priority of the order
          type: integer
          format: int32
        date:
          type: string
          description: Date as String in format "YYYY-MM-DD", indicates starting date from which serviceable slots are fetched
        category:
          description: order category
          type: string
        riderId:
          type: string
        type:
          $ref: '#/components/schemas/OrderType'
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/MinimalLineItem'
        locationAddress:
          $ref: '#/components/schemas/StructuredAddress'
        latLng:
          $ref: '#/components/schemas/MinimalLatLng'
        amountTransaction:
          $ref: '#/components/schemas/AmountTransaction'
        volume:
          $ref: '#/components/schemas/Volume'
        weight:
          $ref: '#/components/schemas/Weight'
        daysToQueryFor:
          description: number of days indicates days in future for serviceable slots to be fetched
          type: integer
          format: int32
        creationTime:
          description: Timestamp for when the get slots request made, using the standard ISO 8601 format
          type: string
          format: date-time
        slotSelectionStrategy:
          $ref: '#/components/schemas/SlotSelectionStrategy'
        preferredSlotIds:
          description: List of slots ids chosen by customer
          type: array
          items:
            type: string
    StructuredAddress:
      description: A real world address
      properties:
        id:
          description: An id for the address
          type: string
        placeName:
          description: Name of the place
          type: string
        localityName:
          description: Name of the locality if available
          type: string
        formattedAddress:
          description: Text representation of the address.
          type: string
        subLocalityName:
          description: Name of the sub-locality if available
          type: string
        pincode:
          description: Zipcode for the address
          type: string
        city:
          description: City of the address
          type: string
        state:
          description: State of the address
          type: string
        countryCode:
          description: Country code to uniquely identify the country
          type: string
        locationType:
          description: Possible values currently are STANDALONE_APARTMENT, GATED_COMMUNITY, INDEPENDENT_PREMISES
          type: string
        placeHash:
          description: Hashed value of placeName for internal use
          type: string
        locationSource:
          $ref: '#/components/schemas/LocationSource'
        locationName:
          description: Location name to be populated from location entity
          type: string
    LengthUnit:
      description: Unit for length
      type: string
      enum:
      - MM
      - CM
      - M
      - IN
      - FT
      - YD
      - KM
      - MI
  parameters:
    ClientIdParam:
      name: clientId
      in: path
      description: Id of the client
      required: true
      schema:
        type: string
  securitySchemes:
    locusauth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization