openapi: 3.1.0
info:
  title: Real Time Tracking API
  description: Real Time Tracking API - Managed by Real Time Tracking Team
  version: 2.0.0
  contact:
    name: Bettermile - Real Time Tracking Team
    email: tracking@bettermile.com
servers:
  - url: https://data-solutions-v2.bettermile.com
    description: Production Environment
tags: []
paths:
  /sm/api/v2/parcel-tracking-subscribe:
    post:
      tags:
        - Parcel Monitoring Service
      description: >-
        This endpoint allows you to subscribe to tracking updates for a specific
        parcel. It provides detailed information about the parcel’s status,
        ensuring that it can be tracked throughout its journey.
      operationId: parcelTrackingSubscribe
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequestBody'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParcelTrackingUpdate'
        '401':
          description: Unauthorized
        '404':
          description: Parcel not found
        '500':
          description: Server error
  /sm/api/v2/latest-parcel-status/{jobInternalId}: {}
  /md/api/v2/tour/{internalId}/driver-location: {}
  /pre-eta/api/v2/loading-zones: {}
components:
  schemas:
    SubscriptionRequestBody:
      type: object
      properties:
        parcelNumber:
          type: string
        tenantId:
          type: string
      required:
        - parcelNumber
        - tenantId
    ParcelTrackingUpdate:
      type: object
      properties:
        parcelNumber:
          type: string
        tenantId:
          type: string
        status:
          $ref: '#/components/schemas/Status'
      required:
        - parcelNumber
        - tenantId
    Status:
      type: object
      properties:
        position:
          $ref: '#/components/schemas/Position'
        etaTimestampMin:
          type: string
          format: date-time
          description: Earliest estimated time of arrival
          example: '2022-01-15T14:15:00Z'
        etaTimestampMax:
          type: string
          format: date-time
          description: Latest estimated time of arrival
          example: '2022-01-15T14:45:00Z'
        remainingStops:
          type: integer
          description: Number of driver's remaining stops before delivery of the parcel
        type:
          $ref: '#/components/schemas/ParcelStatusType'
      required:
        - position
        - etaTimestampMin
        - etaTimestampMax
        - remainingStops
        - type
    Position:
      type: object
      properties:
        lat:
          type: number
          description: Geographic latitude coordinate
          example: 50.9098881
        lng:
          type: number
          description: Geographic longitude coordinate
          example: 9.5806327
      required:
        - lat
        - lng
    ParcelStatusType:
      type: string
      enum:
        - OUT_FOR_DELIVERY
        - DELIVERED
        - NOT_DELIVERED
        - COLLECTED
        - NOT_COLLECTED
        - PICKED_UP
        - NOT_PICKED_UP
    ParcelStatusResponse:
      type: object
      properties:
        parcelNumber:
          type: string
        jobInternalId:
          type: string
          format: uuid
        depotId:
          type: string
        internalDepotId:
          type: string
        vehicleNumber:
          type: string
        tenantId:
          type: string
        type:
          $ref: '#/components/schemas/ParcelStatusType'
        polledAt:
          type: string
          format: date-time
        detailType:
          type: string
        deliveredAt:
          type: string
          format: date-time
        positionLat:
          type: number
          description: Geographic latitude coordinate
          example: 50.9098881
        positionLng:
          type: number
          description: Geographic longitude coordinate
          example: 9.5806327
        etaTimestamp:
          type: string
          format: date-time
        remainingStops:
          type: string
        tourInternalId:
          type: string
          format: uuid
        tourMode:
          $ref: '#/components/schemas/TourMode'
        upperBound:
          type: string
          format: date-time
        lowerBound:
          type: string
          format: date-time
      required:
        - jobInternalId
        - depotId
        - internalDepotId
        - vehicleNumber
        - type
        - polledAt
    TourMode:
      type: string
      enum:
        - REGULAR
        - SHADOWED
    DriverLocationResponse:
      type: object
      properties:
        coordinates:
          $ref: '#/components/schemas/Position'
        timestamp:
          type: string
          format: date-time
      required:
        - coordinates
        - timestamp
    PreEtaTimeframeResponse:
      type: object
      properties:
        timeframeList:
          type: array
          items:
            $ref: '#/components/schemas/PreEtaTimeframe'
      required:
        - timeframeList
    PreEtaTimeframe:
      type: object
      properties:
        depotId:
          type: string
          example: NL2500
        zipCode:
          type: string
        tenantId:
          type: string
        weekday:
          type: string
          enum:
            - Monday
            - Tuesday
            - Wednesday
            - Thursday
            - Friday
            - Saturday
            - Sunday
        predictions:
          type: array
          items:
            $ref: '#/components/schemas/Predictions'
      required:
        - depotId
        - zipCode
        - tenantId
        - weekday
        - predictions
    Predictions:
      type: object
      properties:
        coverageModel:
          type: string
          enum:
            - '70'
            - '75'
            - '80'
            - '90'
        lowerBound:
          type: string
          format: time
          example: '10:30:00'
        upperBound:
          type: string
          format: time
          example: '12:30:00'
      required:
        - coverageModel
        - lowerBound
        - upperBound
    LoadingZonesConfig:
      type: object
      properties:
        tenant_id:
          type: string
          example: gls-de
        internal_depot_id:
          type: string
          example: '35'
      required:
        - tenant_id
        - internal_depot_id
    LoadingZonesJob:
      type: object
      properties:
        external_job_id:
          type: string
          example: '90437913133'
        lat:
          type: number
          description: Geographic latitude coordinate
          example: 50.9098881
        lng:
          type: number
          description: Geographic longitude coordinate
          example: 9.5806327
      required:
        - external_job_id
        - lat
        - lng
    LoadingZonesRequestBody:
      type: object
      properties:
        config:
          $ref: '#/components/schemas/LoadingZonesConfig'
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/LoadingZonesJob'
      required:
        - config
        - jobs
    LoadingZones:
      type: object
      properties:
        zone_id:
          type: string
          enum:
            - A
            - B
            - C
        lower_bound:
          type: string
          format: time
          example: '10:30:00'
        upper_bound:
          type: string
          format: time
          example: '12:30:00'
        external_job_ids:
          type: array
          items:
            type: string
            example: '90437913133'
      required:
        - zone_id
        - lower_bound
        - upper_bound
        - external_job_ids
    LoadingZonesResponse:
      type: object
      properties:
        config:
          $ref: '#/components/schemas/LoadingZonesConfig'
        zones:
          type: array
          items:
            $ref: '#/components/schemas/LoadingZones'
      required:
        - config
        - zones
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerToken: []
