shipment__v3.yml

openapi: 3.0.0
info:
  version: "3"
  title: "Shipment"
  description: >
    Tracking shipments by tracknumber.
    This version of manifest uses carriers APIs, but not easypost to track shipments.
servers:
  - url: http://carriers/openapi/Shipment/v3
tags:
  - name: Tracker
paths:
  "/Tracker/{id}":
    get:
      tags:
        - Tracker
      summary: 'Get status of tracking'
      description: "Return status of tracking by trackNumber and carrier"
      parameters:
        - in: path
          name: id
          description: Composite id. Format - trackNumber|carrier
          required: true
          schema:
            type: string
      responses:
        "200":
          description: 'Status of tracking'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackerResponse'
        "500":
          description: 'Some error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: "#/components/schemas/Message"
      description: "message field is not required"
    Message:
      type: object
      properties:
        level:
          type: string
          enum:
            - info
            - warning
            - error
        type:
          type: string
          enum:
            - UNSUPPORTED_CARRIER
            - UNDEFINED
            - INVALID_RESPONSE
            - NOT_FOUND
          description: >
            UNSUPPORTED_CARRIER - Requested carrier is not supported
            UNDEFINED - Any undefined message type
            NOT_FOUND - Tracknumber not exist
        text:
          type: string
          description: Message, that describes what went wrong
    SuccessResponse:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
      type: object
      properties:
        data:
          type: object
    TrackerResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessResponse'
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Tracker'
    Tracker:
      type: object
      required:
        - trackNumber
        - carrier
        - shipStatus
      properties:
        trackNumber:
          type: string
          description: The tracking code provided by the carrier
          example: '9400100000000000000000'
        carrier:
          type: string
          description: The name of the carrier handling the shipment
          enum:
            - USPS
            - FEDEX
            - UPS
        shipStatus:
          type: string
          description: The current status of the package
          enum:
            - pre_transit
            - in_transit
            - out_for_delivery
            - delivered
            - available_for_pickup
            - return_to_sender
            - failure
            - cancelled
            - error
            - unknown
        publicUrl:
          type: string
          format: url
          example: 'https://google.com'
          nullable: true
          description: URL to a publicly-accessible html page that shows tracking details for this tracker
        estDeliveryDate:
          type: string
          format: date-time
          nullable: true
          description: The estimated delivery date provided by the carrier (if available)
        realDeliveryDate:
          type: string
          format: date-time
          nullable: true
          description: The actual delivery date provided by the carrier (if available)
        rawResponse:
          type: object
          additionalProperties: true
          description: Raw response from carrier with data related to specified tracking number