openapi: 3.0.4
info:
  title: FirstMile REST Tracking API
  version: '1.0'
  description: API for tracking shipments through FirstMile's logistics network.
servers:
  - url: >-
      https://tracking-rest-api-test-dzfbetgsepgkfrh5.westus-01.azurewebsites.net
    description: Test server
  - url: https://trackingapi.firstmile.com
    description: Production server
security:
  - Bearer: []
paths:
  /Tracking/v1/{trackingNumber}:
    get:
      summary: Get tracking information for a shipment
      description: >-
        Retrieves detailed tracking events and shipment information for the
        provided tracking number.
      operationId: getTrackingInfo
      tags:
        - Tracking
      security:
        - Bearer: []
      parameters:
        - name: trackingNumber
          in: path
          required: true
          description: The tracking number to retrieve information for
          schema:
            type: string
            example: '123456789'
        - name: TechPartnerId
          in: query
          required: false
          description: Optional TechPartnerId supplied by FirstMile
          schema:
            type: string
      responses:
        '200':
          description: Tracking information successfully retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackingResponse'
              examples:
                successful_tracking:
                  summary: Successful tracking response with events
                  value:
                    trackingNumber: '123456789'
                    airwayBill: AWB987654321
                    shipmentAddress:
                      companyName: FirstMile Inc.
                      name: John Doe
                      address1: 123 Main St
                      address2: Suite 100
                      address3: null
                      city: Salt Lake City
                      region: Utah
                      regionCode: UT
                      country: United States
                      countryCode: US
                      email: john.doe@example.com
                      phoneNumber: +1-555-1234
                      residential: false
                      residentialSpecified: true
                      deliveryPoint: Front Door
                    weightLbs: 2.5
                    processedDate: '2023-08-01T10:00:00Z'
                    events:
                      - eventDatetime: '2023-08-01T08:00:00Z'
                        eventSource: IFS
                        eventDescription: Package received at facility
                        eventCode: 100
                        eventCodeAsString: RECEIVED
                        actionCode: A1
                        reasonCode: R1
                        deliveryAttributeCode: DA1
                        eventLocation:
                          companyName: FirstMile Facility
                          name: Receiving Dock
                          address1: 456 Warehouse Rd
                          city: Salt Lake City
                          region: Utah
                          regionCode: UT
                          country: United States
                          countryCode: US
                          residential: false
                          residentialSpecified: true
                          deliveryPoint: Dock 3
                      - eventDatetime: '2023-08-02T14:30:00Z'
                        eventSource: DHL
                        eventDescription: Package in transit
                        eventCode: 200
                        eventCodeAsString: IN_TRANSIT
                        eventLocation:
                          city: Denver
                          region: Colorado
                          regionCode: CO
                          country: United States
                          countryCode: US
                    errors: []
                    carrier: FirstMile
                    trackingURL: https://trackingapi.firstmile.com/track/123456789
                    deliveryDateEstimated: '2023-08-05'
                    deliveryDateMax: '2023-08-07'
                    deliveryDateMin: '2023-08-04'
                    podImageURLSBase64: []
                    serviceLevel: Ground
            text/json:
              schema:
                $ref: '#/components/schemas/TrackingResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/TrackingResponse'
        '400':
          description: >-
            Bad Request - Invalid tracking number format or missing required
            parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                invalid_tracking_number:
                  summary: Invalid tracking number format
                  value:
                    type: https://trackingapi.firstmile.com/errors/invalid-request
                    title: Invalid Request
                    status: 400
                    detail: The tracking number provided has an invalid format
                    instance: /Tracking/v1/invalid123
        '401':
          description: Unauthorized - Invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                unauthorized:
                  summary: Missing or invalid bearer token
                  value:
                    type: https://trackingapi.firstmile.com/errors/unauthorized
                    title: Unauthorized
                    status: 401
                    detail: Bearer token is missing or invalid
                    instance: /Tracking/v1/123456789
        '404':
          description: Not Found - Tracking number does not exist in the system
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                tracking_not_found:
                  summary: Tracking number not found
                  value:
                    type: https://trackingapi.firstmile.com/errors/not-found
                    title: Tracking Number Not Found
                    status: 404
                    detail: No shipment found with the provided tracking number
                    instance: /Tracking/v1/999999999
        '500':
          description: Internal Server Error - Unexpected system error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                server_error:
                  summary: Internal system error
                  value:
                    type: https://trackingapi.firstmile.com/errors/internal-error
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred while processing the request
                    instance: /Tracking/v1/123456789
components:
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer token authentication. Include the token in the Authorization
        header as 'Bearer {token}'
  schemas:
    TrackingResponse:
      type: object
      additionalProperties: false
      description: Complete tracking information for a shipment
      required:
        - trackingNumber
        - processedDate
        - weightLbs
      properties:
        trackingNumber:
          type: string
          description: The tracking number the information is for
          example: '123456789'
        airwayBill:
          type: string
          nullable: true
          description: >-
            The Airway Bill for some international tracking numbers (supplied by
            DHL)
          example: AWB987654321
        shipmentAddress:
          $ref: '#/components/schemas/Address'
          description: Address information on where the shipment is going
        weightLbs:
          type: number
          format: double
          description: The weight of the shipment in pounds
          example: 2.5
        processedDate:
          type: string
          format: date-time
          description: The processed date of the shipment
          example: '2023-08-01T10:00:00Z'
        events:
          type: array
          items:
            $ref: '#/components/schemas/TrackingEvent'
          nullable: true
          description: Detailed tracking event information
        errors:
          type: array
          items:
            $ref: '#/components/schemas/TrackingError'
          nullable: true
          description: Error information if any
        carrier:
          type: string
          nullable: true
          description: Carrier responsible for the shipment
          example: FirstMile
        trackingURL:
          type: string
          nullable: true
          description: URL to view tracking information
          example: https://trackingapi.firstmile.com/track/123456789
        deliveryDateEstimated:
          type: string
          nullable: true
          description: Estimated delivery date
          example: '2023-08-05'
        deliveryDateMax:
          type: string
          nullable: true
          description: Maximum expected delivery date
          example: '2023-08-07'
        deliveryDateMin:
          type: string
          nullable: true
          description: Minimum expected delivery date
          example: '2023-08-04'
        podImageURLSBase64:
          type: array
          items:
            type: string
          nullable: true
          description: List of base64-encoded URLs for proof of delivery images
        serviceLevel:
          $ref: '#/components/schemas/ServiceLevel'
    TrackingEvent:
      type: object
      additionalProperties: false
      description: Represents a single tracking event in the shipment's journey
      required:
        - eventDatetime
        - eventCode
      properties:
        eventDatetime:
          type: string
          format: date-time
          description: The date/time of the event
          example: '2023-08-01T08:00:00Z'
        eventSource:
          type: string
          nullable: true
          description: The source of the event (e.g., IFS or DHL)
          example: IFS
        eventDescription:
          type: string
          nullable: true
          description: Short description of the event
          example: Package received at facility
        eventCode:
          type: integer
          format: int32
          description: Event specific code
          example: 100
        eventCodeAsString:
          type: string
          nullable: true
          description: >-
            Event specific code in string format (some carriers don't return
            integer codes)
          example: RECEIVED
        eventLocation:
          $ref: '#/components/schemas/Address'
          description: Address information of the event location if available
        actionCode:
          type: string
          nullable: true
          description: Code representing the action taken
          example: A1
        reasonCode:
          type: string
          nullable: true
          description: Code representing the reason for the event
          example: R1
        deliveryAttributeCode:
          type: string
          nullable: true
          description: Code representing delivery attributes
          example: DA1
    ServiceLevel:
      type: string
      nullable: true
      description: Service Level of the shipment
      enum:
        - Ground
        - Expedited
    TrackingError:
      type: object
      additionalProperties: false
      description: Represents an error encountered during tracking
      required:
        - errorCode
      properties:
        errorCode:
          type: integer
          format: int32
          description: The error code
          example: 404
        errorDescription:
          type: string
          nullable: true
          description: Short description of the error
          example: Tracking number not found
    Address:
      type: object
      additionalProperties: false
      description: Represents a physical or mailing address
      properties:
        name:
          type: string
          nullable: true
          description: Name of the individual or contact person
          example: John Doe
        companyName:
          type: string
          nullable: true
          description: Name of the company associated with the address
          example: FirstMile Inc.
        address1:
          type: string
          nullable: true
          description: Primary street address
          example: 123 Main St
        address2:
          type: string
          nullable: true
          description: Secondary street address (optional)
          example: Suite 100
        address3:
          type: string
          nullable: true
          description: Tertiary street address (optional)
        city:
          type: string
          nullable: true
          description: City of the address
          example: Salt Lake City
        region:
          type: string
          nullable: true
          description: Region or state of the address
          example: Utah
        regionCode:
          type: string
          nullable: true
          description: Code representing the region or state
          example: UT
        country:
          type: string
          nullable: true
          description: Country of the address
          example: United States
        countryCode:
          type: string
          nullable: true
          description: ISO code of the country
          example: US
        email:
          type: string
          nullable: true
          description: Email address of the contact
          example: john.doe@example.com
        phoneNumber:
          type: string
          nullable: true
          description: Phone number of the contact
          example: +1-555-1234
        deliveryPoint:
          type: string
          nullable: true
          description: Delivery point identifier
          example: Front Door
        residential:
          type: boolean
          description: Indicates if the address is residential
          example: false
        residentialSpecified:
          type: boolean
          description: Specifies whether the residential status is explicitly set
          example: true
    ProblemDetails:
      type: object
      additionalProperties: true
      description: >-
        Provides details about problems encountered during API operations (RFC
        7807 compliant)
      properties:
        type:
          type: string
          nullable: true
          description: A URI reference that identifies the problem type
          example: https://trackingapi.firstmile.com/errors/invalid-request
        title:
          type: string
          nullable: true
          description: A short, human-readable summary of the problem type
          example: Invalid Request
        status:
          type: integer
          format: int32
          nullable: true
          description: HTTP status code generated by the origin server
          example: 400
        detail:
          type: string
          nullable: true
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem
          example: The tracking number provided has an invalid format
        instance:
          type: string
          nullable: true
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem
          example: /Tracking/v1/invalid123
