Reference Document – XML Services 10.

PROGRAMME & DEVELOPMENT SERVICES

XML Services
Ver. 10.0

Reference Document – Shipment Preparation Guide

 Reference Document – XML Services 10.0

Contents
1 Introduction ............................................................................................................... 3
2 PLT Functionality ...................................................................................................... 3
2.1 Types of Shipment............................................................................................. 3
2.2 Registration ........................................................................................................ 4
2.3 How to prepare a PLT Shipment ...................................................................... 4
3 Label Utility Functionality ....................................................................................... 6
3.1 Using the Label Utility ....................................................................................... 6
3.2 Generating Waybill Label and Archive Document without the Label Utility7
4 BBX Functionality ..................................................................................................... 8
4.1 Definition ............................................................................................................ 8
4.2 How to prepare a BBX shipment...................................................................... 8
4.3 How to prepare a Loose BBX shipment ........................................................ 10
5 Labelless Functionality........................................................................................... 11
5.1 Definition .......................................................................................................... 11
5.2 How to prepare a Labelless shipment to receive QR Code ......................... 12
5.3 How to prepare a Labelless shipment using Labelless ID ........................... 14
5 Appendix A: Glossary of Terms.............................................................................. 15

Doc.Ref: XMLServices10.0_ShipmentPreparationGuide.doc 2 Revision #: 1.0

DHL PROPRIETARY AND CONFIDENTIAL

 Reference Document – XML Services 10.0

1 Introduction
This summarises the:
BBX functionality, PLT functionality and Label Utility functionality in XML
Services Shipment Validation service in v10.0.

2 PLT Functionality
2.1 Types of Shipment
There are two types of shipments supported in XML Services Shipment
Validation service:
i. Regular shipments
ii. Paperless Trade (PLT) shipments

Regular is that type supported exclusively in all versions of XML Services

previous to v6.1.

PLT shipments are now also supported in XML Services v6.0. This provides the
ability for customers to send a Commercial Invoice and other Customs
documentation for a shipment as images to DHL Express electronically. This is
used instead of printing such paperwork to each physical package, as used with
Regular shipments.

XML Services will only allow use of PLT for dutiable shipments. Also a number
of countries’ Customs authorities do not allow either or both exporting or
importing without printed Customs paperwork affixed to shipments. In such
cases Regular shipments must be sent and XML Services will not permit use of
PLT.

Loose BBX and Labelless shipment are now supported in XML Services v10.0
schema. Loose BBX provides the ability to customers to manage the Parent and
Baby relationship shipment. Parent or Mother shipment will be created after
Baby Shipment creation.

Labelless shipment will address customers who lacks printer facilities to print
shipment’s Transport Label. Shipper will be provided a QR code which can be
scanned directly from their mobile devices as replacement of hardcopy of
shipment’s Transport Label.

The QR code will be used as a digital representative of shipment details, with

information to facilitate customer contact points for drop-off or courier pick-up
of shipment.
Doc.Ref: XMLServices10.0_ShipmentPreparationGuide.doc 3 Revision #: 1.0

DHL PROPRIETARY AND CONFIDENTIAL

 Reference Document – XML Services 10.0

Please refer to the following Reference documents in

Toolkit\documents\ReferenceDocuments directory for global schema of the
XML Services Shipment Validation service:
• XMLServices10.0_ShipmentValidationService.doc (Global schema)

2.2 Registration
Customers who wish to subscribe PLT shipment (even if they are current users
of XML Services for Regular shipments) must register to use PLT, and must
contact their local DHL ESS team for assistance to do so.

2.3 How to prepare a PLT Shipment

After a customer has registered for PLT (i.e. their XML Services credentials are
enabled for submission of PLT submission) they can submit PLT enabled XML
Services Shipment Validation Request messages.
The following elements with the contents described below must be included in
a PLT Shipment Validation Request:
i.<IsDutiable> element must contain value of ‘Y’
Element located at
/req:ShipmentValidateRequest/ShipmentDetails/IsDutiable
Example:
<IsDutiable>Y</IsDutiable>

ii. <Dutiable> element must be included

Element located at /req:ShipmentRequest/Dutiable
Example:
<Dutiable>
<DeclaredValue>200.00</DeclaredValue>
<DeclaredCurrency>USD</DeclaredCurrency>
<ScheduleB>3002905110</ScheduleB>
<ExportLicense>D123456</ExportLicense>
<ShipperEIN>112233445566</ShipperEIN>
<ShipperIDType>S</ShipperIDType>
<ImportLicense>ImportLic</ImportLicense>
<ConsigneeEIN>ConEIN2123</ConsigneeEIN>
<TermsOfTrade>DTP</TermsOfTrade>
</Dutiable>

Doc.Ref: XMLServices10.0_ShipmentPreparationGuide.doc 4 Revision #: 1.0

DHL PROPRIETARY AND CONFIDENTIAL

 Reference Document – XML Services 10.0

iii. <GlobalProductCode> element must contain value of global product

code which is dutiable (non-doc) product and supported PLT capability

iv. <SpecialServiceType> element must contain value of ‘WY’

Element located in SpecialService segment at
/req:ShipmentValidateRequest/SpecialService/SpecialServiceType.
Example:
<SpecialService>
<SpecialServiceType>WY</SpecialServiceType>
</SpecialService>

v. <DocImages> element must contain the commercial invoice or other

supporting document images required for Customs clearance, encoded
in base64 (not as an embedded image file of some kind), and the image
file type which has been encoded must also be defined here.
Element located at /req:ShipmentRequest/DocImages.
Example:
<DocImages>
<DocImage>
<Type>CIN</Type>
<Image>IG9iago8PC9MZW5ndGggNiAwIFIvRmlsdGVyICF</Image>
<ImageFormat>PDF</ImageFormat>
</DocImage>
</DocImages>

vi. Request for custom invoice rendering using <UseDHLInvoice> option

and provide the sufficient <ExportDeclaration> element details.
Note: This does not require providing <DocImages> element with custom
invoice images.
Elements located at /req:ShipmentRequest/UseDHLInvoice and
/req:ShipmentRequest/ExportDeclaration.
Example:
<UseDHLInvoice>Y</UseDHLInvoice>
…..
<ExportDeclaration>
<SignatureName>SignatureName</SignatureName>
<SignatureTitle>SignatureTitle</SignatureTitle>
<ExportReason>ExportReason</ExportReason>
<ExportReasonCode>P</ExportReasonCode>
<InvoiceNumber>12345</InvoiceNumber>
<InvoiceDate>2017-06-26</InvoiceDate>
<Remarks>Successfully processed</Remarks>
<TermsOfPayment>30 days</TermsOfPayment>
<OtherRemarks2>OtherRemarks2</OtherRemarks2>
Doc.Ref: XMLServices10.0_ShipmentPreparationGuide.doc 5 Revision #: 1.0

DHL PROPRIETARY AND CONFIDENTIAL

 Reference Document – XML Services 10.0

<OtherRemarks3>OtherRemarks3</OtherRemarks3>-->
……………….
<ExportLineItem>
…………………
</ExportLineItem>
</ExportDeclaration>

The customer must included functionality in their application which creates the
XML Services Shipment Validation Requests to encode the image files
submitted in base64. There is no encoding functionality provided in the XML
Services Tool Kit.

The customer submits the Shipment Validation Request to DHL in the same way
as for a regular shipment, and will receive a response in the same way.
If a success response is received with an element <PLTStatus> populated with A
then the response can be used to create the Air Waybill shipment label. The
resulting Air Waybill label will include PLT in reverse video on the Services
section.

3 Label Utility Functionality

3.1 Using the Label Utility
An XML Services Shipment Validation Response can be returned, both for
Regular and PLT shipments, with an element containing an image of the labels
in either PDF format or EPL2, ZPL2 or LP2 printer code encoded in base64.

To receive such a response <LabelImageFormat> element must be included in

the Shipment Validation Request and state the Output format required
This may contain either in PDF, EPL2, ZPL2 or LP2.

The Shipment Validation Response returned includes:

<OutputFormat> which states the image type returned, corresponding to the
content of <LabelImageFormat> in the corresponding Shipment Validation
Request
<OutputImage> containing the image in base64.

The customer can then use the Label utility in the XML Services Toolkit to
generate labels from the Shipment Validation Response.
Refer to ToolKit_v10.0.pdf section 3.2.1., Settings to execute generateLabel
script (Label Utility) functionality for details.
Doc.Ref: XMLServices10.0_ShipmentPreparationGuide.doc 6 Revision #: 1.0

DHL PROPRIETARY AND CONFIDENTIAL

 Reference Document – XML Services 10.0

In summary, the following steps are followed after double clicking on

‘generateLabel.cmd’ or run it via the command prompt to open the Label Utility:

i. Against Shipment Response XML File select the Shipment Validation

Response from which the labels are to be created
ii. Against "Label Type" select "Both", to create both an Air Waybill shipment
label and Archive Air Waybill label
iii. Against "Output Format" select the same as given in <OutputFormat> in
the Shipment Validation Response
iv. If Output Format is PDF select the location where the resulting image
files are to placed against “Output PDF Location” using Browse
v. If Output Format is any other value select the printer to be used against
Printer using Browse
vi. Select Submit
The Label utility will decode the <OutputImage> image value in
Shipment Validation Response. If PDF was selected against “Label Type”
the resulting file will be stored in the stated location. If EPL2, ZPL2 or LP
were selected the Air Waybill label and Archive Air Waybill label will
printed on the stated printer.

3.2 Generating Waybill Label and Archive Document without the Label
Utility
If the customer requires to write their own application to create the label
images they can decode the contents of the <OutputImage>. Sample decode
source code is available in the toolkit source code directory.

Alternatively they can use the data in the individual elements in the XML
Services Shipment Validation Response in conjunction with label specifications
available from DHL. In this case there is no need to include
<LabelImageFormat> in the initial Shipment Validation Request.

Doc.Ref: XMLServices10.0_ShipmentPreparationGuide.doc 7 Revision #: 1.0

DHL PROPRIETARY AND CONFIDENTIAL

 Reference Document – XML Services 10.0

4 BBX Functionality
4.1 Definition
BBX consists of a ‘Mother’ shipment which is cleared as one single shipment on
entry to the nominated country/region of import. The mother will contain
multiple ‘Baby’ shipments consigned to different receivers belonging to the
same customs zone.

4.2 How to prepare a BBX shipment

XMLPI supports BBX shipment process where the customer knows the count of
mother pieces upfront.

1. Customer sends shipment validation request message for Mother Shipment

with relevant shipment information and the below information :
a. The <Pieces> element should declare the relevant piece details

Note:
Each individual <Piece> segment will indicate one single piece of the
Total Mother Piece.
Doc.Ref: XMLServices10.0_ShipmentPreparationGuide.doc 8 Revision #: 1.0

DHL PROPRIETARY AND CONFIDENTIAL

 Reference Document – XML Services 10.0

b. <SpecialServiceType> element must contain value of ‘YW’

c. <GlobalProductCode> element must contain value of ‘P’ or ‘H’

2. Customer receives shipment validation response message for Mother

Shipment with the Pieces IDs. The successful response is used to create the
Mother shipment label.

3. Customer sends shipment validation request message for Baby Shipment

with relevant shipment information and the below information:
a. At the baby shipment level,
i. <ParentShipmentIdentificationNumber> element must contain the
Mother Shipment ID
ii. <GlobalProductCode> element must contain value of ‘B’

b. For each baby piece id

i. <ParentPieceIdentificationNumber> element must contain the
corresponding Mother Shipment’s piece ID

NOTE: The above steps are recommended to prepare a BBX Shipment.

OR,

Customer sends shipment validation request message for Baby Shipment

with relevant shipment information and the below information:
c. At the baby shipment level,
i. <ReferenceType> element must contain value of ‘ACL’
ii. <ReferenceID> element must contain the Mother Shipment ID
iii. <GlobalProductCode> element must contain value of ‘B’

d. For each baby piece id

i. <ReferenceType> element must contain value of ‘ACL’
ii. <ReferenceID> element must contain the corresponding Mother
Shipment’s piece ID

NOTE: The above steps are legacy way of preparing a BBX Shipment.

4. Customer receives shipment validation response message for Baby

Shipment. The successful response can be used to create the Baby shipment
label.

Doc.Ref: XMLServices10.0_ShipmentPreparationGuide.doc 9 Revision #: 1.0

DHL PROPRIETARY AND CONFIDENTIAL

 Reference Document – XML Services 10.0

4.3 How to prepare a Loose BBX shipment

XMLPI supports Loose BBX shipment process where the customer can request
for several Baby shipments and close the process by requesting for the Mother
shipment.

Data is setup such that single or multiple Piece IDs are linked to a Baby
Shipment. Multiple Baby Waybills are then linked to only one (1) Parent
Shipment.

1. Obtain a Parent Shipment ID by sending a MyDHLAPI Request Identifer

request message.

Alternatively, customer can send a ShippingNumbersExternalRequest

request message to obtain Parent Shipment ID range.

2. Customer sends shipment validation request message for Baby Shipment

with relevant shipment information and the below information :
a. At the baby shipment level,
i. < ParentShipmentIdentificationNumber> element must contain
Parent Shipment ID obtained from Step 1.
ii. <GlobalProductCode> element must contain value of ‘B’
iii. <ParentShipmentGlobalProductCode> element must contain the
Parent Shipment’s Global product code
iv. <ParentShipmentPackagesCount> element must contain the
Parent Shipment’s total number of pieces
v. <SpecialServiceType> element must contain value of ‘YZ’
vi. <Importer> element section must contain Importer of Record
details
vii. <Shipper> and <Consignee> element section must contain the
Baby Shipment’s details
viii. <LabelTemplate> element must contain the value of
‘ECOM26_84_LBBX_001’

3. Customer receives shipment validation response message for Baby

Shipment with the Pieces IDs. The successful response is used to create
the Baby shipment label and waybill document.

4. Customer to repeat Steps 2 and 3 for additional Baby Shipments.

5. Customer to complete the Loose BBX process by sending shipment

validation request message for Parent Shipment.
Doc.Ref: XMLServices10.0_ShipmentPreparationGuide.doc 10 Revision #: 1.0

DHL PROPRIETARY AND CONFIDENTIAL

 Reference Document – XML Services 10.0

a. At the parent shipment level,

i. < ShipmentIdentificationNumber> element must contain Parent
Shipment ID obtained from Step 1.
ii. < UseOwnShipmentIdentificationNumber> element must contain
value ‘Y’
iii. <SpecialServiceType> element must contain value of ‘YM’
iv. <GlobalProductCode> element must contain the Parent Shipment’s
Global product code

b. For each baby piece,

i. < UseOwnPieceIdentificationNumber> element must contain value
‘Y’
ii. < PieceIdentificationNumber> element must contain the Baby
Shipment’s Piece ID obtained from Step 2 and 3 shipment
validation response message. Note that ALL Baby Shipment Piece
IDs must be included in the Parent Shipment piece section

Note that on each baby piece, it is customer’s responsibility to

declare the total shipment’s weight of the Parent Shipment, same
with the DeclaredValue for Customs Declaration and Customs
Invoice printing.

c. For Parent Shipment, customer may request for DHL Customs Invoice
by indicating <RequestDHLCustomsInvoice> with value ‘Y’ and
setting <CustomsInvoiceTemplate> with new template name
‘COMMERCIAL_INVOICE_04’.

6. Customer receives shipment validation response message for Parent

Shipment. The successful response is used to create the Parent
Shipment’s Customs Invoice.

5 Labelless Functionality
5.1 Definition
Labelless functionality is to allow pick-up of shipments without a multi-ply or a
printed transport label and waybill being available.

A QR Code will be provided to the shipper which can be scanned directly from
their mobile devices as a replacement of hardcopy shipment transport label.
Doc.Ref: XMLServices10.0_ShipmentPreparationGuide.doc 11 Revision #: 1.0

DHL PROPRIETARY AND CONFIDENTIAL

 Reference Document – XML Services 10.0

The QR Code will be used as a digital representative of shipment details, with

information to facilitate customer contact points for drop-off or courier pick-up
of shipment.

There are two ways to utilize the labelless functionality – 1) to receive a QR

Code in response; and 2) to acquire a pre-defined set of stickers with Labelless
ID.

5.2 How to prepare a Labelless shipment to receive QR Code

Customer may prepare a Labelless shipment and receive a QR Code for
scanning upon pick-up or dropoff.

1. Customer sends the ShipmentRequest message with mandatory fields

a. The <RequestQRCode> element must contain value ‘Y’
b. <SpecialService/SpecialServiceType> element must contain
value of ‘PZ’
c. <SpecialService/SpecialServiceType> element must contain
any one advance shipment special service type PT / PU / PV /
PW. Providing more than one advance shipment special
service code will result to error in response.
d. <ShipmentRequest/SpecialService/SpecialServiceType>
element must contain the Paperless Trade service value of
‘WY’.
Note: Paperless Trade service may not be available
everywhere).
Refer to section 2.3 for PLT shipment preparation guide.

2. There will be no Transport Label image returned in response be default.

<RequestTransportLabel> element value must be ‘Y’ if requiring a
Transport Label image returned in response, together with the QR code
image.

3. <QRCodeImageFormat> element must contain value ‘PNG’.

4. <QRCodeTemplate> element must contain value

‘QR_1_00_LL_PNG_001’.

5. Customer receives ShipmentResponse message containing QR Code

image in ShipmentRespose/Pieces/Piece/QRCode/Image element.
Customer may use the QR Code to be scanned upon courier pick-up or
dropoff at a Service Center.
Doc.Ref: XMLServices10.0_ShipmentPreparationGuide.doc 12 Revision #: 1.0

DHL PROPRIETARY AND CONFIDENTIAL

 Reference Document – XML Services 10.0

Doc.Ref: XMLServices10.0_ShipmentPreparationGuide.doc 13 Revision #: 1.0

DHL PROPRIETARY AND CONFIDENTIAL

 Reference Document – XML Services 10.0

5.3 How to prepare a Labelless shipment using Labelless ID

This option is catered for Service Points to include a Labelless ID and affix a
sticker in the shipment. Full transport labels will then be printed at service
centre before continue to outbound processing. Note that Service Point
onboarding is required by contacting the DHL Express IT Representative.

1. Customer sends the ShipmentRequest message with mandatory field

a. <SpecialService/SpecialServiceType> element must contain
value of ‘PZ’
b. ShipmentRequest/ShipmentDetails/Pieces/Piece/PieceReference
/ReferenceType element with value ‘LID’ must be provided
together with
ShipmentRequest/ShipmentDetails/Pieces/Piece/PieceReference
/ReferenceID element. <ReferenceID> element must contain the
18-character Labelless ID.
c. <ShipmentRequest/SpecialService/SpecialServiceType>
element must contain the Paperless Trade service value of ‘WY’.
Note: Paperless Trade service may not be available everywhere).
Refer to section 2.3 for PLT shipment preparation guide.

2. Providing advance shipment special service type is optional.

Providing more than one advance shipment special service code will
result to error in response.

3. Providing <RequestQRCode> element and <RequestTransportLabel>

element is optional.

4. Customer receives successful ShipmentResponse message.

5. Depending on values provided in step 3, customer receives

ShipmentResponse message containing any of below image(s):
 a QR Code image
 a Transport Label image
 both QR Code image and Transport Label images

Doc.Ref: XMLServices10.0_ShipmentPreparationGuide.doc 14 Revision #: 1.0

DHL PROPRIETARY AND CONFIDENTIAL

 Reference Document – XML Services 10.0

5 Appendix A: Glossary of Terms

Term Definition
PLT Paperless Trade: functionality to allow
submission of paperwork for Customs
clearance to be submitted to DHL
electronically rather than printing and
affixing it to the corresponding
shipment. Only available where both
shipment origin and destination
Customs authorities do not mandate
use of printed documentation
PLT is not required if a shipment is not
dutiable (i.e. does not need to be
declared to Customs)
Regular Shipment Shipment where PLT is not used,
either where it is dutiable and printed
Customs documentation is attached to
the shipment or where the shipment is
not dutiable
BBX BreakBulk Shipment
LBBX Loose BreakBulk Shipment

Doc.Ref: XMLServices10.0_ShipmentPreparationGuide.doc 15 Revision #: 1.0

DHL PROPRIETARY AND CONFIDENTIAL