openapi: 3.0.3
info:
  version: 1.2.1
  title: Subscriber's system notification
  description: |-

    Open API specification which customer has to implement to be able to consume UTAPI Push notifications.

    ### Note ###
    Date and Time always conform to the ISO 8601 format e.g.: 2017-06-21T14:07:17+2:00, 2017-06-21T14:07:00Z (zoned date time) or 2017-06-21T14:07:17 (date time) or 2017-06-21 (date).
    If no time zone information is provided then time zone should be interpreted as in the place of the respective shipment event.

servers:
- url: https://customer.url/path/to
paths:
  /webhook:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PushNotification'
      responses:
        "202":
          description: Event has been accepted
components:
  schemas:
    PushNotification:
      allOf:
      - $ref: '#/components/schemas/SubscriptionRequestState'
      - $ref: '#/components/schemas/PushNotification_allOf'
      type: object
    SubscriptionRequestState:
      description: Subscription request state response
      properties:
        self:
          description: uniform resource identifier of system
          example: https://api-eu.dhl.com/subscription/d51e5436-3882-4d94-92d5-d30b31d844d8
          format: uri
          type: string
        scope:
          $ref: '#/components/schemas/SubscriptionScope'
        expires:
          format: iso8601-date-time
          type: string
        secret:
          description: Validation of intent secret
          format: password
          type: string
        note:
          example: Regular push message
          type: string
      type: object
    SubscriptionScope:
      enum:
      - subscription.create
      - subscription.validate
      - subscription.activate
      - subscription.ready
      - subscription.push
      - subscription.remove
      type: string
    TrackingShipment:
      description: Unified tracking shipment
      properties:
        id:
          description: Shipment identification tracking number
          type: string
        service:
          $ref: '#/components/schemas/Service'
        division:
          description: The (sub)division of service provider that owns the shipment
          type: string
        origin:
          $ref: '#/components/schemas/SecuredPlace'
        destination:
          $ref: '#/components/schemas/SecuredPlace'
        status:
          $ref: '#/components/schemas/TrackingShipmentStatus'
        pickUpDate:
          description: Shipment pickup date
          format: iso8601-date-time
          type: string
        estimatedTimeOfDelivery:
          description: Estimated time of delivery
          format: iso8601-date-time
          type: string
        agreedDeliveryDate:
          description: Agreed Delivery Date
          type: string
          format: iso8601-date-time
        estimatedDeliveryTimeFrame:
          $ref: '#/components/schemas/EstimatedDeliveryTimeFrame'
        estimatedTimeOfDeliveryRemark:
          description: Human-readable description of the estimated delivery time
          type: string
        serviceUrl:
          description: Custom link to BU tracking service
          format: uri
          type: string
        rerouteUrl:
          description: "Custom link to BU rerouting service, if available for the\
            \ current status of the shipment"
          format: uri
          type: string
        returnFlag:
          default: false
          description: A flag whether the delivery is returned back to consignor
          type: boolean
        details:
          $ref: '#/components/schemas/TrackingShipmentDetails'
        events:
          description: Historical list of events & timestamps
          items:
            $ref: '#/components/schemas/TrackingShipmentEvent'
          type: array
      type: object
    TrackingShipmentStatus:
      description: High-level shipment status
      properties:
        timestamp:
          description: A combination of date and time of day
          format: iso8601-date-time
          type: string
        location:
          $ref: '#/components/schemas/SecuredPlace'
        statusCode:
          $ref: '#/components/schemas/StatusCode'
        status:
          description: Short description of the status - title
          type: string
        description:
          description: Human-readable detailed description
          type: string
        remark:
          description: Remark regarding the shipment status
          type: string
        nextSteps:
          description: Description of the next steps
          type: string
      required:
      - statusCode
      - timestamp
      type: object
    TrackingShipmentDetails:
      description: Shipment Details
      properties:
        product:
          $ref: '#/components/schemas/Product'
        provider:
          $ref: '#/components/schemas/Provider'
        receiver:
          $ref: '#/components/schemas/PersonEntity'
        sender:
          $ref: '#/components/schemas/PersonEntity'
        carrier:
          $ref: '#/components/schemas/PersonEntity'
        shipper:
          $ref: '#/components/schemas/PersonEntity'
        consignee:
          $ref: '#/components/schemas/PersonEntity'
        proofOfDelivery:
          $ref: '#/components/schemas/ProofOfDelivery'
        proofOfDeliverySignedAvailable:
          description: \'Yes\' if signer identification is available
          type: boolean
        totalNumberOfPieces:
          description: Total number of items or pieces in the shipment
          format: int32
          type: integer
        pieceIds:
          description: Ids of all the items or pieces in the shipment
          items:
            $ref: '#/components/schemas/PieceId'
          type: array
        weight:
          $ref: '#/components/schemas/QuantitativeValue'
        volume:
          $ref: '#/components/schemas/QuantitativeValue'
        loadingMeters:
          description: A loading meter standard unit of measurement for transport
            by truck
          format: float
          type: number
        dimensions:
          $ref: '#/components/schemas/Dimensions'
        references:
          description: A list of indications that refers to related shipment
          items:
            $ref: '#/components/schemas/Reference'
          type: array
        valueAddedServices:
          $ref: '#/components/schemas/TrackingShipmentDetails_valueAddedServices'
        controlledDataCodes:
          description: Extra Controlled Access Data Codes
          items:
            $ref: '#/components/schemas/ControlledDataCode'
          type: array
        shipmentActivationDate:
          description: Shipment Activation date
          type: string
          format: iso8601-date-time
        dgf:routes:
          description: DHL Global Forwarding routing Details
          items:
            $ref: '#/components/schemas/DgfRoute'
          type: array
        telemetry:
          description: list of all sensor measurements from devices
          type: array
          items:
            $ref: '#/components/schemas/Measurement'
      type: object
    TrackingShipmentEvent:
      allOf:
      - $ref: '#/components/schemas/TrackingShipmentStatus'
      - $ref: '#/components/schemas/TrackingShipmentEvent_allOf'
      description: Shipment movement information
      type: object
    ttl:
      default: 15552000
      description: Define the TTL value in seconds of shipment between 30 and 365
        days
      format: int32
      maximum: 31536000
      minimum: 2592000
      type: integer
    Service:
      description: Service (provider) used to resolve this tracking number (id)
      enum:
      - dgf
      - dsc
      - ecommerce
      - ecommerce-apac
      - ecommerce-europe
      - ecommerce-ppl
      - express
      - freight
      - parcel-de
      - parcel-nl
      - parcel-pl
      - parcel-uk
      - post-de
      - post-international
      - sameday
      - svb
      example: express
      nullable: false
      type: string
      x-enum-varnames:
      - DGF
      - DSC
      - ECM
      - ECP
      - ECE
      - PPL
      - XPR
      - FRT
      - PAD
      - PAN
      - PAP
      - PUK
      - PSD
      - DPI
      - SMD
      - SVB
    SecuredPlace:
      description: The location of object
      properties:
        address:
          $ref: '#/components/schemas/SecuredAddress'
      type: object
    SecuredAddress:
      description: The mailing address secured by policy
      properties:
        addressLocality:
          description: "Text specifying the name of the locality, for example a city"
          example: Prague
          type: string
        addressLocalityServicing:
          description: Text specifying a detail of address locality
          example: Chodov
          type: string
        addressRegion:
          description: Text specifying a detail of country
          example: Prague 11
          type: string
        countryCode:
          description: Code specifying the country for the address using ISO 3166-1
          example: CZ
          format: country-code
          type: string
        postalCode:
          description: Text specifying the postal code for an address
          example: "14000"
          type: string
        streetAddress:
          description: The street address expressed as free form text
          example: Batman Avenue 1040
          type: string
    EstimatedDeliveryTimeFrame:
      description: A term when shipment is expected to arrive
      properties:
        estimatedFrom:
          description: The start date of the estimated time frame
          format: iso8601-date-time
          type: string
        estimatedThrough:
          description: The end date of the estimated time frame
          format: iso8601-date-time
          type: string
      type: object
    ReturnFlag:
      default: false
      description: A flag whether the delivery is returned back to consignor
      type: boolean
    StatusCode:
      description: Code of the status (high-level grouping statuses)
      enum:
      - delivered
      - failure
      - pre-transit
      - transit
      - unknown
      example: delivered
      type: string
    Product:
      description: Offered product or service
      properties:
        deliveryMethodRemark:
          description: Specific detail of product
          example: D2P
          type: string
        productName:
          description: Business unit product or service
          example: Worldwide Priority
          type: string
      type: object
    Provider:
      description: "The service provider, service operator, or service performer"
      example:
        destinationProvider: freight
      properties:
        destinationProvider:
          description: The name of the provider organization handling the delivery
            in the destination country
          enum:
          - acs-courier
          - anpost
          - bpost
          - bring
          - chronopost
          - colis-prive
          - express
          - fastway
          - freight
          - freight-fr
          - hrvatska-posta
          - magyar-posta
          - oepag
          - parcel-be
          - parcel-bl
          - parcel-cz
          - parcel-de
          - parcel-es
          - parcel-lu
          - parcel-nl
          - parcel-pl
          - parcel-pt
          - parcel-uk
          - posta
          - posti
          - rapido
          - relais-colis
          - slovak-parcel-service
          - trans-o-flex
          - urgent-cargus
          type: string
      required:
      - destinationProvider
      type: object
    PersonEntity:
      description: "A real organization or personal entity, if type is not specified,\
        \ a Organization implementation is used"
      discriminator:
        mapping:
          Organization: '#/components/schemas/Organization'
          Person: '#/components/schemas/Person'
        propertyName: '@type'
      oneOf:
      - $ref: '#/components/schemas/Organization'
      - $ref: '#/components/schemas/Person'
      type: object
    Organization:
      description: "Common organization such as school, club etc."
      properties:
        '@type':
          default: Organization
          example: Organization
          type: string
        name:
          description: The name of the person
          example: Linford Alene
          type: string
        organizationName:
          description: The name of organization
          example: Highgate School and Academy
          type: string
      type: object
    Person:
      description: A person
      properties:
        '@type':
          default: Person
          example: Person
          type: string
        familyName:
          description: "Family name, the last name of a person"
          type: string
        givenName:
          description: "Given name, the first name of a person"
          type: string
        name:
          description: The name of the person
          example: Dariel Leola
          type: string
    ProofOfDelivery:
      description: An acknowledgment that an order successfully arrived at its intended
        destination
      properties:
        documentUrl:
          description: The link to related electronic proof of delivery document
          example: https://webpod.dhl.com/pod?token=510f1359603a768a57af49cf10083f90&language=en
          format: uri
          type: string
        signatureUrl:
          description: The link to related electronic signature
          format: uri
          type: string
        signed:
          $ref: '#/components/schemas/PersonEntity'
        timestamp:
          description: Date and time of related proof of delivery document
          format: iso8601-date-time
          type: string
      type: object
    PieceId:
      description: Identification of item or piece in the shipment
      type: string
    QuantitativeValue:
      description: A point value or interval for product characteristics and other
        purposes
      properties:
        unitText:
          description: A string or text indicating the unit of measurement
          example: m
          type: string
        value:
          description: The value of the quantitative value or property value node
          example: 1.5
          type: number
      type: object
    Dimensions:
      description: A measurable extent of a particular kind of delivery
      properties:
        height:
          $ref: '#/components/schemas/QuantitativeValue'
        length:
          $ref: '#/components/schemas/QuantitativeValue'
        width:
          $ref: '#/components/schemas/QuantitativeValue'
      type: object
    Reference:
      description: An indication that refers to related shipment
      properties:
        number:
          description: A value of reference
          type: string
        type:
          $ref: '#/components/schemas/ReferenceType'
      required:
      - type
      type: object
    ReferenceType:
      description: Type of reference
      enum:
      - container-number
      - customer-confirmation-number
      - customer-reference
      - domestic-consignment-id
      - ecommerce-number
      - housebill
      - local-tracking-number
      - masterbill
      - payer-account-number
      - receiver-account-number
      - reference
      - shipment-id
      - shipper-account-number
      example: customer-confirmation-number
      type: string
    ValueAddedService:
      description: End customer service
      properties:
        serviceType:
          enum:
          - bulky
          - pickup
          - gogreen
          - priority
          - extraInsurance
          - directInjection
          - cashOnDelivery
          type: string
        serviceCriteria:
          type: string
        serviceFlag:
          type: boolean
      type: object
    ControlledDataCode:
      enum:
      - consignee-city
      - servicepoint-facilityId
      - servicepoint-url
      - shipper-city
      - signatory-name
      example: consignee-city
      type: string
    DgfRoute:
      description: DHL Global Forwarding Route
      properties:
        dgf:vesselName:
          description: Vessel Name for Ocean
          example: MAERSK SARAT
          type: string
        dgf:voyageFlightNumber:
          description: "Voyage number for Ocean, Flight Carrier and Number for Air"
          example: TR TRUCK
          type: string
        dgf:airportOfDeparture:
          $ref: '#/components/schemas/DgfAirport'
        dgf:airportOfDestination:
          $ref: '#/components/schemas/DgfAirport'
        dgf:estimatedDepartureDate:
          description: Flight Estimated Date and Time of Departure
          format: iso8601-date-time
          type: string
        dgf:estimatedArrivalDate:
          description: Flight Estimated Date and Time of Arrival
          format: iso8601-date-time
          type: string
        dgf:placeOfAcceptance:
          $ref: '#/components/schemas/DgfLocation'
        dgf:portOfLoading:
          $ref: '#/components/schemas/DgfLocation'
        dgf:portOfUnloading:
          $ref: '#/components/schemas/DgfLocation'
        dgf:placeOfDelivery:
          $ref: '#/components/schemas/DgfLocation'
      type: object
    DgfAirport:
      allOf:
      - $ref: '#/components/schemas/DgfLocation'
      description: DHL Global Forwarding Airport
      properties:
        dgf:locationCode:
          description: Airport of departure/destination in IATA code format
          example: AMS
          type: string
        countryCode:
          description: Airport of departure/destination ISO country code
          example: NL
          format: country-code
          type: string
      type: object
    DgfLocation:
      description: DHL Global Forwarding Location
      properties:
        dgf:locationName:
          description: The name of the location
          example: GOTHENBURG
          type: string
      type: object
    PushNotification_allOf:
      properties:
        shipments:
          description: An array of unified tracking shipments
          items:
            $ref: '#/components/schemas/TrackingShipment'
          type: array
      example: null
    TrackingShipmentDetails_valueAddedServices:
      description: Services I booked together with my Tracking details
      properties:
        services:
          description: List of customer services
          items:
            $ref: '#/components/schemas/ValueAddedService'
          type: array
      type: object
    TrackingShipmentEvent_allOf:
      properties:
        pieceIds:
          description: Ids of all the items or pieces in the shipment
          items:
            $ref: '#/components/schemas/PieceId'
          type: array
      example: null
    Measurement:
      description: Telemetry measurement details about shipment
      properties:
        '@policy':
          $ref: '#/components/schemas/SecretPolicy'
        timestamp:
          description: Date and time when the telemetry data was created by the origin system
          type: string
          format: iso8601-date-time
          # Custom validation constraint
          x-field-extra-annotation: '@com.dhl.utapi.common.datetime.validation.LocalDateTimeConstraint'
        deviceId:
          description: Sensor device id measured the humidity
          type: string
        pieceIds:
          description: piece ids of shipment
          type: array
          items:
            $ref: '#/components/schemas/PieceId'
        location:
          $ref: '#/components/schemas/Location'
        humidity:
          $ref: '#/components/schemas/Humidity'
        pressure:
          $ref: '#/components/schemas/Pressure'
        temperature:
          $ref: '#/components/schemas/Temperature'
        tilt:
          $ref: '#/components/schemas/Tilt'
    SecretPolicy:
      description: A secret policy protecting sensitive information
      type: string
      enum:
        - none
        - postal-code
      default: postal-code
      example: postal-code
    Location:
      description: location co-ordinates of shipment
      type: object
      properties:
        lat:
          description: Latitude value
          type: number
          example: 18.556873
        lon:
          description: Longitude value
          type: number
          example: -70.06104
    Humidity:
      description: Humidity measurement
      type: object
      properties:
        value:
          description: Humidity value
          type: number
        unit:
          description: Unit of measurement
          type: string
          enum:
            - percentage
          example: percentage
    Pressure:
      description: Pressure measurement
      type: object
      properties:
        value:
          description: Pressure value
          type: number
        unit:
          description: Unit of measurement
          type: string
          enum:
            - pascal
            - bar
            - psi
          example: pascal
    Temperature:
      description: Temperature measurement
      type: object
      properties:
        value:
          description: Temperature value
          type: number
        unit:
          description: Unit of measurement
          type: string
          enum:
            - celsius
            - fahrenheit
            - kelvin
          example: celsius
    Tilt:
      description: Tilt measurement
      type: object
      properties:
        value:
          description: Tilt value
          type: number
        unit:
          description: Unit of measurement
          type: string
          enum:
            - degree
            - radian
          example: degree

