openapi: 3.0.3
info:
  title: DHL  Freight Print API
  version: '1.1'
  description: >-
    
    Please refer Downloads section for more information

  contact:
    email: api4freight@dhl.com

paths:
  /print/printdocumentsbyid:
    post:
      tags:
        - print
      summary: /print/printdocumentsbyid
      description: Print documents for one or more shipment ids
      operationId: printPrintdocumentsbyid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrintOptionsById'
      responses:
        '200':
          description: Success
          content:
            application/json: 
              schema:
                $ref: '#/components/schemas/PrintResult'

  /print/printdocuments:
    post:
      tags:
        - print
      summary: /print/printdocuments
      description: Test
      operationId: printPrintdocuments
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                shipment:
                  $ref: '#/components/schemas/Shipment'     
                options:
                  $ref: '#/components/schemas/ReportOptions'
        required: true    
      responses:
        '200':
          description:  PrintResult
          content:
            application/json: 
              schema:
                $ref: '#/components/schemas/PrintResult'
                
  /print/printmultipledocuments:
    post:
      tags:
        - print
      summary: /print/printmultipledocuments
      description: Test
      operationId: printPrintmultipledocuments
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                shipments:
                  type: array
                  items:
                    $ref: '#/components/schemas/Shipment'
                options:
                  $ref: '#/components/schemas/ReportOptions'
      responses:
        '200':
          description:  PrintResult
          content:
            application/json: 
              schema:
                $ref: '#/components/schemas/PrintResult'
  
components:
  schemas:
    PrintOptionsById:
      type: object
      properties:
        shipmentIds:
          type: array
          maxItems: 999
          minItems: 1
          items:
            type: string
          description: 
            Provide one or more shipment ids that were returned from the Booking API.
          example: '["SHIPMENT.ID-1", "SHIPMENT.ID-2"]'
        options:
          $ref: '#/components/schemas/ReportOptions'
    Shipment:
      required:
        - id
        - parties
        - payerCode
        - pieces
        - productCode
      type: object
      properties:
        id:
          maxLength: 13
          type: string
          description: >
            The shipment's tracking id: The unique global number that ensures that
            packages are not separated from each other during transport from one
            point to another.
          example: ''
        productCode:
          maxLength: 3
          type: string
          description: 
            See the product documentation for available options. 
            You can also use GET /products to see available product for your region.
            With POST /productmatches you can validate which products fit to your shipment details.
          example: 'ECI'
        shippingDate:
          type: string
          format: date
        requestedDeliveryDate:
          type: string
          description: 
            Required with **DHL Eurapid** and Commited Delivery Date (CDD).
          format: date
        deliveryInstruction:
          maxLength: 140
          type: string
        totalNumberOfPieces:
          maximum: 999
          type: integer
          format: int32
          example: 1
        totalWeight:
          maximum: 99999
          type: number
          description: The shipment total weight weight in kg
          format: double
          example: 380
        totalVolume:
          maximum: 999
          type: number
          description: The shipment total volume in m³
          format: double
          example: 0.864
        totalLoadingMeters:
          maximum: 99
          type: number
          description: 
            A loading meter (LDM) is 1 meter of the loading space of a truck's
            width and full height. Usually calculated for goods that cannot be
            stacked on or with other goods.
          format: double
        totalPalletPlaces:
          maximum: 999
          type: number
          description: >
            Pallet place (PPL) is based on the dimensions of a EUR pallet: 120
            x 80 cm. Usually calculated for goods that cannot be stacked on or
            with other goods. 1 PLL =  0.4 LDM.
          format: double
        payerCode:
          $ref: '#/components/schemas/PayerCode'
        parties:
          maxItems: 6
          minItems: 2
          type: array
          items:
            $ref: '#/components/schemas/Party'
        pieces:
          maxItems: 999
          type: array
          items:
            $ref: '#/components/schemas/Piece'
        additionalServices:
          $ref: '#/components/schemas/AdditionalServicesDTO'
        additionalInformation:
          maxItems: 99
          type: array
          items:
            $ref: '#/components/schemas/AdditionalInformation' 
    PayerCode:
      required:
        - code
      type: object
      properties:
        code:
          maxLength: 3
          type: string
          description: 
            See the product documentation for available options based on selected product.
            You can also use GET /products {productCode} to see available payer codes
            for your product.
          example: 'DAP'
        
    Party:
      required:
        - address
        - name
        - type
      type: object
      properties:
        id:
          maxLength: 15
          type: string
          description: 
            For a consignor, consignee or freight payer the customer account
            number. Mandatory for the party that according to the payer code will be freight payer.
            For an access point, i.e. parcel shop, parcel station etc, this is the
            identifier of this location.
        type:
          maxLength: 15
          type: string
          enum:
            - Consignor
            - Pickup
            - Consignee
            - Delivery
            - AccessPoint
            - FreightPayer
        vatEoriSocialSecurityNumber:
          maxLength: 20
          type: string
          description: 
            Used for customs clearance when importing or exporting with
            countries outside the EU.
          example: ''
        name:
          maxLength: 35
          type: string
        contactName:
          maxLength: 35
          type: string
        references:
          maxItems: 99
          type: array
          items:
            type: string
        address:
          $ref: '#/components/schemas/Address'
        phone:
          maxLength: 64
          type: string
        
        subType:
          maxLength: 15
          type: string
          description: 
            Only use with DHL Sweden access point to state if it's a parcel shop, parcel station etc.
          enum:
            - ParcelShop
            - ParcelStation
            - Servicepoint
            - Locker
            - Postoffice
            - Postbank
            
    Address:
      required:
        - street
        - cityName
        - postalCode
        - countryCode
      type: object
      properties:
        street:
          maxLength: 35
          type: string
          description: 
            Provide both street name and house number in this field.
        streetNumber:
          maxLength: 10
          type: string
        additionalAddressInfo:
          maxLength: 35
          type: string
        cityName:
          maxLength: 35
          type: string
        postalCode:
          maxLength: 9
          type: string
        countryCode:
          maxLength: 2
          type: string
          description: >
            ISO 3166-1 are two-letter country codes 
          example: 'DE'
        
    Piece:
      required:
        - id
        - numberOfPieces
        - packageType
        - weight
      type: object
      properties:
        id:
          type: array
          minItems: 1
          maxItems: 999
          uniqueItems: true
          description: >
            The SSCC (Serial Shipping Container Code) a unique GS1/GS1-128
            number, used to identify a logistic unit, such as a case, pallet or
            parcel.
          example: []
          items:
            maxLength: 35
            type: string
        goodsType:
          maxLength: 70
          type: string
          description: Description of goods on cargo detail level.
        packageType:
          maxLength: 4
          type: string
          example: 'PAL'
          description: >
            See the product documentation for available options based on
            selected product. You can also use GET / packageTypes {productCode} to receive the allowed
            package types for your selected product
        marksAndNumbers:
          maxLength: 45
          type: string
        numberOfPieces:
          maximum: 999
          minimum: 1
          type: integer
          format: int32
          example: 1
        weight:
          maximum: 99999
          type: number
          description: Item weight in kg
          format: double
          example: 380
        volume:
          maximum: 999
          type: number
          description: Item volume in m³
          format: double
          example: 0.864
        loadingMeters:
          maximum: 99
          type: number
          format: double
        palletPlaces:
          maximum: 999
          type: number
          format: double
        width:
          maximum: 999
          type: number
          description: Item width in cm
          format: double
          example: 80
        height:
          maximum: 999
          type: number
          description: Item height in cm
          format: double
          example: 90
        length:
          maximum: 9999
          type: number
          description: Item length in cm
          format: double
          example: 120
        stackable:
          type: boolean
        
    AdditionalInformation:
      type: object
      properties:
        code:
          type: string
          enum:
            - EKAER_NUMBER
            - EKAER_FREE
            - SENT_REF
            - SENT_CARKEY
          description: >
            Contains predefined code values (see enumerator) to handle country specific shipment fields for
            e.g. Hungarian EKAER and Polish SENT legal requirements.
          example: 'EKAER_NUMBER'
        stringValue:
          type: string
          description: >
            Contains the content/value for the respective code.
            For EKAER_NUMBER: provide the Hungarian EKAER number and omit EKAER_FREE.
            For EKAER_FREE: provide true or false. If true, omit EKAER_NUMBER.
            For SENT_REF: provide the Polish SENT system reference value.
            For SENT_CARKEY: provide the Polish SENT carrier key
          example: 'E23022311111111'
        dateValue:
          type: string
          format: date-time
        numericValue:
          type: number
          format: double
          
    AdditionalServicesDTO:
      type: object
      properties:
        bookIn:
          type: boolean
          example: false
        bookInWithInfo:
          $ref: '#/components/schemas/BookInWithInfoOptions' 
        carryingHelpPickup:
          type: boolean
          example: false
        carryingHelpToRoomOfChoice:
          type: boolean
          example: false
        cashOnDelivery:
          $ref: '#/components/schemas/CashOnDeliveryOptions'
        collectionAtTerminal:
          type: boolean
          example: false
        customsCustomersOwnDeclaration:
          $ref: '#/components/schemas/CustomsCustomersOwnDeclarationOptions'
        customsHandlingFullService:
          type: boolean
          example: false
        customsHandlingStandard:
          type: boolean
          example: false
        customsJointDeclaration:
          $ref: '#/components/schemas/CustomsJointDeclarationOptions'
        dangerousGoods:
          type: boolean
          example: false
        dangerousGoodsLimitedQuantity:
          type: boolean
          example: false
        deliveryAtConstructionSite:
          type: boolean
          example: false
        deliveryWithoutIdControl:
          type: boolean
          example: false
        deliveryWithoutProofOfDelivery:
          type: boolean
          example: false
        doorstepDelivery:
          $ref: '#/components/schemas/DoorstepDeliveryOptions'
        eurPalletExchange:
          $ref: '#/components/schemas/EURPalletExchangeOptions'
        eveningDeliveryZoneA:
          type: boolean
        eveningDeliveryZoneB:
          type: boolean
          example: false
        eveningDeliveryZoneC:
          type: boolean
          example: false
        eveningDeliveryZoneD:
          type: boolean
          example: false
        eveningDeliveryZoneE:
          type: boolean
          example: false
        fixedDeliveryDate:
          $ref: '#/components/schemas/FixedDeliveryDateOptions'
        greenFreight:
          type: boolean
          example: false
        indoorDelivery:
          type: boolean
          example: false
        installation:
          $ref: '#/components/schemas/InstallationOptions'
        installationAdvanced:
          $ref: '#/components/schemas/InstallationAdvancedOptions'
        insurance:
          $ref: '#/components/schemas/InsuranceOptions'
        m20:
          $ref: '#/components/schemas/M20Options'
        m40:
          $ref: '#/components/schemas/M40Options'
        m60:
          $ref: '#/components/schemas/M60Options'
        nonStackable:
          type: boolean
        notification:
          type: boolean
          example: false
        onlineAppointmentBooking:
          $ref: '#/components/schemas/OnlineAppointmentBookingOptions'
        packagingRemoval:
          type: boolean
          example: false
        personalDelivery:
          type: boolean  
        preAdvice:
          type: boolean
          example: false
        preAdviceByDriver:
          $ref: '#/components/schemas/PreAdviceByDriverOptions'
        priorityServiceG7:
          type: boolean
          example: false
        priorityServiceG10:
          type: boolean
          example: false
        priorityServiceG12:
          type: boolean
          example: false
        priorityServiceP10:
          type: boolean
          example: false
        priorityServiceP12:
          type: boolean
          example: false          
        removalOfReplacedGoods:
          $ref: '#/components/schemas/RemovalOfReplacedGoodsOptions'
        tailLiftLoading:
          type: boolean
          example: false
        tailLiftUnloading:
          type: boolean
          example: false
        thermoCold:
          $ref: '#/components/schemas/ThermoColdOptions'
        thermoWarm:
          $ref: '#/components/schemas/ThermoWarmOptions'
        timeDefiniteLoading:
          $ref: '#/components/schemas/TimeDefiniteLoadingOptions'
        timeDefiniteUnloading:
          $ref: '#/components/schemas/TimeDefiniteUnloadingOptions'
        voecSupplyVAT:
          $ref: '#/components/schemas/VoecSupplyVATOptions'
        weekendDelivery:
          type: boolean
          example: false
        
    CashOnDeliveryOptions:
      required:
        - amount
        - currency
      type: object
      properties:
        amount:
          type: integer
          format: int64
          example: 475
        bankGiroNumber:
          maxLength: 9
          type: string
        plusGiroNumber:
          maxLength: 9
          type: string
        reference:
          maxLength: 35
          type: string
        currency:
          maxLength: 3
          type: string
          description: >
            ISO 4217 codes are three-letter currency codes
          example: 'EUR'
    CustomsCustomersOwnDeclarationOptions:
      required:
        - customsId
      type: object
      properties:
        customsId:
          maxLength: 70
          type: string
        customsClearanceInstruction:
          maxLength: 70
          type: string
    CustomsJointDeclarationOptions:
      required:
        - sfid
      type: object
      properties:
        sfid:
          maxLength: 35
          type: string
    DeliveryMonitoringOptions:
      type: object
      properties:
        email:
          maxLength: 64
          type: string
        smsPhoneNumber:
          maxLength: 20
          type: string
    DoorstepDeliveryOptions:
      type: object
      properties:
        accessCode:
          maxLength: 20
          type: string
    EURPalletExchangeOptions:
      required:
        - quantity
      type: object
      properties:
        quantity:
          maximum: 999
          type: integer
          format: int32
        consignorPalletRegistrationNumber:
          maxLength: 6
          type: string
        consigneePalletRegistrationNumber:
          maxLength: 6
          type: string
    
    HardcopyProofOfDeliveryOptions:
      type: object
      properties:
        email:
          maxLength: 64
          type: string
    InstallationOptions:
      required:
        - quantity
      type: object
      properties:
        quantity:
          maximum: 999
          minimum: 1
          type: integer
          format: int32
    InstallationAdvancedOptions:
      required:
        - quantity
      type: object
      properties:
        quantity:
          maximum: 999
          minimum: 1
          type: integer
          format: int32
    InsuranceOptions:
      required:
        - currency
        - value
      type: object
      properties:
        value:
          type: number
          format: double
        currency:
          maxLength: 3
          type: string
          description: >
            ISO 4217 codes are three-letter currency codes
          example: 'EUR'
    M20Options:
      required:
        - quantity
      type: object
      properties:
        quantity:
          maximum: 999
          minimum: 1
          type: integer
          format: int32
    M40Options:
      required:
        - quantity
      type: object
      properties:
        quantity:
          maximum: 999
          minimum: 1
          type: integer
          format: int32
    M60Options:
      required:
        - quantity
      type: object
      properties:
        quantity:
          maximum: 999
          minimum: 1
          type: integer
          format: int32
    OnlineAppointmentBookingOptions:
      type: object
      properties:
        responseText:
          type: string
    PreAdviceByDriverOptions:
      type: object
      properties:
        phone:
          type: string
    RemovalOfReplacedGoodsOptions:
      required:
        - quantity
      type: object
      properties:
        quantity:
          maximum: 999
          minimum: 1
          type: integer
          format: int32
    
    ThermoColdOptions:
      type: object
      description: >
        For “Thermo Cold” deliveries, the temperature is maintained at between +2 and +8°C throughout the transport chain. Different temperature ranges can be provided by special agreement (although max. 15°C).
      properties:
        min:
          type: number
          format: double
          minimum: 2
        max:
          type: number
          format: double
          maximum: 15
    ThermoWarmOptions:
      type: object
      description: >
        Thermo Warm indicates that the goods are to be transported in frost-free conditions (at least +1°C)
      properties:
        min:
          type: number
          format: double
          minimum: 1
        max:
          type: number
          format: double
    TimeDefiniteLoadingOptions:
      required:
        - dateTime
      type: object
      properties:
        dateTime:
          type: string
          format: date-time
    TimeDefiniteUnloadingOptions:
      required:
        - dateTime
      type: object
      properties:
        dateTime:
          type: string
          format: date-time
    VoecSupplyVATOptions:
      type: object
      properties:
        vatId:
          type: string
    FixedDeliveryDateOptions:
      required:
        - date
      type: object
      properties:
        date:
          type: string
          format: date
    BookInWithInfoOptions:
      type: object
      properties:
        contactDetails:
          maxLength: 64
          type: string
        contactDetailsType:
          type: string
          enum:
            - email
            - phonenumber
            - externalSystem
            - timeWindow
            - other
    
          
    ReportOptions:
      type: object
      properties:
        label:
          type: boolean
        shipmentList:
          type: boolean
        shipmentListType:
          format: int32
          enum:
            - Consignee
            - Delivery
          type: integer
        waybill:
          type: boolean
        guarantee:
          type: boolean
        returnLabel:
          type: boolean
        licensePlateBarCode:
          $ref: '#/components/schemas/LicenseBarCodeEnum'
        pageOptions:
          $ref: '#/components/schemas/PageOptions'   
    
    LicenseBarCodeEnum:
      format: int32
      enum:
        - GS1
        - Code128
      type: integer
    
    PageOptions:
      type: object
      properties:
        pageType:
          $ref: '#/components/schemas/PageTypeEnum'
        marginLeft:
          format: double
          type: number
        marginTop:
          format: double
          type: number
        padding:
          format: double
          type: number
        
    PageTypeEnum:
      format: int32
      enum:
        - Label
        - Label2xPortraitA4
        - Label3xLandscapeA4
        - LabelCompact
      type: integer
            
    PrintResult:
      type: object
      properties:
        reports:
          type: array
          items:
            $ref: '#/components/schemas/PrintReport'
          readOnly: true
          
    PrintReport:
      type: object
      properties:
        name:
          type: string
        content:
          type: string
        type:
          type: string
        valid:
          type: boolean

    IValidationError:
      type: object
      properties:
        field:
          type: string
          readOnly: true
        errorCode:
          type: integer
          format: int32
          readOnly: true
        message:
          type: string
          readOnly: true
        incompatibleFields:
          type: array
          readOnly: true
          items:
            type: string
            
# 1) Define the security scheme type (HTTP bearer)
  securitySchemes:
    bearerAuth:            # arbitrary name for the security scheme
      type: http
      scheme: bearer
      bearerFormat: JWT    # optional, arbitrary value for documentation purposes
      
# 2) Apply the security globally to all operations
security:
  - bearerAuth: []         # use the same name as above
  
servers:
  - url: https://api-sandbox.dhl.com/freight/shipping/labels/v1
    description: Customer Sandbox Environment
  - url: https://api.dhl.com/freight/shipping/labels/v1
    description: Customer Production Environment