Project Brief DHL Express Global Web Services Developer Guide V4.0.1

User Manual:

Open the PDF directly: View PDF .
Page Count: 163

Download
Open PDF In Browser	View PDF

DHL EXPRESS GLOBAL
WEBSERVICES
DEVELOPER GUIDE
DHL Express – Excellence. Simply delivered.
V4.0.1

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

DOCUMENT CONTROL
REVISION HISTORY:
Version

Release Date

Comments

4.0

22/01/2018

Updated Design & update to createShipment and new
services updateShipment and requestPickup

4.0.1

30/01/2018

Updated REST examples and Pickup reference numbers

PAGE 2 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

CONFIDENTIALITY (CONTENT IS COMMERCIALLY CONFIDENTIAL)
The information contained in this document is the property Deutsche Post DHL.
No part of its contents may be divulged to third parties without the express written approval of DHL
Express.
All rights reserved; no part of this document may be reproduced, stored in a retrieval system, or
transmitted in any form or by any other means, electronic, mechanical, photocopying, recording
otherwise without the prior written permission of DHL Express.
This document may not be lent, resold, hired out or otherwise disposed of by way of trade in any
form, binding or cover other than that in which it is published, without the prior written permission
of DHL Express.

DISCLAIMER (RIGHT TO MODIFY)
This document contains (as detailed) the latest information received in time to be incorporated for
publication. However, DHL Express reserves the right to modify the information contained herein
without published notification.
Deutsche Post World Net offers no warranty, express or implied, regarding its accuracy, sufficiency,
merchantability or fitness for any purpose of the information contained herein. Any use made
thereof is made entirely at the risk and for the account of the user.

TERMS AND CONDITIONS
The requirements and specifications outlined in this manual are governed by DHL’s Terms and
Conditions of Carriage, found on DHL’s website, www.DHL.com.

AUDIENCE
This document is intended to serve as a guide to assist DHL customers and third party developers
during the integration development process. The primary audience of this document is intended to
be a trading partner’s technical resources and internal DHL Express Global WebServices support
staff.
© 2005 - 2018 DHL Express, Inc. All rights reserved.

PAGE 3 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

CONTENT
1.
1.1
1.2
1.3
2.
2.1
2.2
3.

INTRODUCTION.................................................................................................................. 6
DHL EXPRESS GLOBAL WEB SERVICES OVERVIEW ........................................................................ 6
REQUIREMENTS – TECHNICAL SKILLS ......................................................................................... 6
REQUIREMENTS – BUSINESS UNDERSTANDING.............................................................................. 6
DHL EXPRESS GLOBAL WEB SERVICES OVERVIEW........................................................... 7
WEB SERVICE DEFINITION LANGUAGE AND REFERENCE DOCUMENTS ................................................ 7
SECURITY AND AUTHENTICATION ............................................................................................. 8
WHAT WEB SERVICES OPERATIONS ARE AVAILABLE? .................................................... 9

RATEREQUEST.................................................................................................................. 11
4.1 RATEREQUEST - DESCRIPTION ................................................................................................ 11
4.2 RATEREQUEST - INPUT.......................................................................................................... 11
4.3 RATEREQUEST – INPUT FIELD LIST ........................................................................................... 17
4.4 RATEREQUEST - OUTPUT ...................................................................................................... 21
4.5 RATE RESPONSE – OUTPUT FIELD LIST ...................................................................................... 24
5.
SHIPMENTREQUEST ......................................................................................................... 26
5.1 SHIPMENTREQUEST - DESCRIPTION .......................................................................................... 26
5.2 SHIPMENTREQUEST - INPUT ................................................................................................... 26
5.3 SHIPMENT REQUEST – INPUT FIELD LIST .................................................................................... 38
5.4 SHIPMENTREQUEST - OUTPUT ................................................................................................ 48
5.5 SHIPMENT RESPONSE – OUTPUT FIELD LIST ................................................................................ 50
6.
SHIPMENTDELETEREQUEST ............................................................................................. 51
6.1 SHIPMENTDELETEREQUEST - DESCRIPTION ................................................................................ 51
6.2 SHIPMENTDELETEREQUEST - INPUT .......................................................................................... 51
6.3 SHIPMENTDELETEREQUEST – INPUT FIELD LIST ............................................................................ 53
6.4 SHIPMENTDELETEREQUEST – OUTPUT ...................................................................................... 53
6.5 SHIPMENTDELETEREQUEST – OUTPUT FIELD LIST......................................................................... 54
7.
TRACKINGREQUEST ......................................................................................................... 55
7.1 TRACKINGREQUEST - DESCRIPTION ......................................................................................... 55
7.2 TRACKINGREQUEST - INPUT ................................................................................................... 56
7.3 TRACKINGREQUEST – INPUT FIELD LIST..................................................................................... 57
7.4 TRACKINGRESPONSE - OUTPUT .............................................................................................. 59
7.5 TRACKINGRESPONSE – OUTPUT FIELD LIST ................................................................................ 64
8.
DOCUMENTRETRIEVE - EPOD .......................................................................................... 69
8.1 DOCUMENTRETRIEVE-EPOD - DESCRIPTION .............................................................................. 69
8.2 DOCUMENTRETRIEVE-EPOD - INPUT ....................................................................................... 69
8.3 SHIPMENTDOCUMENTRETRIEVE-EPOD – INPUT FILED LIST ............................................................ 80
8.4 SHIPMENTDOCUMENTRETRIEVE-EPOD – OUTPUT....................................................................... 83
8.5 DOCUMENTRETRIEVE-EPOD – OUTPUT FIELD LIST ...................................................................... 98
9.
UPDATESHIPMENT ......................................................................................................... 101
9.1 UPDATESHIPMENT - DESCRIPTION ......................................................................................... 101
9.2 UPDATESHIPMENT - INPUT .................................................................................................. 101
9.3 UPDATE SHIPMENT REQUEST – INPUT FIELD LIST ....................................................................... 104
9.4 UPDATESHIPMENT - OUTPUT................................................................................................ 108
9.5 UPDATE SHIPMENT RESPONSE – OUTPUT FIELD LIST .................................................................. 110
10. REQUESTPICKUP ............................................................................................................ 111
10.1
REQUESTPICKUP - DESCRIPTION......................................................................................... 111
10.2
REQUESTPICKUP - INPUT .................................................................................................. 111
10.3
REQUESTPICKUP REQUEST – INPUT FIELD LIST ....................................................................... 116
10.4
REQUESTPICKUP - OUTPUT ............................................................................................... 122

PAGE 4 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
10.5
REQUEST PICKUP RESPONSE – OUTPUT FIELD LIST .................................................................. 123
11. APPENDIX....................................................................................................................... 124
12.

SERVICE INPUT/OUTPUT EXAMPLES FOR RATEREQUEST ............................................ 134

13.

SERVICE INPUT/OUTPUT EXAMPLES FOR SHIPMENTREQUEST .................................... 139

14.

SERVICE INPUT/OUTPUT EXAMPLES FOR SHIPMENTDELETEREQUEST........................ 143

15.

SERVICE INPUT/OUTPUT EXAMPLES FOR TRACKINGREQUEST .................................... 145

16.

SERVICE INPUT/OUTPUT EXAMPLES FOR EPOD ........................................................... 150

17.

HELPFUL XML AND WEB SERVICES LINKS .................................................................... 163

PAGE 5 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

1. INTRODUCTION
1.1 DHL EXPRESS GLOBAL WEB SERVICES OVERVIEW
The DHL Express Global Web Services are a set of operations offering DHL’s core services like
capability, rating or booking a pickup request to any customer. This enables the customer to
integrate these services seamlessly into their own IT infrastructure. Customers can then ask for the
available products and their prices (where applicable) online as well as creating a shipment together
with a courier pickup.
This document describes how to integrate these services to your own applications and is intended as
a user guide for developers.

1.2 REQUIREMENTS – TECHNICAL SKILLS
Technically speaking, the DHL Express Global Web Services is a set of Operations accessible by a
standardized web protocol. Each operation can be called by a client application to request shipment
capability, estimated shipping price or even book a pickup of a shipment. Client applications will
request a certain operation to be executed with the application specific request data. The DHL
Express Global Web Services then responds synchronously by sending back response data in a
standard pre-defined format. The client application can then process the response data to complete
the subsequent workflow.
In order to access the web service, a SOAP or REST (jSON) protocol is used and developers should be
familiar with XML and have a basic understanding of web services. Please find a list of helping
resources in the Appendix.

1.3 REQUIREMENTS – BUSINESS UNDERSTANDING
Developers who plan to connect their tools or services to the DHL Customer Web Services should
also have a closer look into DHL’s product and services offering. More details about DHL products
and services are available at www.dhl.com and your DHL Sales representative.

PAGE 6 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

2. DHL EXPRESS GLOBAL WEB SERVICES OVERVIEW
There are some main points that must be noted before getting started with the DHL Express Global
Web Services integration •

The DHL customer web services consist of Port types and bindings that contain
information about the service operation, service endpoints and service location.

2.1 WEB SERVICE DEFINITION LANGUAGE AND REFERENCE DOCUMENTS
These documents will be used to integrate to the DHL Express Global Web Services, including WSDL
and SOAP UI project.
Your DHL contact can provide the production endpoint upon completion of certification
testing.

Reference

Description

WSDL
Description

RateRequest
ShipmentRequest
ShipmentDeleteRequest

Document

https://wsbexpress.dhl.com:443/snd
pt/expressRateBook?WSDL

WSDL
Description

TrackingRequest

https://wsbexpress.dhl.com:443/snd
pt/glDHLExpressTrack?WSDL

WSDL
Description

DocumentRetrieve (ePOD)

https://wsbexpress.dhl.com:443/snd
pt/getePOD?WSDL

WSDL
Description

updateShipment

https://wsbexpress.dhl.com:443/snd
pt/updateShipment?WSDL

WSDL
Description

requestPickup

https://wsbexpress.dhl.com:443/snd
pt/requestPickup?WSDL

Testing DHL Web Services with SOAP UII
The open source product SoapUI (http://www.soapui.org/) provides advanced support for testing
Web Services. Prior to development cycle, this tool can be used to independently verify the DHL
services in a test environment, and provide verification and context during the system development
life cycle. It is also useful in providing functionality context to the consumer prior to development
and independently validating security credentials.
Validation of the Input Data the Input data
The input data for the DHL Express Global Web Services is validated in several steps. The first step is
general XML validation based on data cardinality and data content restrictions defined by the
request message format (i.e. schema validation). In a second step, several business rules are applied
on the passed data. The results of these validations are placed in the result message of the service
operation. The service operation always delivers a result message. All errors or validation errors are
stored in this result messages. Please refer to the Appendix for complete list of error codes.

PAGE 7 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

2.2 SECURITY AND AUTHENTICATION
External Web Service calls from the customer to DHL will be handled through the DHL Web Services
Broker. The Web Services Broker is an XML and web services gateway used by DHL providing
governance, security, virtualization, and enhanced performance for web service transactions.
The primary transport protocol for these calls is https (standard port 443). For this solution, the DHL
Web Service Broker will validate that the messages are well formed and provide security and data
encryption. DHL utilizes WS-Security features.

Authentication using WS-Security
WS-Security offers a general-purpose mechanism for associating security tokens with message
content. The specification defines three approved token types, but for the purposes of these
services, UsernameToken will be used.
For example, the UsernameToken Profile describes how a Web service client can supply a
UsernameToken as a way to identify the requestor by a username and by supplying a password.
The SOAP header also requires the setting of Password Type as ‘PasswordText’. The following XML
snippet shows a sample WS-Security UsernameToken:

...
...
...
...

To authenticate using WS-Security for DHL Web Services, the consumer would need to add a SOAP
header to the SOAP envelope. For REST (jSON) the basic authentication will be used. This header
would contain the WS-Security information.
For more information about this please take a look into http://docs.oasis-open.org/wss/

User access rights
The applicable statement for user access relates to the authentication properties enforced at the
web service broker. Authentication details will be stored on the Web Service broker as a
configuration, and this solution assumes the customer will have established integration credentials at
application level. Credentials will not be managed at the customer user level.
Example:
Customer XYZ is building a web portal ABC with internal user administration. This web portal will
call the DHL Express Global Web Services. Just the application itself will get access to the DHL
Express Global Web Services and not each user registered in the application ABC.

How to get access?
The authentication credentials will be provided by your DHL point of contact for the integration
project.

PAGE 8 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

3. WHAT WEB SERVICES OPERATIONS ARE AVAILABLE?
For the orchestrated DHL web services offering, there are the following operations available for use.

a) RateRequest – This service allows the customer to input characteristics about a
prospective shipment, and outputs the corresponding available DHL products, along with
rate estimates and estimated delivery date/time.
b) ShipmentRequest – This service allows the customer to input characteristics about a
requested shipment and pickup, and outputs reference information (waybill and piece ID)
as well as a shipping label. If a pickup has been requested then the pickup confirmation
number will also be sent back as an output.
c) ShipmentDeleteRequest – This service allows the customer to request the deletion of a
pickup, if it was requested in the original ShipmentRequest.
d) TrackingRequest – This service allows the customer to input specific waybill numbers,
and outputs tracking checkpoint information at the shipment or piece level.
e) DocumentRetrieve – This service allows the customer to input parameters indicating
which ePOD or ePODs is requesting and the content of the ePODs. The operation
outputs the ePOD(s) as a base64 encoded string.
f) updateShipment – This service allows the customer to add pieces to a previously
created shipment that has not been picked up/scanned by DHL and is for the same day.
The term used for this process is Shipment Consolidation
g) requestPickup – This service allows for a stand-alone pickup request to be sent to the
DHL Express Customer Services team for Export and Import bookings.

The services are called independently, but can also be used in concert (i.e. using output from one
service as input into the next service) to meet the consumer requirements.

SOAP endpoints for WSDL schemas
Reference
WSDL
Description
WSDL
Description

Description
a)
b)
c)
d)

RateRequest
ShipmentRequest
ShipmentDeleteRequest
TrackingRequest

Document
https://wsbexpress.dhl.com:443/snd
pt/expressRateBook?WSDL
https://wsbexpress.dhl.com:443/snd
pt/glDHLExpressTrack?WSDL

WSDL
Description

e) DocumentRetrieve (ePOD)

https://wsbexpress.dhl.com:443/snd
pt/getePOD?WSDL

WSDL
Description

https://wsbexpress.dhl.com:443/snd
pt/updateShipment?WSDL

WSDL
Description

g) requestPickup

updateShipment

https://wsbexpress.dhl.com:443/snd
pt/requestPickup?WSDL

PAGE 9 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

REST endpoints
Service

Endpoint URL

RateRequest

https://wsbexpress.dhl.com/rest/sndpt/RateRequest

ShipmentRequest

https://wsbexpress.dhl.com/rest/sndpt/ShipmentRequest

DeleteShipment

https://wsbexpress.dhl.com/rest/sndpt/DeleteShipment

TrackingRequest

https://wsbexpress.dhl.com/rest/sndpt/TrackingRequest

DocumentRetriev
e(ePOD)

https://wsbexpress.dhl.com/rest/sndpt/getePOD

UpdateShipment

https://wsbexpress.dhl.com/rest/sndpt/UpdateShipment

RequestPickup

https://wsbexpress.dhl.com/rest/sndpt/RequestPickup

PAGE 10 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

4. RATEREQUEST
4.1 RATEREQUEST - DESCRIPTION
The Rate request will return DHL’s product capabilities (products, services and estimated delivery
time) and prices (where applicable) for a certain set of input data.
Using the shipper and receiver address as well as the dimension and weights of the pieces belonging
to a shipment, this operation returns the available products and service including the shipping price
(where applicable) and the potential delivery date considering the planned pickup date.
A shipment request can just be successfully executed (assuming the same input data) for a product
and service combination which is returned by the rate request.

4.2 RATEREQUEST - INPUT
The following diagram shows an overview of the request input structure.
Within the RateRequest, the ClientDetail is an optional node for reference use, and does not affect
functionality. The critical elements are contained within the RequestedShipment node.
4.2.1

RateRequest Schema Diagram

Each of the individual sections of RequestedShipment is represented below in schema diagram, with
context, and a detailed description of each field follows in the Input Field List.

PAGE 11 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
4.2.2

RateRequest Input: DropOffType

The DropoffType is used to indicate whether a scheduled pickup is required as part of the
consideration for the rate request. There are two possible values to indicate whether a pickup is
considered. The possible values are as follows;

•

REGULAR_PICKUP – The pickup location is already serviced by regularly scheduled courier
pickup and an additional pickup does not need to be considered for this service.

•

REQUEST_COURIER- The rating response returns products, for which the pickup capability is
given, based on ShipmentTimeStamp.

4.2.3

RateRequest Input: NextBusinessDay

The NextBusinessDay field is used to indicate that the Rate Request process should query the next
business day for available services if the current request is beyond cutoff, or occurs on a weekend or
holiday. There are three possible use cases for this field.

•

NextBusinessDay is null (node not included) – This represents the base functionality. In this
case, the process will filter out any services which has a pickup date <> to the requested ship
date. For example, if the requested shipment date is a Monday, but the next available
pickup date is a Tuesday, this option will not present these services.

•

NextBusinessDay = N – This case will behave identically to the above null case.

•

NextBusinessDay = Y – This case will provide services for the subsequent business day, if
available.

PAGE 12 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
4.2.4

RateRequest Input: Ship

The Ship section outlines the shipper and receiver for the specific rate request. In the context to rate
requests, the street address elements are not critical, since capability and rate are determined based
on city, postal code, and country code. Please note that the Shipper and Recipient structures are
identical.

4.2.5

RateRequest Input: Packages

The Packages section details the weight and dimensions of the individual pieces of the shipment.
For example, the shipper may tender a single shipment with multiple pieces, and each piece may
have a distinct shipping label. In this context, a RequestedPackage node represents each individual
piece, and there is a limitation of 50 RequestedPackage nodes in the request.

PAGE 13 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

4.2.6

RateRequest Input: ShipmentTimeStamp

The ShipmentTimeStamp node is the date/time stamp (including GMT offset) when the shipment
will be ready for shipping and tendered to the carrier, either as part of a scheduled pickup, regular
pickup, station dropoff, etc. Please note that the timestamp for this event does not represent the
time of the execution of the service, and should not be considered a system event.

4.2.7

RateRequest Input: UnitOfMeasurement

The UnitOfMeasurement node conveys the unit of measurements used in the operation. This single
value corresponds to the units of weight and measurement which are used throughout the message
processing. The value of ‘SI’ corresponds to KG and CM, respectively, while the value of ‘SU’
corresponds to LB and IN, respectively.

4.2.8

RateRequest Input: Contents

The Contents node details whether a shipment is non-dutiable (value DOCUMENTS) or dutiable
(NON_DOCUMENTS). Depending on the nature of the contents of the shipment, is customs duties
are applicable, different products may be offered by the DHL web services.

4.2.9

RateRequest Input: DeclaredValue

The DeclaredValue contains the value of the shipment. The field is optional decimal with a total
length of 18 characters 3 corresponding to the fraction part.

PAGE 14 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
4.2.10

RateRequest Input: DeclaredValueCurrencyCode

This is to specify the currency code for the declared value. It is an optional field with a length of 3
characters.

4.2.11

RateRequest Input: PaymentInfo

The PaymentInfo node details the potential terms of trade for this specific shipment, and the schema
itself defines the possible enumerated values for this field.

4.2.12

RateRequest Input: Account

The Account field details the DHL account number used for the rate request. When the account
number is in this field, this account number serves as both the shipper account as well as payer
account. DHL recommends the use the more robust Billing structure.

4.2.13

RateRequest Input: Billing

The Billing structure functions as a more robust alternative to the single Account field, and allows for
using a payer account different than the shipper account (to allow for bill-to receiver or bill-to third
party). The web service requestor should use either the Account field or the Billing structure to
communicate account information, and DHL recommends the Billing structure.

4.2.14

RateRequest Input: SpecialServices

The SpecialServices section communicates additional shipping services, such as Insurance (or
Shipment Value Protection).

PAGE 15 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

4.2.15

Rate Request Input: RequestValueAddedServices

Flag used to request all the existing special services for the requested product in the response
message. If the value is "Y" all the additional services available for the product selected will be
returned. The default value is "N".

PAGE 16 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

4.3 RATEREQUEST – INPUT FIELD LIST
Rate Request fields

Mandatory
/Optional

Value
constraints

Comments

RateRequest
./ClientDetail
Sso

This field is for internal use only

plant

This field is for internal use only

./RequestedShipment
Possible values:
- REGULAR_PICKUP, the pickup location
is already served by a regular courier
and an additional pickup does not need
to be considered for this service
- REQUEST_COURIER

DropOffType

NextBusinessDay

The rating response returns products for
which the pickup capability is given,
based on ShipmentTimeStamp.
AN 1

Possible values include Y, N

AN 1

If the value is "Y" all the additional
services available for the product
selected will be returned. The default
value is "N".

StreetLines

AN 35

Shipper street name and number

StreetName

AN 35

Shipper street name should already be
sent as separate attribute if feasible.

StreetNumber

AN 15

Shipper street number should be sent as
separate attribute, if feasible.

StreetLines2

AN 35

Shipper additional address information

StreetLines3

AN 35

Shipper additional address information

City

StateOrProvinceCode

AN 2

2 letter state code for the USA only

PostalCode

AN 12

Shipper postal code

RequestValueAddedServi
ces
./Ship
./Shipper

AN 35

Shipper city name

PAGE 17 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

CountryCode

AN 2

ISO 2 character codes of the Shipper
country.

AN 35

Recipient street name and number

AN 35

Recipient street name should be sent as
separate attribute if feasible.

AN 15

Recipient street number should be sent
as separate attribute, if feasible.

./Recipient
./Address
StreetLines

StreetName

StreetNumber

StreetLines2

AN 35

Recipient additional address information

StreetLines3

AN 35

Recipient additional address information

City

AN 35

Recipient city name

StateOrProvinceCode

AN 2

2 Letter State code for the USA only

PostalCode

AN 12

Recipient postal code

AN 2

ISO 2 character codes of the Receiver
country.

CountryCode

./Packages (1:1)
./RequestedPackages (1:M)

@number

Weight

No length
constraint
Max 50
occurrences

Will be used as Piece Sequence number
and returned in the response.
Sum of the weight of the individual
pieces/packages the rating request is
for.

15.3 D

Length

5.1 D >=1

Length of the piece listed.

Width

5.1 D >=1

Width of the piece listed.

Height

5.1 D >=1

Height of the piece listed.

./Dimensions

This timestamp identifies the ready date
and time of the rated shipment.
It needs to be provided in the following
format with GMT offset
YYYY-MM-DDTHH:MM:SSGMT+k
ShipTimestamp

2010-02-26T17:00:00GMT+01:00

PAGE 18 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

If the date is on a public holiday, sunday
or any other day where there is no
pickup, the rate request will return this
in the error code as it is a non valid
request.
Possible values:
- SI, international metric system (KG,
CM)
- SU, UK, US system of measurement
(LB, IN)
UnitOfMeasurement

N/A

The unit of measurement for the
dimensions of the package.
Possible values
- DOCUMENTS

Content

N/A

- NON_DOCUMENTS

DeclaredValue

15.3

Declared value of the shipment

DeclaredValueCurrecyCo
de

AN 3

3 character currency code for the
declared value

PaymentInfo

N/A

Possible values:
- See schema enumeration

N/A

The DHL account number that is used
for the shipment. Internally attached to
this account are the customer specific
rates. Please note if you use the
tag then the Billing section
below is not needed

N/A

The DHL account number used for the
shipment. Used as the shipper account
number. Please note if you use this
billing section then the above
tag is not needed.
is mandatory
then.

Account

Billing

ShipperAccountNumber

Possible values:

ShippingPaymentType

AN 1

- S (use ShipperAccountNumber as
payer)
- R (use BillingAccountNumber as
bill-to receiver account number)
- T (use BillingAccountNumber as
bill-to third party account number)

PAGE 19 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

Please note if you use value R or T
in this tag then the next tag
is also
mandatory

BillingAccountNumber

N/A

The DHL account number used for the
shipment, if ShippingPaymentType is
equal to R or T.

AN 2

Enter II if you wish to get a quote for
Insurance with your prospect shipment.
If not needed then leave the
SpecialServices section out.

./SpecialServices
./Service

ServiceType

ServiceValue

15.3 D

Monetary value of service (e.g. Insured
Value) – this is needed if you wish to
get a quote on Insurance with your
prospect shipment

CurrencyCode

AN 3

Currency code) – this is needed if you
wish to get a quote on Insurance with
your prospect shipment

PaymentCode

AN 3

For future use.

StartDate

Date

For future use.

EndDate

Date

For future use.

TextInstruction

AN 50

For future use.

PAGE 20 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

4.4 RATEREQUEST - OUTPUT
The following diagram shows an overview of the rate response structure. The critical information to
derive from this response are the notification codes for the response, the products returned, the
estimated charges, and the expected delivery time for the shipment.

4.4.1

RateResponse Schema Diagram

Each of the individual sections of Rate Response is represented below in schema diagram, with
context, and a detailed description of each field follows in the Output Field List.
4.4.2

RateResponse Output: Notification

The Notification structure includes the result code and message, based on the results of the
processing. Successful messages will include a zero error code and no corresponding message,
while exceptions will be noted with both code and message.

PAGE 21 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

4.4.3

RateResponse Output: Service

For successful responses, there will be 1-to-M Service nodes returned, which will include all of the
information about the DHL product returned. A critical element of the Service structure is the @type
attribute, which designates the DHL global product code that corresponds to that service quotation.
The charges and delivery times for that product are in the subsequent nodes within Service.

4.4.4

RateResponse Output: TotalNet

For successful responses, the total net structure shows the summary of the net estimated charges
(plus currency) for a given Service. Please note that the subsequent nodes, under Charges, provides
line item detail of the estimated charge. Nevertheless, for consumers only interested in the total
estimate, these nodes will have the summary estimates.

4.4.5

RateResponse Output: Charges

While the previous section, TotalNet, provides a single summary charge, this section provides line
item visibility into the components of that charge and value added service codes that are available
for the prospect shipment. In this context, the sum of the charges communicated in this structure
will be equal to the charge in TotalNet. The Currency field will apply for all of the subsequent
charges, and the ChargeType is a description of the local charge code description for that charge.
The text in the ChargeType may vary, depending on locale.
Important: The field is the Value Added Service code you can use in your prospect
shipment when using ShipmentRequest. Please note that FF (Fuel Surcharge) should not be used as
this is automatically added during billing.
is the name of the service i.e. Shipment Insurance or Dangerous Goods

PAGE 22 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

4.4.6

RateResponse Output: DeliveryTime

The DeliveryTime field is provided for each Service, and details the local timestamp (based on
delivery location) when the shipment will be delivered by.

4.4.7

RateResponse Output: CutoffTime

The CutoffTime field is optionally provided for each Service, and details the local timestamp (based
on origin location) when the service offered in the response has its operational cutoff. This is the
timestamp when the shipment needs to be tendered to the courier in order to meet the cutoff for
that day’s shipping.

4.4.8

RateResponse Output: NextBusinessDayInd

The NextBusinessDayInd field is optionally provided for each Service, and is a Y/N indicator to alert
the consumer that the next available pickup date is beyond the requested shipment date. When the
Request NextBusinessDay flag is not used (or N), this value will always be N. Otherwise, this value
may have a value of Y or N, depending on how the next available pickup date relates to the
requested shipment date/time.

PAGE 23 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

4.5 RATE RESPONSE – OUTPUT FIELD LIST
Mandatory
Rate Response fields

/Optional

Value
constraints Comments

RateResponse
./Provider
M

Provider Code, always contains
DHL.

"@code"

Error > 0 or Success Code = 0

message

Response Message, see Error
codes for more details

"@type"

This is the code for the product for
which the delivery is feasible
respecting the input data from the
request.

"@account"

Not used.

This is the estimated date/time the
shipment will be delivered by for
the rated shipment and product
listed

This is the cutoff time for the
service offered in the response.
This represents the latest time
(local to origin) which the
shipment can be tendered to the
courier for that service on that
day.

This indicator has values of Y or
N, and tells the consumer if the
service in the response has a
pickup date on the same day as
the requested shipment date (per
the request).

Currency

This the currency of the rated
shipment for the product listed.

Amount

This is the total prize of the rated

"@code"
./Notification

./Service

DeliveryTime

CutoffTime

NextBusinessDayInd
./TotalNet

PAGE 24 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
shipment for the product listed.
./Charges

This the currency for all line item
charges listed in the Charge
section

ChargeCode

Special service or extra charge
code – this is the code you would
have to use in the
ShipmentRequest message if you
wish to add an optional Service
such as Insurance.

ChargeType

Name of the Value Added Service

ChargeAmount

The charge amount of the line
item charge.

Currency
./Charge (1:M)

PAGE 25 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

5. SHIPMENTREQUEST
5.1 SHIPMENTREQUEST - DESCRIPTION
The ShipmentRequest Operation will allow you to generate an AWB number and piece IDs, generate
a shipping label, transmit manifest shipment detail to DHL, and optionally book a courier for the
pickup of a shipment. The key elements in the response of the Shipment Request will be a base64
encoded PDF label and the Shipment and Piece identification numbers, which you can use for
tracking on the DHL web site.
While the RateRequest and ShipmentRequest services can be used independently, DHL recommends
the use of RateRequest to first validate the products available for the shipper/receiver. The global
product codes which are output during the RateResponse can be used directly as input into the
Shipment Request, as both perform similar validations in terms of service capability.

5.2 SHIPMENTREQUEST - INPUT
The following diagram shows an overview of the request input structure.
Within the ShipmentRequest, the ClientDetail is an optional node for reference use, and does not
affect functionality. The critical elements are contained within the RequestedShipment node.

PAGE 26 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

5.2.1

ShipmentRequest Schema Diagram

Each of the individual sections of RequestedShipment is shown below in schema diagram, with
context, and a detailed description of each field follows in the Input Field List.

PAGE 27 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

5.2.2

ShipmentRequest Input: ShipmentInfo

The ShipmentInfo section provides general shipment detail, pertaining to operational and billing
features. The Billing and Special Services sub-structures are detailed in below sections.

5.2.3

ShipmentRequest Input: ShipmentInfo DropOffType

The DropOffType is a required field with two possible values, and these values are used to determine
whether a driver pickup will be scheduled as part of this orchestrated service. If a pickup is
requested (REQUEST_COURIER), the web service consumer can expect the optional
DispatchConfirmationNumber to be populated in the response. Otherwise, no pickup will be
scheduled, and no pickup reference information will be provided in the response.

5.2.4

ShipmentRequest Input: ShipmentInfo ServiceType

The ServiceType is a required field which corresponds to the DHL global product code, which
describes the product requested for this shipment. These product codes are available as output
from Rate Request, and the product codes provided will be validated against the origin-destination
requested in the Shipment Request.

PAGE 28 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

5.2.5

ShipmentRequest Input: ShipmentInfo Account

The Account field is a required business field, but is optional within the schema as this information
can be provided in one of two structures. It must either be provided in this field or within the Billing
structure (see below). DHL recommends use of more robust Billing structure. This field corresponds
to the Shipper account number and usage of this field presumes that the account will also be used
as the Payer account. This field is validated as a valid account for usage within this process.

5.2.6

ShipmentRequest Input: ShipmentInfo Billing

If the Billing structure is included, the first two fields are required. This schema structure conveys
the Shipper Account Number, as well as extensibility to convey receiver or third party account
number as payer.

5.2.7

ShipmentRequest Input: ShipmentInfo SpecialServices

The SpecialServices section communicates additional shipping services, such as Insurance (or
Shipment Value Protection). For example, to support Insurance, the ServiceType would have a value
of ‘II, which the ServiceValue and CurrencyCode containing the insured value and currency,
respectively. Please note that for all other Value Added Service like Saturday Delivery, Dangerous
goods etc you do not need to declare the service charge and currency.

PAGE 29 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

5.2.8

ShipmentRequest Input: ShipmentInfo Currency

The Currency field is a required field which details the currency for the Customs Value.

5.2.9

ShipmentRequest Input: ShipmentInfo UnitOfMeasurement

The UnitOfMeasurement node conveys the unit of measurements used in the operation. This single
value corresponds to the units of weight and measurement used throughout the message
processing. The value of ‘SI’ corresponds to KG and CM, respectively, while the value of ‘SU’
corresponds to LB and IN, respectively.

5.2.10

ShipmentRequest Input: ShipmentIdentificationNumber

The ShipmentIdentificationNumber should only be used if discussed with your DHL Express IT
Consultant. This field (when enabled by DHL Express) allows you to use your own DHL Express
allocated Waybill number range to be used – please note that the norm is to not use this field and
each shipment will automatically have its own Waybill number assigned when creating the
shipment.

5.2.11

ShipmentRequest Input: UseOwnShipmentIdentificationNumber

The UseOwnShipmentIdentificationNumber should only be used if discussed with your DHL Express
IT Consultant. This field (when enabled by DHL Express) allows you to use your own DHL Express
allocated Waybill number range to be used and tells the WebServices that you wish to provide your

PAGE 30 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
own Waybill number for each shipment – please note that the norm is to not use this field and each
shipment will automatically have its own Waybill number assigned when creating the shipment.

5.2.12

ShipmentRequest Input: ShipmentInfo LabelType

The LabelType node conveys the label type used in the operation. It is an optional field. This single
value corresponds to the label type returned to customer. Customer can send one of the four
values in this field (PDF, ZPL, EPL, LP2). If customer didn’t include this tag, the default is PDF.

5.2.13

ShipmentRequest Input: ShipmentInfo LabelTemplate

The LabelTemplate node conveys the label template used in the operation. It is an optional field.
This single value corresponds to the label template used to generate labels. – please check with
your DHL Express IT representative which templates meets your requirements. If this tag is not
included, then the default ofECOM26_84_001 will be used

PAGE 31 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

5.2.14

ShipmentRequest Input: ShipmentInfo ArchiveLabelTemplate

The ArchiveLabelTemplate node conveys the label template used in the operation. It is an optional
field. This single value corresponds to the label template used to generate the Archive labels. Please
check with your DHL Express IT representative which templates meets your requirements. If this tag
is not included, then the default of ARCH_8x4 will be used

5.2.15

ShipmentRequest Input: ShipmentInfo PaperlessTradeEnabled

The PaperlessTradeEnabled node is an optional flag indicating if the request includes a Paperless
Trade image/document.

5.2.16 ShipmentRequest Input: ShipmentInfo PaperlessTradeImage
The PaperlessTradeImage node is for the base64 encoded string with the image of export
documentation (Commercial or Proforma Invoice). Allowed formats are JPEG, PDF (incl. multi-page),
PNG. Maximum file size is 1MB A4.

5.2.17

ShipmentRequest Input: ShipmentTimeStamp

5.2.18

ShipmentRequest Input: PickupLocationCloseTime

The PickupLocationCloseTime node identifies the pickup location close time (i.e. what time do the
premises where the collection is supposed to happen close). The value must be in local time. The
value component must be HH:MM (using a 24-hours clock format, e.g. 14:00). This node is optional
and must be used with DropOffType = ‘REQUEST_COURIER’.

5.2.19

ShipmentRequest Input: SpecialPickupInstruction

The SpecialPickupInstruction node details any special instructions you wish to send to the courier for
the order pick-up. This node is optional and must be used with DropOffType = ‘REQUEST_COURIER’.

PAGE 32 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
5.2.20

ShipmentRequest Input: PickupLocation

The PickupLocation node provides information on where the package should be picked up by DHL
courier. This node is optional and must be used with DropOffType = ‘REQUEST_COURIER’.

5.2.21

ShipmentRequest Input: PaymentInfo

The PaymentInfo node details the potential terms of trade for this specific shipment, and the schema
itself defines the possible enumerated values for this field.

5.2.22

ShipmentRequest Input: International Detail

The InternationalDetail section conveys data elements for international shipping.
The NumberOfPieces field is used to transmit the number of pieces in shipment, but for validation
purposes this information is calculated based on the number of pieces in the message.
The Description field is used as a description of goods for the label and manifest.
The CountryOfManufacture, Quantity, and UnitPrice are field which are available for customs
processing, but currently not mapped.
The CustomsValue field communicates the customs value of the shipment, used for manifesting.
The USFilingTypeValue is used for the US AES4, FTR and ITN numbers to be printed on the Transport
Label

5.2.23

ShipmentRequest Input: Content

PAGE 33 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

5.2.24

ShipmentRequest Input: ExportReference

An optional field ExportReference exists in the InternationalDetail segment to support the
requirement for origin specific export references, such as EEI/ITN reference information required for
the US export. An example of the node contents is below.
AES X20101010123456

5.2.25

ShipmentRequest Input: OnDemandDeliveryOptions (0:1)

The OnDemandDeliveryOptions section conveys data elements for On Demand Delivery (ODD)
service.
The Delivery option is to define which on demand delivery option you wish to choose optionally
when your shipment is to be delivered. The options are:
-

TV (Deliver to a DHL Express Servicepoint)

SW (Leave with neighbour)

SX (Signature release)

The Location is mandatory if the above delivery option is SX and should advise DHL where exactly to
leave the shipment (ie.front door etc)
The instructions is optional – additional information that is useful for the DHL Express courier
The GateCode is optional – is the entry code to gain access to an apartment complex or gate
The LWNTypeCode is mandatory if the above delivery option is SW . The possible values are
-

N – Leave with neighbour

C – Leave with concierge

The NeighbourName Is mandatory if the delivery option is SW and the LWNTypeCode is N
(Neighbour) – this is where the name of the neighbour is required
The NeighbourHouseNumber Is mandatory if the delivery option is SW and the LWNTypeCode is N
(Neighbour) – this is the house number of the neighbour
The AuthorizerName is mandatory if delivery option is SX – this is the person that this authorised to
sign and receive the DHL Express shipment.
The SelectedServicePointID is mandatory if delivery option is TV – this is the unique DHL Express
Service point location ID of where the parcel should be delieverd (please contact your local DHL
Express Account Manager to obtain the list of the servicepoint IDs)

PAGE 34 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

PAGE 35 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

5.2.26

ShipmentRequest Input: Ship

The Ship section outlines the shipper, receiver and optional pickup address for the specific shipment
request. In the context to rate requests, the street address elements are not critical, since capability
and rate are determined based on city, postal code, and country code. Please note that the Shipper,
Pickup, BookingRequestor and Recipient structures are identical.
If included in the message, this optional Pickup structure will be used as precedence over the
Shipper address when the Pickup service is invoked. The Pickup address will not be used in
manifesting.

PAGE 36 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
5.2.27

ShipmentRequest Input: Packages

The Packages section details the contents of individual pieces (or discrete shipping containers) within
the shipment. The minimum number of packages or pieces in a shipment is one and the upper limit
is 50.
The InsuredValue field is an optional field in the Packages section which will be deprecated from the
interface, as the SpecialServices section should be used to convey Insured Value.
The Weight and Dimensions fields represent the weight and dims of the individual pieces.
The CustomerReferences field is used as the Piece Reference and the first instance is also used as the
Shipment Reference. Currently only the Shipment Reference appears on the label.

5.2.28

ShipmentRequest Input: DangerousGoods

The DangerousGoods section indicates if there is dangerous good content within the shipment. The
ContentID node contains the Content ID for the Dangerous Good classification (please contact your
DHL Express representative for the list of the codes). If the shipment is Dry Ice UN1845 (Content ID –
901) then the additional node needs to be populated - “DryIceTotalNetWeight.”
If is the shipment is “Excepted Quantities” then the additional node needs to be populated –
“UNCode”

PAGE 37 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

5.3 SHIPMENT REQUEST – INPUT FIELD LIST

Shipment Request
fields

Values
M
or
Comments
/O Constr
aints

ShipmentRequest
./ClientDetail
sso

This field is for internal use only

plant

This field is for internal use only

./RequestedShipment
./ShipmentInfo
@provider

"DHL"
Possible values:
-REGULAR_PICKUP, the pickup location is already
served by a regular courier and an additional pickup
does not need to be considered for this service
- REQUEST_COURIER

DropOffType
ServiceType

The rating response returns products for which the
pickup capability is given, based on
ShipmentTimeStamp.

The shipping product requested for this shipment,
corresponding to the DHL Global Product codes.

AN 1

The customer account to be used as payer in the
request. If the tag is used then there is
no need to populate the Billing section further down
below in this table as the tag will
override any other accounts entered.

Account

M/
O

AN 9

However if you do wish to charge your shipment to
a third party or receiver then please leave the
ACCOUNT section out and populate the Billing
section below

Currency

AN 3

The currency of the monetary values presented in
the request.
The unit of measurement for the dimensions of the
package.

UnitOfMeasurement

AN 2

PAGE 38 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

Possible values:
- SI, international metric system (KG, CM)
- SU, UK, US system of measurement (LB, IN)

ShipmentIdentificatio
nNumber

The shipment identification number does not need
to be transmitted in the request as the operation
will assign a new number and return it in the
response. Only used when
“Y”,“ UseOwnShipmentdentificationNumber set to Y and
N”
this feature enabled within client profile.
Y or 1 -= allows you to define your own AWB in the
tag below
N or 0 = Auto-allocates the AWB from DHL Express
You can request your own AWB range from your
DHL Express IT consultant and store these locally in
your integration however this is not needed as if you
leave this tag then DHL will automatically assign the
AWB centrally.
In addition this special function needs to be enabled
for your username by your DHL Express IT
Consultant.

UseOwnShipmentIde
ntificationNumber

PackagesCount

N/A

SendPackage

N/A

Number of packages which need to be processed.

Possible values:
- PDF
- ZPL
- EPL
LabelType

LabelTemplate

ArchiveLabelTemplate

AN 3

- LP2

Any valid DHL Express label template (please contact
your DHL Express IT representative for a list of labels)
– If this node is left blank then the default DHL
AN 20 ecommerce label template will be used.

Any valid DHL Express archive label template (please
contact your DHL Express IT representative for a list
of labels) – If this node is left blank then the default
AN 20 DHL ecommerce label template will be used.
Possible values (case sensitive):

PaperlessTradeEnable
d

N1 or
A5

- true
- false

PAGE 39 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

-0
-1
PaperlessTradeImage

Base64
binary Base64 encoded image. Max size 1MB A4
This timestamp identifies the pickup date and time
of the rated shipment.
It needs to be provided in the following format with
GMT offset

ShipTimestamp

YYYYMMDDT24
HH:M
M:SS
GMT+
M
k

YYYY-MM-DDTHH:MM:SSGMT+k
2010-02-26T17:00:00GMT+01:00
If the date is on a public holiday, Sunday or any
other day where there is no pickup, the rate request
will return this in the error code as it is a non valid
request.
This node identifies the closing time of your pickup
location in local time.
It needs to be provided in the following 24-hours
time format:
HH:mm

PickupLocationCloseTi
me
O

HH:m
m

SpecialPickupInstructi
on

This node details special pickup instructions you may
AN 75 wish to send to the DHL Courier

PickupLocation

This node provides information on where the
AN 40 package should be picked up by DHL courier.

Sample: 17:00

Possible values:
PaymentInfo

AN 3

- See schema enumeration

N/A

The DHL account number used for the shipment.
Used as the shipper account number. Please note if
you use this billing section then the above
tag is not needed.
is mandatory then.

./Billing
O
ShipperAccountNumb
er

Possible values:
- S (use ShipperAccountNumber as payer)
- R (use BillingAccountNumber as bill-to receiver
account number)

ShippingPaymentType

M/
O

AN 1

T (use BillingAccountNumber as bill-to third party
account number) Please note if you use value R or T
in this tag then the next tag
is also mandatory

PAGE 40 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

BillingAccountNumbe
r

The DHL account number used for the shipment, if
ShippingPaymentType is equal to R or T.

AN 9

ServiceType

AN 2

ServiceValue

CurrencyCode

AN 3

Currency code

PaymentCode

AN 3

For future use.

StartDate

Date

For future use.

EndDate

Date

For future use.

TextInstruction

AN50

For future use.

./SpecialServices
./Service
Enter II if you wish to get a quote for Insurance with
your prospect shipment. If not needed then leave
the SpecialServices section out.

15.3 D Monetary value of service (currently only applicable
for Insurance)

./InternationalDetail
./Commodities
NumberOfPieces
Description
CountryOfManufactu
re

M
O

The number of pieces in the shipment

AN 135
The description of the content of the shipment.
AN 2

The country of manufacture of the content of the
shipment.

N 10

The quantity of the items in the shipment, e.g. 3
books.

Quantity

UnitPrice

Price per item in the shipment, e.g. 7.50 € if one of
18.3 D the books costs 7.50€.

CustomsValue

18.3 D The value which needs to be declared for customs.
Possible values
- DOCUMENTS

Content

N/A

- NON_DOCUMENTS

USFillingTypeValue

AN 20 The US filing Type Value for shipments from the US

ExportReference

AN 40 Export Reference field, appears on label.

./OnDemandDeliveryOptions (please note if you use this optional segment then
the Buyer segment is also required)
DeliveryOption

M “TV”,” The Delivery option is to define which on demand
SW”,” delivery option you wish to choose optionally when
SX” your shipment is to be delivered. The options are:

PAGE 41 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

Location
Instructions
GateCode

Mandatory if the above delivery option is SX and
should advise DHL where exactly to leave the
shipment (ie.front door etc)

AN15

Additional information that is useful for the DHL
AN110 Express courier

AN10

Entry code to gain access to an apartment complex
or gate
Mandatory if the above delivery option is SW . The
possible values are

LWNTypeCode

NeighbourName
NeighbourHouseNum
ber

AuthorizerName

N – Leave with neighbour
“N”,”
C”
C – Leave with concierge

AN20

Mandatory if the delivery option is SW and the
LWNTypeCode is N (Neighbour) – this is where the
name of the neighbour is required

AN20

Mandatory if the delivery option is SW and the
LWNTypeCode is N (Neighbour) – this is the house
number of the neighbour

AN20

Mandatory if delivery option is SX or SW– this is the
person that this authorised to sign and receive the
DHL Express shipment

SelectedServicePointI
D

AN6

Mandatory if delivery option is TV – this is the
unique DHL Express Service point location ID of
where the parcel should be delieverd (please contact
your local DHL Express Account Manager to obtain
the list of the servicepoint IDs)

RequestedDeliveryDat
e

AN29

Reserved for future use

PersonName

AN 45 A contact name of a person who will ship the
shipment.

CompanyName

AN 35 The company name the person is working in.

PhoneNumber

The contact person phone number. In case of
AN 25 questions, this person can be called by the courier.

EmailAddress

AN 50 The email address of the contact person.

MobilePhoneNumber

AN 25 The mobile phone number of the contact person.

AN 35 The street line should contain street name and

./Ship
./Shipper
./Contact

./Address
StreetLines

PAGE 42 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
number of the shipper.
StreetName

Shipper street name should be sent as separate
AN 35 attribute if feasible.

StreetNumber

Shipper street number should be sent as separate
AN 15 attribute, if feasible.

StreetLines2

AN 35 Shipper additional address information

StreetLines3

AN 35 Shipper additional address information

City

AN 35 Shipper city name

StateOrProvinceCode

AN 2

PostalCode

AN 12 Shipper postal code

CountryCode

AN 2

PersonName

AN 45 A contact name of a person who will give the
shipment.to the courier

CompanyName

AN 35 The company name the person is working in.

PhoneNumber

The contact person phone number. In case of
AN 25 questions, this person can be called by the courier.

EmailAddress

AN 50 The email address of the contact person.

MobilePhoneNumber

AN 25 The mobile phone number of the contact person.

AN 35 The street line should contain street name and
number of the pickup place.

2 Letter state code for the USA only

ISO 2 character codes of the Shipper country.

./Pickup
./Contact

./Address
StreetLines

StreetName

Pickup street name should be sent as separate
AN 35 attribute if feasible.

StreetNumber

Pickup street number should be sent as separate
AN 15 attribute, if feasible.

StreetLines2

AN 35 Pickup additional address information

StreetLines3

AN 35 Pickup additional address information

City

AN 35 Pickup city name

StateOrProvinceCode

AN 2

PostalCode

AN 12 Pickup postal code

CountryCode

AN 2

2 Letter state code for the USA only

ISO 2 character codes of the Pickup country.

./BookingRequestor

PAGE 43 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

./Contact
PersonName

AN 45 A contact name of a person who is requesting the
pickup.

CompanyName

AN 35 The company name the person is working in.

PhoneNumber

The contact person phone number. In case of
AN 25 questions, this person can be called by the courier.

EmailAddress

AN 50 The email address of the contact person.

MobilePhoneNumber

AN 25 The mobile phone number of the contact person.

StreetLines

AN 35 The street line should contain street name and
number of pickup requestor

StreetName

Pickup street name should be sent as separate
AN 35 attribute if feasible.

StreetNumber

Pickup street number should be sent as separate
AN 15 attribute, if feasible.

StreetLines2

AN 35 Pickup additional address information

StreetLines3

AN 35 Pickup additional address information

City

AN 35 Pickup city name

StateOrProvinceCode

AN 2

PostalCode

AN 12 Pickup postal code

CountryCode

AN 2

./Address

2 Letter state code for the USA only

ISO 2 character codes of the Pickup Requestor
country.

./Buyer
./Contact
PersonName

AN 45

A contact name of a person who acts as Buyer

CompanyName

AN 35

The company name the person is working in.

PhoneNumber

AN 25

The contact person phone number. In case of
questions, this person can be called by the courier.

EmailAddress

AN 50

The email address of the contact person.

MobilePhoneNumber

AN 25

The mobile phone number of the contact person.

AN 35

The street line should contain street name and
number of the shipper.

./Address
StreetLines

StreetName

AN 35

Pickup street name should be sent as separate
attribute if feasible.

PAGE 44 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

StreetNumber

AN 15

Pickup street number should be sent as separate
attribute, if feasible.

StreetLines2

AN 35

Pickup additional address information

StreetLines3

AN 35

Pickup additional address information

City

AN 35

Pickup city name

StateOrProvinceCode

AN 2

2 Letter state code for the USA only

PostalCode

AN 12

Pickup postal code

CountryCode

AN 2

ISO 2 character codes of the Buyer country.

./Recipient
./Contact
PersonName

AN 45 A contact name of a person who will ship the
shipment.

CompanyName

AN 35 The company name the person is working in.

PhoneNumber

The contact person phone number. In case of
AN 25 questions, this person can be called by the courier.

EmailAddress

AN 50 The email address of the contact person.

MobilePhoneNumber

AN 25 The mobile phone number of the contact person.

StreetLines

AN 35 The street line should contain street name and
number of the shipper.

StreetName

Recipient street name should be sent as separate
AN 35 attribute if feasible.

StreetNumber

Recipient street number should be sent as separate
AN 15 attribute, if feasible.

StreetLines2

AN 35 Recipient additional address information

StreetLines3

AN 35 Recipient additional address information

City

AN 35 Recipient city name

StateOrProvinceCode

AN 2

PostalCode

AN 12 Recipient postal code

CountryCode

AN 2

./Address

2 Letter state code for the USA only

ISO 2 character codes of the Receiver country.

./Packages (1:1)
./RequestedPackages (1:M)
@number

M Integer Running number of the packages.

PAGE 45 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

InsuredValue

N/A

Insurance values of the package.

Weight

M 15.3 D The weight of the package.
Y = allows you to define your own PieceID in the tag
below
N = Auto-allocates the PieceID from DHL Express
You can request your own Piece ID range from your
DHL Express IT consultant and store these locally in
your integration however this is not needed as if you
leave this tag then DHL will automatically assign the
piece ID centrally.

UseOwnPieceIdentific
ationNumber

In addition this special function needs to be enabled
“Y”,” for your username by your DHL Express IT
Consultant.
N”
You can request your own Piece ID range from your
DHL Express IT consultant and store these locally in
your integration however this is not needed as if you
leave this tag then DHL will automatically assign the
piece ID centrally.

PieceIdentificationNu
mber
PackageContentDescr
iption

AN35

If you wish to use this function then the above tag
UseOwnPieceIdentificationNumber needs to be set
as Y

AN70

This optional field allows you to provide the content
description on a piece level instead of Shipment
level.

5.1 D Length of the piece listed.
>=0.5

./Dimensions
Length

5.1 D
>=0.5 Width of the piece listed.

Height

5.1 D
>=0.5 Height of the piece listed.

CustomerReferences

AN 135
Customer Reference for the piece.

ContentId

AN 3

DryIceTotalNetWeight

Width

./DangerousGoods
./Content
Valid DHL Express Dangerous good content id
(please contact your DHL Express IT representative
for the relevant content ID code if you are shipping
Dangerous Goods)

This is a numeric string with up to 7 char (i.e.
AN 1-7 1000,00 or 1000.00)

PAGE 46 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

UNCode

Comma separated UN codes – eg. “UN7843268473”, “7843268473,123”

PAGE 47 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

5.4 SHIPMENTREQUEST - OUTPUT
The following diagram shows an overview of the shipment response structure. The critical
information to derive from this response are the notification codes for the response, the shipment
and piece identifiers returned, the encoded label image, and the optional pickup confirmation
reference.

5.4.1

ShipmentResponse Schema Diagram

Each of the individual sections of ShipmentResponse is shown below in schema diagram, with
context, and a detailed description of each field follows in the Output Field List.

5.4.2

ShipmentResponse Output: Notification

PAGE 48 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

5.4.3

ShipmentResponse Output: PackagesResult

The PackagesResult provides the DHL piece ID associated to each RequestedPackage from the
ShipmentRequest. In this case, the TrackingNumber is the Piece ID returned from the service. In
order to tie the RequestedPackages from the ShipmentRequest with the PackageResult in the
response, the @number attribute is used to referentially link the request and result packages.
The TrackingNumber field is the identifier for that specific piece of the shipment, of which there can
be many.

5.4.4

ShipmentResponse Output: LabelImage

The Label Image section of the response provides the label format in the LabelImageFormat field (i.e.
PDF), as well as the base64 encoded label image in the GraphicImage field. The HTML Image is not
used.

5.4.5

ShipmentResponse Output: ShipmentIdentificationNumber

This field corresponds to the airbill number associated to this shipment. This is the primary tracking
identifier within DHL, and is the DHL primary reference field in calling application.

5.4.6

ShipmentResponse Output: DispatchConfirmationNumber

This field is the confirmation number generated by the creation of a pickup, if requested. This data
will need to be persisted if the web service consumer intends to utilize the DeleteShipment
functionality, as it is a required field.

PAGE 49 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

5.5 SHIPMENT RESPONSE – OUTPUT FIELD LIST
Shipment Response xml
fields (Source)

Mandatory/
Optional

Values or
Constraints

@code

Message

Comments

ShipmentResponse
./Notification
Error > 0 or Success Code = 0
Response Message, see Error
codes for more details

./PackagesResult
./PackageResult
"@number"

TrackingNumber

Integer

Running number of the
packages.

AN 35

This field contains a unique
number for the individual
package.

AN 3

Mapped from Request
Document. Currently always
“PDF”

./LabelImage

LabelImageFormat

GraphicImage

Base64 Binary

This field contains the actual
label as Base64 Binary. There
will be one document
containing all the labels for
each package/piece on
separate pages.

HTMLImage

Base64 Binary

Not used

ShipmentIdentificationNumber

DispatchConfirmationNumber

AN 35

The shipment identification
number also named airwaybill
(AWB). This number can be
used to track the progress of
the shipment on the DHL
webside.

AN 15

The booking reference
number. This number should
be used when interacting with
the DHL customer service
regarding the pickup process.

PAGE 50 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

6. SHIPMENTDELETEREQUEST
6.1 SHIPMENTDELETEREQUEST - DESCRIPTION
The ShipmentDeleteRequest Operation will allow the user to synchronously cancel a previous successful
ShipmentRequest. The underlying process for the ShipmentDeleteRequest is a cancellation of a scheduled driver
pickup, if included in the original request. Any shipment manifest data which was included in the original
ShipmentRequest will not be deleted as part of this operation, but will not become an active shipment if the
shipment label does not enter the DHL Network. If a scheduled pickup was not included in the original
ShipmentRequest (i.e. DropOffType = REGULAR_PICKUP), then it is not necessary to delete the shipment.

6.2 SHIPMENTDELETEREQUEST - INPUT
The following diagram shows an overview of the request input structure.
Within the DeleteRequest, the ClientDetail is an optional node for reference use, and does not affect
functionality. The critical elements are the remaining nodes in the request.

The PickupDate is the day of the scheduled pickup, previously communicated as part of the
ShipmentTimestamp of the ShipmentRequest. For example, if the ShipmentTimestamp for the
successful shipment was “2010-11-30T12:30:47GMT+01:00”, then the PickupDate would be
“2010-11-30”.
The PickupCountry is the two character country code which was used in the original request.
The DispatchConfirmationNumber is the reference
ShipmentResponse for DispatchConfirmationNumber.

value

which

was

the

original

The RequestorName is a required field, but is not validated against the original ShipmentRequest.
This value is not validated against the original request, and can be defaulted if necessary.

PAGE 51 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
The Reason value is an optional field, and used to indicate the reason for the cancellation. The
possible values are included in the table below. Value of 7 (“Other”) used in the absence of
transmitted data.

Reason

Value

001

Package Not Ready

002

Rates Too High

003

Transit Time Too Slow

004

Take To Service Center or Drop
Box

005

Commitment Time Not Met

006

Reason Not Given

007

Other

008

Pickup Modified

PAGE 52 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

6.3 SHIPMENTDELETEREQUEST – INPUT FIELD LIST
Mandatory
ShipmentDeleteRequest fields

/Optional

Value
constraints Comments

DeleteRequest
PickupDate

PickupCountry

YYYY-MM- The scheduled pickup date of
DD
the shipment to be deleted.
AN 2

The country code associated to
the origin of the shipment.

DispatchConfirmationNumber

AN 20

The confirmation number
returned from the original
shipment request.

RequestorName

AN 45

The delete requestor name

Reason

AN 50

Optional reason code (see
above table)

./ClientDetail
sso

This field is for internal use only

plant

This field is for internal use only

6.4 SHIPMENTDELETEREQUEST – OUTPUT

PAGE 53 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

6.5 SHIPMENTDELETEREQUEST – OUTPUT FIELD LIST
ShipmentDeleteRespons
e fields

Mandatory
/Optional

Value
constraint
s
Comments

DeleteResponse
./Notification
@code
message

Error > 0 or Success Code = 0

Response Message, see Error codes
for more details

For this service, the potential error use cases include

•

Pickup Not Found, if already deleted

•

Pickup Not Found, if manually deleted otherwise

•

Pickup Not Found, if still in process of creation

Please note, for the 3rd use case, there is a very small window of time between when the original
pickup request is processed and when the backend system creates the pickup (< 30 secs). During
this time, it may not be possible to delete the pickup request.

PAGE 54 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

7. TRACKINGREQUEST
7.1 TRACKINGREQUEST - DESCRIPTION
The TrackingRequest operation is used to inform customers about the status of their in-transit
shipments, based on the valid DHL Waybill Number. The resulting response will provide tracking
events at both the Shipment and/or Piece events corresponding to the DHL Waybill(s) submitted.
When presenting the results of the web service, note that the resulting piece and shipment events
should not be grouped separately. Depending on the type of event or DHL processing facility, only
piece or shipment data (or both piece and shipment) may be available. Merging the resulting Piece
and Shipment events will provide a consolidated view of the event history for the DHL Shipment.

7.1.1

TrackingRequest Schema Diagram

The following diagram details the schema diagram for the TrackingRequest, as input. While the
critical input for the TrackingRequest is the DHL Airbill Numbers (ArrayOfAWBNumberItem), there
are two options available to tailor the output.

The remaining subsections of 4.2.2 will provide additional context to the structures immediately
below TrackingRequest, while the individual nodes are described in further detail in section 4.2.3.

PAGE 55 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

7.2 TRACKINGREQUEST - INPUT
The Request node contains a ServiceHeader structure, which describes the MessageTime and
MessageReference of the request. The Header fields are required fields for the request, used to
distinguish individual requests. The MessageReference is required to be between 28 and 32
characters in length, but is not required to be unique between requests.

7.2.1

TrackingRequest Input: AWBNumber

The AWBNumber element must contain at least one element within the ArrayOfAWBNumberItem
node. The DHL Waybill element is defined at a maximum length of 11 characters; the standard DHL
Waybill used in shipping will typically be 10 digits. The AWBNumber element allows multiple DHL
Waybill numbers in a single request, as multiple Waybill requests are batched on the backend to
populate the response for multiple shipments.

7.2.2

TrackingRequest Input: LPNumber

The LPNumber element is currently not active, but is present within the service signature for future
use of tracking by piece number.

7.2.3

TrackingRequest Input: LevelOfDetails

The LevelOfDetails element contains an enumerated value for checkpoint details requested in the
response. It is a required element in the request, applies to all shipments in the request and has the
following values.
•
•

7.2.4

LAST_CHECK_POINT_ONLY
ALL_CHECK_POINTS

TrackingRequest Input: PiecesEnabled

The PiecesEnabled element contains an enumerated value for shipment and/or piece details and
events requested in the response. It is an optional element in the request, applies to all shipments in
the request and has the following values.
•
•
•

7.2.5

B = Both Piece and Shipment Details (recommended value)
S = Shipment Details Only
P = Piece Details Only.

TrackingRequest Input: EstimatedDeliveryDateEnabled

The EstimatedDeliveryDateEnabled element indicates if estimated delivery date (EDD) should be
included in the service response (Estimated Delivery Date information is not always available).

PAGE 56 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

7.3 TRACKINGREQUEST – INPUT FIELD LIST
The following table details the fields used by the TrackingRequest, their cardinality and a brief
description of their usage.
Tracking Request fields

M/O

Values or
Constraints

Comments

TrackingRequest
./Request
/ServiceHeader
The format of the should be YYYYMM-DD(T)hh:mm:ss-Time Zone
e.g.
2010-11-24T00:17:20Z
MessageTime

Date

2010-11-24T00:17:20-07:00

MessageReference

AN 32

Message reference, between 28-32
characters in length.

AN 11

DHL Waybill number

AN 35

DHL Piece ID (future use, not active)

./AWBNumber
ArrayOfAWBNumberItem
./LPNumber
ArrayOfTrackingPieceIDItem

Checkpoint Detail Indicator
ALL_CHECK_POINTS
LevelOfDetails

Enumerated

LAST_CHECK_POINT_ONLY
Pieces Indicator
B = Both Piece and Shipment
S = Shipment Details Only

PiecesEnabled

Enumerated

P = Piece Details Only.
Possible values:
- 1, EDD requested
- 0, EDD not requested

EstimatedDeliveryDateEnabled

Enumerated

(Estimated Delivery Date is not
always returned and is subject to
the scans by the DHL Operations
team)

PAGE 57 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

Waybill numbers to be used during Testing for Tracking
Please note that when testing the Tracking Web service, only the Waybill numbers below are loaded
and any production Waybill numbers or ones created via CreateShipment will not be trackable.
3898464710

9296347550

9296392420

3567549160

8423914660

7195064870

7895183380

1191166550

7780184230

5220325810

7895111000

7898385320

5138809620

6424045110

6768764450

3314358460

9545331390

7895083910

8260591010

4688745390

7967566180

PAGE 58 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

7.4 TRACKINGRESPONSE - OUTPUT
The following diagram details the TrackingResponse. All successful tracking responses will conform
to this schema.

At a high level, the TrackingResponse contains a Response element and an AWBInfo element.
Within the AWBInfo element, each ArrayOfAWBInfoItem corresponds to the response for each DHL
Airbill submitted in the original request.
The remaining subsections of 4.2.4 will provide additional context to the structures immediately
below TrackingResponse, while the individual nodes are described in further detail in section 4.2.5.

7.4.1

TrackingResponse Output: Response

The Response element contains the service header information for the message. This includes the
timestamp when the response generated to the consumer, as well as the unique message reference
generated by DHL.

PAGE 59 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

7.4.2

TrackingResponse Output: AWBInfo

The AWBInfo element is a complex element which maintains an array of airbill responses for each
airbill requested. The ArrayOfAWBInfoItem consists of four child elements
•
•
•
•
7.4.3

AWBNumber
Status
ShipmentInfo
Pieces
TrackingResponse Output: AWBNumber

The AWBNumber returned in the response corresponds to the DHL Airbill Number in the Tracking
Request. For multiple shipment requests, this field is used to distinguish between the multiple
responses.

7.4.4

TrackingResponse Output: Status

The Status element consists of a summary ActionStatus field, which describes the success of the
service. Expected values for this element are “Success” and “No Shipments Found”.
The optional Condition element consists of additional error information, and is only present in the
case of an exception. Appendix A contains specific information on the values of the ConditionCode
and ConditionData returned in the case of a Not Found exception.

PAGE 60 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
7.4.5

TrackingResponse Output: ShipmentInfo

The ShipmentInfo element is an optional element within the response, and will be populated for
successful invocations. This element describes the shipment details, as well as provide optional
ShipmentEvents. The ShipmentInfo element consists of the following child elements:
•
•
•
•
•
•
•
•
•

OriginServiceArea – This complex element contains the Service Area code and Service Area
description for the origin of the shipment.
DestinationServiceArea – This complex element contains the Service Area Code and Service
Area Description for the destination of the shipment.
ShipperName – The name or title associated to the shipper.
ShipperAccountNumber – The account number for shipping, currently not included for
tracking purposes.
ConsigneeName – The name or title associated to the receiver.
ShipmentDate – The date of the shipment initiation.
Pieces – The number of pieces in the shipment.
Weight – The weight of the shipment.
WeightUnit – The unit of measure for shipment weight.

PAGE 61 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

The ShipmentEvent element is an optional complex element detailing the specific shipment events
for the entire shipment, and has a cardinality of zero to many. Each event will be detailed under the
element ArrayOfShipmentEventItem, and the events will appear in descending order by date/time.
The ArrayOfShipmentEventItem element consists of these child elements.

•
•
•
•
•

Date – The date of the Shipment Event
Time – The time of the Shipment Event (in local time)
Service Event – The code and description of the event.
Signatory – The signee for the shipment, if captured.
Service Area – The service area code and description where the event occurred.

The ShipmentReference element is an optional complex element detailing the reference information,
if any, available for this shipment

.
•

EstimatedDeliveryData – estimated delivery date (EDD)

PAGE 62 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
7.4.6

TrackingResponse Output: Pieces

The following diagram details the Pieces element of ArrayOfAWBInfoItem. The Pieces element is an
optional element which contains a single complex PieceInfo element. The PieceInfo element consists
of one to many ArrayOfPieceInfoItem elements.

Within the ArrayOfPieceInfoItem element, there are two complex child elements.
•
•

PieceDetails – This element describes attributes of the specific piece, including piece id,
dimensions and weight.
PieceEvent – This element contains one to many events at the piece level, including a
description of the event, the date/time of the event, and the location of the event. In this
sense, it is identical in structure to the ShipmentEvent element.

PAGE 63 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

7.5 TRACKINGRESPONSE – OUTPUT FIELD LIST

Mandatory
TrackingResponse

/Optional

Value
constraints Comments

./Response
./ServiceHeader
The format of the should be YYYYMM-DD(T)hh:mm:ssZ (GMT
MessageTime

Date

e.g 2011-01-12T18:41:12Z

MessageReference

AN 32

The unique message reference for
this response.

AN 11

Identifies the piece number as a
counter, same as input.

./AWBInfo
./ArrayOfAWBInfoItem
AWBNumber
./Status
The summary status of the request.
Values include;
“Success”
ActionStatus

AN 20

“No Shipments Found”

./Condition/ArrayOfConditionItem
Error Code associated to the request
ConditionCode

e.g. 101

ConditionData

AN 50

Error Description

ServiceAreaCode

AN 3

The DHL Service Area Code for the
origin of the Shipment

Description

AN 40

The description of the Service Area
Code.

/ShipmentInfo
/OriginServiceArea

PAGE 64 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

Outbound Sort Code of Origin
OutboundSortCode

AN 4

(currently not available)

ServiceAreaCode

AN 3

The DHL Service Area Code for the
destination of the Shipment

Description

AN 40

Description

FacilityCode

AN 3

The DHL Facility Code for the
Destination

InboundSortCode

AN 4

Inbound Sort Code of Destination
(currently not available)

ShipperName

AN 35

Shipper Name

/DestinationServiceArea

Shipper’s Account Number
ShipperAccountNumber

N 10

(currently not populated for
tracking)

ConsigneeName

N 35

Receiver’s Name
The shipment initiation date, local to
origin
YYYY-MM-DD(T)HH:MM:SS+GMT

ShipmentDate

Date

2010-11-09T14:30:00+01:00

Pieces

Number of pieces in shipment
Weight of shipment

Weight

AN 9

Format 99999.999
L = Pounds
K = Kilogram

WeightUnit

AN 1

G = Grams

/ShipmentEvent/ArrayOfShipmentEventItem (1:m)
Local Date of Shipment Event
Date

Date

YYYY-MM-DD
Local Time of Shipment Event

Time

HH:MM:SS

ServiceEvent

PAGE 65 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

EventCode

AN 2

The event code for this specific
event.

Description

AN 50

The description of the event

AN 20

The signee for the shipment, only
occurs for final disposition events
(such as OK event)

ServiceAreaCode

AN 3

The DHL Service Area Code for the
event

Description

AN 40

The description of the service area
code.

Signatory

ServiceArea

/ShipperReference (currently not used)
ReferenceID

AN 35

Reference ID for shipment

ReferenceType

AN 2

Reference Type
Estimted delivery date (EDD)
YYYY-MM-DD(T)HH:MM:SS+GMT

EstimatedDeliveryDate

Date

2010-11-09T14:30:00+01:00

/Pieces/PieceInfo/ArrayOfPieceInfo
PieceDetails
Airbill associated to the Piece (same
as
AWBNumber

AN 11

the parent node airbill)

LicensePlate

AN 35

Piece ID associated to the Piece

PieceNumber

Number of the Piece
Actual Depth of shipment

ActualDepth

AN 9

Format 99999.999
Actual Width of shipment

ActualWidth

AN 9

Format 99999.999
Actual Height of shipment

ActualHeight

AN 9

Format 99999.999

ActualWeight

AN 9

Actual Weight of shipment

PAGE 66 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

Format 99999.999
Depth of shipment
Depth

AN 9

Format 99999.999
Width of shipment

Width

AN 9

Format 99999.999
Height of shipment

Height

AN 9

Format 99999.999
Weight of shipment

Weight

AN 9

Format 99999.999

PackageType

AN 3

Package Type of Shipment
Volumetric Weight of shipment

DimWeight

AN 9

Format 99999.999
L = Pounds
K = Kilogram

WeightUnit

AN 1

G = Grams

PieceContents

AN 20

Contents or description of the piece

/PieceEvent/ArrayOfPieceEventItem (1:m)
Local Date of Piece Event
Date

Date

YYYY-MM-DD
Local Time of Shipment Event

Time

HH:MM:SS

EventCode

AN 2

The event code for this specific
event.

Description

AN 50

The description of the event

AN 20

The signee for the piece, only occurs
for final disposition events (such as
OK event)

AN 3

The DHL Service Area Code for the
event

ServiceEvent

Signatory

ServiceArea
ServiceAreaCode

PAGE 67 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

Description

AN 40

The description of the service area
code.

/ShipperReference (currently not used)
ReferenceID

AN 35

Reference ID for shipment

ReferenceType

AN 2

Reference Type

PAGE 68 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

8. DOCUMENTRETRIEVE - EPOD
8.1 DOCUMENTRETRIEVE-EPOD - DESCRIPTION
The Document Retrieve operation will return ePOD image(s) according to how the image was
requested.
Using Waybill number as well as other shipment criteria, this operation returns the available ePOD
image including, if requested, the ePOD details.
A Document Retrieve request is successfully executed if the correct combination of account/Waybill
and image content is sent in the request.

8.2 DOCUMENTRETRIEVE-EPOD - INPUT
The following diagrams show an overview of the request input structure. It is composed of two
main structures. The header (Hdr) and the Body(Bd). The Bd contains two structures, the Shipment
(Shp) elements and the Generic Request (GenrcRq). Most of the parameters defining the image
requested are on the Shp and GenrcRq segments.
Msg

Hdr

Bd
Shp

GenrcRq

The representation of each of the individual sections of shipmentDocumentRetrieve request is below
in schema diagram, with context, and a detailed description of each field follows in the Input Field
List.

PAGE 69 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
8.2.1

Header (Hdr) Schema Diagram

8.2.2

Header Input: Id

Unique identification of the request. e.g. 1234567890

8.2.3

Header Input: Ver

Mandatory: Version of the DHL canonical format. This is a constant value that should be set to
1.038.

8.2.4

Header Input: Dtm

Mandatory: Message creation date-time in the following format: 2013-04-07T23:59:59

PAGE 70 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
8.2.5

Header Input: CorrId

Correlation id can be used to link a message. It is optional and it is only used in the response.

8.2.6

Header Input: Sndr

The Sndr section provides details about the message sender.

8.2.7

Sndr Input: AppCd

Mandatory: The AppCd identifies the application sending the request to the backend system. In this
case, the value should be DCG.

8.2.8

Sndr Input: AppNm

Optional: The AppNm node contains the name of the sending application.

PAGE 71 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
8.2.9

Sndr Input: CmptNm

Optional: The CmptNm is the name of the component in the application that is sending the request.

8.2.10

Sndr Input: GId

Optional: General identification of the message. In this process this group is not used.

8.2.11

Header Input: Rcp.

Optional: Recipient identification. This section is only used in the response no need to use it in the
request.

PAGE 72 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

PAGE 73 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
8.2.12

Bd Input: Shp Schema Diagram

8.2.13

Shp Input: Id

Mandatory: Shipment identifier: an identification number assigned to a shipment, controlled by DHL.

PAGE 74 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
8.2.14

Shp Input: ShpTr

The ShpTr section contains the fields related to the shipment transaction

8.2.15

ShpTr Input: PuDtm

Optional: Shipment pick-up datetime (Optional (part of Shipment Key)) The date and time when the
goods are collected from shipper. If not provided, the shipment with the most recent pickup date
matching the other search criteria is considered.

8.2.16

ShpTr Input: SCDtl

The SCDtl section contains shipment customer detail

PAGE 75 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
8.2.17

SCDtl Input: AcctNo

Account Number. This is optional if requesting a summary ePOD, however it is mandatory for each
Waybill number to declare the corresponding account number.

8.2.18

SCDtl Input: CRlTyCd

Optional: If the AccNo is provided this field also should be provided. Customer role type code: It is
optional for summary ePOD but mandatory for detail ePOD. This is the code that uniquely identifies
a customer role. Values are: PY=Payer RV=Receiver SP=Shipper

8.2.19

SCDtl Input: CtryCd

/Country code: this is optional for ePOD retrieval. The country code is a two-character code that
uniquely identifies a country. The code should be aligned to the ISO (ISO 3166-1-alpha-2 code
elements) standards or in certain circumstances created by DHL. Values are e.g. BE=Belgium
FR=France XC=Curacao (Not ISO - part of Netherlands Antilles).

8.2.20

Shp Input: ShpInDoc

The ShpInDoc includes the SDoc(Shipment Documentation) section

PAGE 76 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
8.2.21

ShpInDoc Input: SDoc

SDoc contains shipment in document

8.2.22

SDoc Input: DocTyCd

Mandatory: Document type code: identifies uniquely a document type. In this case POD (electronic
proof of delivery)

8.2.23

SDoc Input: Img

The Img (Image) section contains only the Img (image) field. Image of the document. Please note
that this tag is only used in this service as the place where the ePOD image is returned. Not need to
send it in the request.

PAGE 77 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
8.2.24

Bd Input: GenrcRq

The Generic Request GenrcRq) contains the type and value criteria of the request.

PAGE 78 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
8.2.25

GenrcRq Input: TyCd

Generic request criteria type code : There might be up to 7 instances of this element with a
matching value in the Val attribute. These are the values for each instance:
1. "IMG_CONTENT" - Mandatory. Specifies the output type for PDF rendering.
2. "IMG_FORMAT" - Mandatory. Document Format.
3. "DOC_RND_REQ" - Optional. Presentation format. If not provided the default is all documents in
one file.
4."EXT_REQ" - Optional. Specifies whether the request is done for DHL internal purpose or whether
the data is requested by a customer.
5. "DUPL_HANDL" - Optional . From a set of matching documents which have identical values in the
specified metadata fields, only one will be returned.
6. "SORT_BY" – Optional. Sort order within a group of matching documents for which only one
will be returned. The top most entry in the sort order will be returned.
7. "LANGUAGE" – Optional. Language code.

8.2.26

GenrcRq Input: Val

Generic request criteria value. One value for each TyCd.
1. IMG_CONTENT. The following values are supported: a. epod-detail-esig / epod-detail: Detailed
ePOD in letter format. b. epod-summary-esig / epod-summary: Summary ePOD in letter format. c.
epod-table-detail / epod-table-esig / epod-table: Detailed ePOD in table format. d. epod-tablesummary: Summary ePOD in table format. PLEASE NOTE THAT ACCOUNT NUMBER MUST BE
PROVIDED TO REQUEST FOR DETAIL EPOD (a)(c). Remarks: “/” represents aliases. The output will be
the same for all aliases which are under the same category. For example, epod-detail-esig / epoddetail will both give detailed ePOD in letter format with no difference. All the output types above
will return ePOD with eSIG (if the eSIG is available), else ePOD without eSIG will be returned.
2. IMG_FORMAT. The only possible value is PDF.
3. DOC_RND_REQ. The possible values are: true if one output file for all shipments which is the
default or false one file for each shipment.
4. EXT_REQ. The possible values are: true (default) if the purpose is customer use or false if it is for
internal purpose.
5. DUPL_HANDL. The only available and default value is CORE_WB_NO.
6. SORT_BY. The only available value "$INGEST_DATE,D".
7. Language codes are defined according to ISO 639-1 standard. Thus the 2-character code must
be in lower-case letters. e.g. en, de. If not provided en is the default.

PAGE 79 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

8.3 SHIPMENTDOCUMENTRETRIEVE-EPOD – INPUT FILED LIST

Shipment Document
Retrieve fields

Mandatory
/Optional

Value
constraints

Comments

shipmentDocumentRetrieveReq
./MSG
./Hdr
@Id

AN 30

Request Id

@Ver

AN 7

Use always this value: 1.038

@Dtm

DateTime

Format: 2013-04-07T23:59:59

AN 20

Correlation ID. This field is only used in
the response. No need to send in the
request.

@AppCd

AN 5

Value: DCGAP

@AppNm

AN 20

Value: DCGAP

@CmptNm

AN 256

Your own unique system name

@CorrId
./Sndr

./Rcp This section is not used in the request, only in the response.
./Bd
./Ship(1:M)
@Id

AN 35

Shipment Id (AWB)

./ShpTr(0:M)

@PuDtm

DateTime

Pickup Date-Time: We recommend not
to enter the pick up date. However,
the format of the pickup date is 201201-31T00:00:00.

AN 12

Account No: optional for summary
ePOD, mandatory for detail ePOD.
This includes 3 distinct request
parameters: Filter by account number
of a specific type (CRlTyCd) (1. payer PY 2. receiver - RV 3. shipper - SP).

./SCDtl():M)

@AccNo

PAGE 80 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

Customer role type code: This code
identifies weather the above account
number was used in the Payer,
Receiver or Shipper Account field
while creating the shipment.

@CRlTyCd

@CtryCd

AN 2

The possible codes are PY=Payer, RV
=Receiver, SP=Shipper – You only
need to specify this field if you are
requesting a detailed ePOD

AN 2

Country code: this is optional for ePOD
retrieval. This is the origin country
code..The country code is a twocharacter code that uniquely identifies
a country. The code should be aligned
to the ISO (ISO 3166-1-alpha-2 code
elements) standards or in certain
circumstances created by DHL. Values
are e.g. BE=Belgium FR=France
XC=Curacao (Not ISO - part of
Netherlands Antilles)

AN3

Document type code: identifies
uniquely a document type. Value =
POD (electronic proof of delivery)

AN12

Generic request criteria type code :
There might be up to 7 instances of
this element with a matching value in
the Val attribute. These are the values
for each instance: 1. "IMG_CONTENT"
- Mandatory. Specifies the output type
for PDF rendering. 2. "IMG_FORMAT"
- Mandatory. Document Format. 3.
"DOC_RND_REQ" - Optional.
Presentation format. If not provided
the default is all documents in one file.
4."EXT_REQ" - Optional. Specifies
whether the request is done for DHL
internal purpose or whether the data is
requested by a customer. 5.
"DUPL_HANDL" - Optional . From a
set of matching documents which have
identical values in the specified
metadata fields, only one will be
returned. 6. "SORT_BY" – Optional.
Sort order within a group of matching
documents for which only one will be
returned. The top most entry in the
sort order will be returned. 7.

./ShpInDoc(1:M)
./SDoc(1:M)

@DocTyCd

./GenrcRq(0:M)

@ TyCd

PAGE 81 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
"LANGUAGE" – Optional. Language
code.

@Val

AN75

Generic request criteria value. One
value for each TyCd. 1.
IMG_CONTENT. The following values
are supported: a. epod-detail-esig /
epod-detail: Detailed ePOD in letter
format. b. epod-summary-esig / epodsummary: Summary ePOD in letter
format. c. epod-table-detail / epodtable-esig / epod-table: Detailed ePOD
in table format. d. epod-tablesummary: Summary ePOD in table
format. PLEASE NOTE THAT
ACCOUNT NUMBER MUST BE
PROVIDED TO REQUEST FOR
DETAIL EPOD (a)(c). Remarks: “/”
represents aliases. The output will be
the same for all aliases which are
under the same category. For
example, epod-detail-esig / epod-detail
will both give detailed ePOD in letter
format with no difference. All the
output types above will return ePOD
with eSIG (if the eSIG is available),
else ePOD without eSIG will be
returned. 2. IMG_FORMAT. The
possible value is PDF. 3.
DOC_RND_REQ. The possible values
are: true if one output file for all
shipments which is the default or false
one file for each shipment. 4.
EXT_REQ. The possible values are:
true (default) if the purpose is
customer use or false if it is for internal
purpose. 5. DUPL_HANDL. The only
available and default value is
CORE_WB_NO. 6. SORT_BY. The
only available value
"$INGEST_DATE,D". 7. Language
codes are defined according to ISO
639-1 standard. Thus the 2-character
code must be in lower-case letters.
e.g. en, de. If not provided en is the
default.

PAGE 82 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

8.4 SHIPMENTDOCUMENTRETRIEVE-EPOD – OUTPUT
The representation of each of the individual sections of shipmentDocumentRetrieve response is
below in schema diagram, with context, and a detailed description of each field follows in the
Output Field List.

8.4.1

Header (Hdr) Schema Diagram

8.4.2

Header Output: Id

Unique identification of the response. e.g. 1234567890

PAGE 83 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

8.4.3

Header Output: Ver

Version of the DHL canonical format. This is a value backend returns based on the canonical format
version used. For example 1.038.

8.4.4

Header Output: Dtm

Response’s date-time in the following format: 2013-04-07T23:59:59

8.4.5

Header Output: Sndr

The Sndr section provides details about the response sender.

8.4.6

Header Output: AppCd

The AppCd identifies the application sending the response. In this case, the value is ESB.

8.4.7

Header Output: AppNm

The AppNm node contains the name of the responding application. The value is ESB.

PAGE 84 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

8.4.8

Bd Output: Shp Schema Diagram

8.4.9

Shp Output: Id

Shipment identifier: This is not returned in the response.

PAGE 85 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
8.4.10

Shp Output: ShpTr

Nothing from ShpTr section is returned.

8.4.11

ShpTr Output: PuDtm

This is not returned.

8.4.12

ShpTr Outtput: SCDtl

The SCDtl section contains shipment customer detail. This is not returned.

8.4.13

SCDtl Output: AcctNo

This is not returned.

PAGE 86 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
8.4.14

SCDtl Output: CRlTyCd

This is not returned.

8.4.15

SCDtl Output: CtryCd

This is not returned.

8.4.16

Shp Output: ShpInDoc

The ShpInDoc includes the SDoc(Shipment Documentation) section

8.4.17

ShpInDoc Output: SDoc

SDoc contains shipment in document

PAGE 87 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
8.4.18

SDoc Output: DocTyCd

Document type code: Value returned is POD.

8.4.19

SDoc Output: Img

The Img (Image) section contains only the Img (image) field. Image of the document returned in a
base64 encoded string. It also returns the ImgMimeTy with value = application/pdf

8.4.20

SDoc Output: ImgMimeTy

Image mime type : Specifies MIME type of Image. In this case the value is application/pdf.

8.4.21

DatTrErr Output

The DatTrErr is where any messages generated during the process of the request are returned.

PAGE 88 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
8.4.22

OrgHdr Output: Service

Even though this section has four attributes (Id, Ver, Dtm, and CorrId) and blocks Sndr and Rcp
defined, the first three attributes return with null values. Only CorrId is returned.

8.4.23

OrgHdr Output: CorrId

Correlation Message identification (Referenced to ID). In this case a unique number is returned(e.g.:
72563197).

8.4.24

OrgHdr Output: Sndr

Sndr only returns fields AppNm and CmptNm with values “ESB” and “ESB”

PAGE 89 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

8.4.25

OrgHdr Output: Rcp

Rcp returns only AppNm and CmptNm with values “DCG” and “DCG”.

8.4.26

Rp Output

This section returns information about the backend service operation that processed the request.
The below three attributes are returned.

PAGE 90 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

8.4.27

Rp Output: AppCd

Backend returns a null value in this field.

8.4.28

Rp Output: AppNm

Backend does not return this field.

8.4.29

Rp Output: CmptNm

Backend returns the name of the operation that processed the ePOD request. It will always be the
value “DocumentManagement.ShipmentDocumentRetrieveProvider”.

PAGE 91 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
8.4.30

Rp Output:GId

General identification of the message. This is optional and might return two attributes: Id which is
the message identification value and IdTp, which is the identification type.

8.4.31

DatTrErr Output: ErrMsgGI

The error message general info (ErrMsgGI) returns attributes that provide information about
messages generated by backend. For this service only returns three attributes: Ty, Pri, and Sev. Only
those three attributes will be described below.

8.4.32

ErrMsgGI Output: Ty

Error message type identifier. The value will always be “CF”.

8.4.33

ErrMsgGI Output: Pri

Priority defines the importance of the event. The backend operation will return a value of 2 for
ePOD retrieval.

PAGE 92 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

8.4.34

ErrMsgGI Output: Sev

Severity: the perceived severity of the status the event is describing with respect to the application
that reports the event.

8.4.35

DatTrErr Output: TfErrMsg

Transfer Error Message (TfErrMsg) returns any errors related to the transfer of the message.

8.4.36

TfErrMsgOutput: ErrMsgDtl

This structure display the details of the error related to the transfer of the message. Usually Backend
returns only MsgClgd and Dsc.

8.4.37

ErrMsgDtl Output:MsgClgd

The identifier for the error message. For example 100002.

8.4.38

ErrMsgDtl Output:MsgClg

The message name regarding the identifier MsgClgd

PAGE 93 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

8.4.39

ErrMsgDtl Output:Dsc

The error message description

8.4.40

ErrMsgDtl Output: DtlDsc

Additional details about the error message.

8.4.41

DatTrErr Output: DatErrMsg

Data Error Message (DatErrMsg). Information about errors related to data.

8.4.42

DatErrMsg Output:ErrMsgDtl

This structure display the details of the error related to the message data. Usually backend returns
only MsgClgd and Dsc.

PAGE 94 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

8.4.43

ErrMsgDtl Output:MsgClgd

The identifier for the error message. For example 100002.

8.4.44

ErrMsgDtl Output:MsgClg

The message name regarding the identifier MsgClgd

8.4.45

ErrMsgDtl Output:Dsc

The error message description

8.4.46

ErrMsgDtl Output: DtlDsc

Additional details about the error message.

PAGE 95 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
8.4.47

DatErrMsg Output:BOErr

Backend returns error messages when mandatory fields are missing. The error message will be in the
section FldErr.

8.4.48

BOErr Output: FldErr

Errors related to mandatory missing fields:

PAGE 96 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

8.4.49

FldErr Output: FldId

This structure returns FldXPth with the Xpath of the field that is missing, for example:

8.4.50

FldErr Output: ErrMsgDtl

ErrMsgDtl returns the field Dsc with the description of the missing field, for example:

PAGE 97 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

8.5 DOCUMENTRETRIEVE-EPOD – OUTPUT FIELD LIST

Shipment Document
Retrieve fields

Mandat
ory
/Option
al

Value
constraints

Comments

shipmentDocumentRetrieveResp
./MSG
./Hdr
@Id

AN 30

Response Id

@Ver

AN 7

Version of the response schema used:
e.g.: 1.038

@Dtm

DateTime

@AppCd

AN 5

Value: ESB

@AppNm

AN 20

Possible values ESB

@CmptNm

AN 256

This field is not returned.

Date-time when the response was
created. Format: 2013-04-07T23:59:59

./Sndr

./Bd
./Ship(1:M)

@Id

AN 35

Shipment Id (AWB). Even though it is
defined as mandatory in the schema,
the field is returned with an empty
value.

./ShpTr(0:M) Nothing from this section is returned
@PuDtm

DateTime

Pickup Date-Time (Not returned)

./SCDtl():M)

@AccNo

@CRlTyCd

AN 12

AN 2

Customer role type code: a code that
uniquely identifies a customer role.
Values are: PY=Payer RV=Receiver
SP=Shipper. (NOT RETURNED)

PAGE 98 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

@CtryCd

AN 2

/Country code: this is optional for
ePOD retrieval. The country code is a
two-character code that uniquely
identifies a country. The code should
be aligned to the ISO (ISO 3166-1alpha-2 code elements) standards or
in certain circumstances created by
DHL. Values are e.g. BE=Belgium
FR=France XC=Curacao (Not ISO part of Netherlands Antilles) (NOT
RETURNED)

./ShpInDoc(1:M)
./SDoc(1:M)
@DocTyCd

AN 3

Document type code: Value returned:
POD (electronic proof of delivery)

./Img (0:M)
@Img

Base64Binary

Base64 encoded image

./DatTrErr(0:M)
./OrgHdr(0:1)

@Id

AN 20

Unique identifier of the response. In this
case the field is returned with an empty
value
Version schema format. Service returns
null value in this field.

@Ver

AN 7

@Dtm

DateTime

Response creation date-time. Service
returns null value in this field.

./Sndr(0:1) The service does not return anything from this section
@AppCd

AN 5

This field is not returned.

@AppNm

AN 20

This field is not returned.

@CmptNm

AN 256

This field is not returned.

@AppCd

AN 5

The service returns a null value in this
field.

@AppNm

AN 20

The service does not return this field.

AN 256

The service returns value
“DocumentManagement.ShipmentDocu
mentRetrieveProvider”

./Rp(0:1)

@CmptNm
./ErrMsgGI(0:1)

Only 3 fields from this section sometimes are returned

PAGE 99 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

@Ty

AN 20

Error message type identifier: e.g.:CF

@Pri

NUMBER

Priority:e.g.:2

@Sev

NUMBER

Severity: e.g.: 10

AN 128

Error message identifier. For example:
100000

./TfErrMsg(0:M)
./ ErrMsgDtl(0:1)
@ MsgCIgd

@ MsgClg

AN 128

The message name regarding the
identifier MsgClgd. For example: IPESB

@Dsc

AN 128

The error message description.

AN 128

Additional details about the error
message.

@ MsgCIgd

AN 128

Error message identifier. For example:
100000

@ MsgClg

AN 128

The message name regarding the
identifier MsgClgd. For example: IPESB

@Dsc

AN 128

The error message description.

@ DtlDsc

AN 128

Additional details about the error
message.

AN 512

This structure returns FldXPth with the
Xpath of the field that is missing, for
example:

AN 128

ErrMsgDtl returns the field Dsc with the
description of the missing field, for
example:

@ DtlDsc
./ DatErrMsg (0:M)
./ ErrMsgDtl(0:1)

./ BOErr (0:1)
./FldErr(0:M)
./FldId(0:1)

@ FldXPth

./ ErrMsgDtl(0:1)

@ Dsc

PAGE 100 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

9. UPDATESHIPMENT
9.1 UPDATESHIPMENT - DESCRIPTION
The updateShipment request allows for additional pieces to be added to a previously created
shipment that has not been picked up by DHL Express/had a scan against it. As an example a
shipment was created for customer A in the morning however 2 hours later customer A has ordered
something else and instead of creating two independent shipments to Customer A, you can use the
updateShipment service to search for your previous shipment and add the additional pieces to it.
As an output you will receive either the additional transport labels only or you can request all the
labels to be printed – this allows flexibility based on your operational processes when labelling the
parcels.
IMPORTANT: Please note that at least 10mins must be given between the initial createShipment
request and then the updateShipment request (including subsequent updateShipment request). This
is to ensure that the shipment data has propagated into the DHL Operations backend and that the
DHL Express Global WebServices retrieves the current number of pieces back to provide an
operationally correct Transport Label.

9.2 UPDATESHIPMENT - INPUT
The following diagram shows an overview of the request input structure.
9.2.1

updateShipment Schema Diagram

Each of the individual sections of updateShipment is shown below in schema diagram, with context,
and a detailed description of each field follows in the Input Field List.

PAGE 101 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

9.2.2

updateShipment Input: ShipmentInfo

The ShipmentInfo section are in essence the search parameters of the previously created shipment in
DHL’s database to be able to add the additional packages that will be declared in the segment
below. The search criteria is by providing the Account number used (this is either from the Account
tag or the Billing section Account in the original ShipmentRequest service), the ServiceType
(product), Shipment Date (based on ShipTimestamp, format YYYY-mm-dd) and the
ShipmentIdentificationNumber (Waybill).
In addition you can optionally define the label/archive template and label type in the request. To give
full operational flexibility you can decide whether you wish to print all labels including the previous
generated ones or only the new additional labels for the additional pieces that are being added.

PAGE 102 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

9.2.3

updateShipment Input: Packages

PAGE 103 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

9.3 UPDATE SHIPMENT REQUEST – INPUT FIELD LIST

Shipment Request fields

M/O

Values or
Constraints

Comments

updateShipmentRequest
./ClientDetail
sso

This field is for internal use only

plant

This field is for internal use only

./UpdatedShipment
Has to match with
ShipmentTimestamp from
createShipment (only the date
part)
OriginalShipDate

YYYY-mm-dd

Example (2017-11-15)

./ShipmentInfo

ServiceType

AN 1

The shipping product requested
for this shipment, corresponding
to the DHL Global Product codes.
The customer account to be used
as payer in the request. If the
tag is used then there
is no need to populate the Billing
section further down below in this
table as the tag will
override any other accounts
entered.

Account

ShipmentIdentificationNumber

M/O

AN 9

However if you do wish to charge
your shipment to a third party or
receiver then please leave the
ACCOUNT section out and
populate the Billing section below

Please provide the Shipment
Identification Number (Waybill) of
the shipment you wish to update.
Possible values:
- PDF

LabelType

AN 3

- ZPL

PAGE 104 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

- EPL
- LP2

LabelTemplate

ArchiveLabelTemplate

AN 20

Any valid DHL Express label
template (please contact your DHL
Express IT representative for a list
of labels) – If this node is left blank
then the default DHL ecommerce
label template will be used.

AN 20

Any valid DHL Express archive
label template (please contact
your DHL Express IT representative
for a list of labels) – If this node is
left blank then the default DHL
ecommerce label template will be
used.
Y or 1= All previously
pieces/packages will be included
when the label image is returned

IncludePreviousPieceLabels

AN1

N or 0 = The previous
pieces/packages will not be
included when the label image is
returned – only the new pieces
will be provided

./Billing
The DHL account number used for
the shipment. Used as the shipper
account number. Please note if
you use this billing section then
the above tag is not
needed.
is
mandatory then.

ShipperAccountNumber

M/O

AN 9

Please note if you did declare the
section above then the
account number within will
overwrite the entire Billing section.
Possible values:

ShippingPaymentType

M/O

AN 1

- S (use
ShipperAccountNumber as
payer)
- R (use BillingAccountNumber
as bill-to receiver account
number)
- T (use BillingAccountNumber

PAGE 105 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
as bill-to third party account
number) Please note if you
use value R or T in this tag
then the next tag
is
also mandatory

AN 9

The DHL account number used for
the shipment, if
ShippingPaymentType is equal to
R or T.

@number

Integer

Running number of the packages.

Weight

15.3 D

The weight of the package.

BillingAccountNumber
./Packages (1:1)
./RequestedPackages (1:M)

Y = allows you to define your own
PieceID in the tag below
N = Auto-allocates the PieceID
from DHL Express
You can request your own Piece
ID range from your DHL Express IT
consultant and store these locally
in your integration however this is
not needed as if you leave this tag
then DHL will automatically assign
the piece ID centrally.

UseOwnPieceIdentificationNumb
er

“Y”,”N”

In addition this special function
needs to be enabled for your
username by your DHL Express IT
Consultant.
You can request your own Piece
ID range from your DHL Express IT
consultant and store these locally
in your integration however this is
not needed as if you leave this tag
then DHL will automatically assign
the piece ID centrally.

PieceIdentificationNumber

PackageContentDescription

AN35

If you wish to use this function
then the above tag
UseOwnPieceIdentificationNumber
needs to be set as Y or 1

AN70

This optional field allows you to
provide the content description on
a piece level instead of Shipment
level.

./Dimensions

PAGE 106 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

Length

5.1 D >=0.5

Length of the piece listed.

Width

5.1 D >=0.5

Width of the piece listed.

Height

5.1 D >=0.5

Height of the piece listed.

PAGE 107 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

9.4 UPDATESHIPMENT - OUTPUT
The following diagram shows an overview of the shipment response structure. The critical
information to derive from this response are the notification codes for the response, the shipment
and piece identifiers returned and the encoded label image.

9.4.1

updateShipmentResponse Schema Diagram

Each of the individual sections of ShipmentResponse is shown below in schema diagram, with
context, and a detailed description of each field follows in the Output Field List.

9.4.2

updateShipmentResponse Output: Notification

PAGE 108 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
9.4.3

updateShipmentResponse Output: PackagesResult

9.4.4

updateShipmentResponse Output: LabelImage

9.4.5

updateShipmentResponse Output: ShipmentIdentificationNumber

This field corresponds to the airbill number associated to this shipment. This is the primary tracking
identifier within DHL, and is the DHL primary reference field in calling application.

PAGE 109 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

9.5 UPDATE SHIPMENT RESPONSE – OUTPUT FIELD LIST
Shipment Response xml
fields (Source)

Mandatory/
Optional

Values or
Constraints

@code

Message

Comments

UpdateShipmentResponse
./Notification
Error > 0 or Success Code = 0
Response Message, see Error
codes for more details

./PackagesResult
./PackageResult
"@number"

TrackingNumber

Integer

Running number of the
packages.

AN 35

This field contains a unique
number for the individual
package.

AN 3

Mapped from Request
Document. Currently always
“PDF”

./LabelImage

LabelImageFormat

GraphicImage

Base64 Binary

This field contains the actual
label as Base64 Binary. There
will be one document
containing all the labels for
each package/piece on
separate pages.

HTMLImage

Base64 Binary

Not used

ShipmentIdentificationNumber

AN 35

The shipment identification
number also named airwaybill
(AWB). This number can be
used to track the progress of
the shipment on the DHL
webside.

PAGE 110 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

10.

REQUESTPICKUP

10.1 REQUESTPICKUP - DESCRIPTION
The requestPickup request allows users to request standalone pickup requests for local and
remote/import pickups. This can be used independatly to the other services and sends a pickup
booking pickup request to the DHL Express Customer Services systems which forward the request to
the DHL Express courier systems for a courier allocation.
Remote Booking feature
You can request Remote Booking via GloWS. When BookingRequestor section is provided and
Country Code is different to the Country Code specified under Shipper section then booking is
marked as “Remote” under CSV. If the BookingRequestor section exists but the Shipper Country
Code and Booking Requestor Country Code is the same, then error message will be send to the
client.

10.2 REQUESTPICKUP - INPUT
The following diagram shows an overview of the request input structure.
10.2.1

requestPickup Schema Diagram

Each of the individual sections of requestPickup is shown below in schema diagram, with context,
and a detailed description of each field follows in the Input Field List.

PAGE 111 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

PAGE 112 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

10.2.2

requestPickup Input

The root of the requestPickup holds the pickup time stamp, the pickup location close time, optional
special pickup instructions and pickup location(I,e front door, reception etc)
PickupTimestamp - The provided PickupTimestamp in the request message will be validated
to ensure the format of provided timestamp is valid. Also, pick up date cannot be in the past or
more than 10 days in future. Sample - “2017-10-12T17:30:00GMT+00:00”
PickupLocationCloseTime - When the pickup location close time is provided in the request
message, the close time will be validated against pickup timestamp. If the pickup time is later then
provided close time, an error message will be thrown to the client. Sample – “12:00”
SpecialPickupInstruction - any special instructions you wish to send to the courier for the
order pick-up
PickupLocation - where the package should be picked up by DHL courier
10.2.3

requestPickup Input: ShipmentInfo

The ShipmentInfo section contains the product code/service type, the billing section, unit of
measurement and currency that is applicable to the pickup.

10.2.4

requestPickup Input: International Detail

The InternationalDetail section conveys data elements for international shipping.
The NumberOfPieces field is used to transmit the number of pieces in shipment the shipment to be
picked up – this is important for DHL Express to know what type of vehicle is required for the
pickup.
The Description field is used as a description of goods

PAGE 113 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

10.2.5

requestPickup Input: Ship

The Ship section outlines the shipper, recipient, pickup and booking requestor addresses.
Shipper – Is the address of the individual/company that is shipping the parcels
Recipient – Is the destination address where the shipment is to be delivered
Pickup Address – is optional in case the pickup address is different to the shipper address
Booking Requestor – is optional in case the booking requestor is not the same the shipper

10.2.6

requestPickup Input: Packages

The Packages section details the contents of individual pieces (or discrete shipping containers) within
the shipment. The minimum number of packages or pieces in a shipment is one and the upper limit
is 99.
The SpecialServices section should be used to convey Insured Value.
The Weight and Dimensions fields represent the weight and dims of the individual pieces.
The CustomerReferences field is used as the Piece Reference and the first instance is also used as the
Shipment Reference. Currently only the Shipment Reference appears on the label.

PAGE 114 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

PAGE 115 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

10.3 REQUESTPICKUP REQUEST – INPUT FIELD LIST

requestPickup fields

M/O

Values or
Constraints

Comments

requestPickupRequest
./ClientDetail
sso

This field is for internal use only

plant

This field is for internal use only

./PickUpShipment
Identifies the date and time the
package is tendered.

PickupTimestamp

PickupLocationCloseTime

AN29

The time is the local time of the
shipment based on the shipper's
time zone. The date component
must be in the format: YYYY-MMDD; the time component must be
in the format: HH:MM:SS using a
24 hour clock. The date and time
parts are separated by the letter T
(e.g. 2010-02-05T14:00:00
GMT+01:00).

AN29

identifies the pickup location close
time (i.e. what time do the
premises where the collection is
supposed to happen close). The
value must be in local time. The
value component must be HH:MM
(using a 24-hours clock format,
e.g. 14:00).

SpecialPickupInstruction

AN75

any special instructions you wish
to send to the courier for the
order pick-up

PickupLocation

AN40

where the package should be
picked up by DHL courier

./ShipmentInfo

ServiceType

AN 1

The shipping product requested
for this shipment, corresponding
to the DHL Global Product codes.

UnitOfMeasurement

“SI”,”SU”

The unit of measurement for the

PAGE 116 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
dimensions of the package.
Possible values:
- SI, international metric system
(KG, CM)
- SU, UK, US system of
measurement (LB, IN)
./Billing
The DHL account number used for
the shipment. Used as the shipper
account number. Please note if
you use this billing section then
the above tag is not
needed.
is
mandatory then.

ShipperAccountNumber

M/O

AN 9

Please note if you did declare the
section above then the
account number within will
overwrite the entire Billing section.
Possible values:

AN 1

- S (use
ShipperAccountNumber as
payer)
- R (use BillingAccountNumber
as bill-to receiver account
number)
- T (use BillingAccountNumber
as bill-to third party account
number) Please note if you
use value R or T in this tag
then the next tag
is
also mandatory

AN 9

The DHL account number used for
the shipment, if
ShippingPaymentType is equal to
R or T.

NumberOfPieces

Description

AN 1-35

ShippingPaymentType

BillingAccountNumber

M/O

./InternationalDetail
./Commodities
The number of pieces in the
shipment
The description of the content of
the shipment.

PAGE 117 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

./Ship
./Shipper
./Contact
PersonName

AN 45

A contact name of a person who
will ship the shipment.

CompanyName

AN 35

The company name the person is
working in.

PhoneNumber

AN 25

The contact person phone
number. In case of questions, this
person can be called by the
courier.

EmailAddress

AN 50

The email address of the contact
person.

MobilePhoneNumber

AN 25

The mobile phone number of the
contact person.

AN 35

The street line should contain
street name and number of the
shipper.

AN 35

Shipper street name should be
sent as separate attribute if
feasible.

AN 15

Shipper street number should be
sent as separate attribute, if
feasible.

AN 35

Shipper additional address
information

./Address

StreetLines

StreetName

StreetNumber
StreetLines2

O
O

StreetLines3

AN 35

Shipper additional address
information

City

AN 35

Shipper city name

StateOrProvinceCode

AN 2

2 Letter state code for the USA
only

PostalCode

AN 12

Shipper postal code

CountryCode

AN 2

ISO 2 character codes of the
Shipper country.

AN 45

A contact person of the pickup
location.

./Pickup (0:1)
./Contact
PersonName

PAGE 118 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

CompanyName

AN 35

The company name the person is
working in.

PhoneNumber

AN 25

The contact person phone
number. In case of questions, this
person can be called by the
courier.

EmailAddress

AN 50

The email address of the contact
person.

MobilePhoneNumber

AN 25

The mobile phone number of the
contact person.

./Address

StreetLines

AN 35

The street line should contain
street name and number of the
pickup location.

StreetName

AN 35

Pickup street name should be sent
as separate attribute if feasible.

StreetNumber

AN 15

Pickup street number should be
sent as separate attribute, if
feasible.

StreetLines2

AN 35

Pickup additional address
information

StreetLines3

AN 35

Pickup additional address
information

City

AN 35

Pickup city name

StateOrProvinceCode

AN 2

2 Letter state code for the USA
only

PostalCode

AN 12

Pickup postal code

CountryCode

AN 2

ISO 2 character codes of the
Pickup country.

PersonName

AN 45

A contact person of the pickup
location.

CompanyName

AN 35

The company name the person is
working in.

./BookingRequestor (0:1)
./Contact

PhoneNumber

AN 25

The contact person phone
number. In case of questions, this
person can be called by the
courier.

EmailAddress

AN 50

The email address of the contact

PAGE 119 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
person.
MobilePhoneNumber

AN 25

The mobile phone number of the
contact person.

./Address

StreetLines

AN 35

The street line should contain
street name and number of the
pickup location.

StreetName

AN 35

Pickup street name should be sent
as separate attribute if feasible.

StreetNumber

AN 15

Pickup street number should be
sent as separate attribute, if
feasible.

StreetLines2

AN 35

Pickup additional address
information

StreetLines3

AN 35

Pickup additional address
information

City

AN 35

Pickup city name

StateOrProvinceCode

AN 2

2 Letter state code for the USA
only

PostalCode

AN 12

Pickup postal code

CountryCode

AN 2

ISO 2 character codes of the
Pickup country.

PersonName

AN 45

A contact name of a person who
will receive the shipment.

CompanyName

AN 35

The company name the person is
working in.

./Recipient
./Contact

PhoneNumber

AN 25

The contact person phone
number. In case of questions, this
person can be called by the
courier.

EmailAddress

AN 50

The email address of the contact
person.

MobilePhoneNumber

AN 25

The mobile phone number of the
contact person.

AN 35

The street line should contain
street name and number of the

./Address
StreetLines

PAGE 120 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
reveiver.

StreetName

StreetNumber
StreetLines2

O
O

AN 35

Recipient street name should be
sent as separate attribute if
feasible.

AN 15

Recipient street number should be
sent as separate attribute, if
feasible.

AN 35

Recipient additional address
information

StreetLines3

AN 35

Recipient additional address
information

City

AN 35

Recipient city name

StateOrProvinceCode

AN 2

2 Letter state code for the USA
only

PostalCode

AN 12

Recipient postal code

CountryCode

AN 2

ISO 2 character codes of the
Receiver country.

@number

Integer

Running number of the packages.

Weight

15.3 D

The weight of the package.

CustomerReferences

AN35

Customer Reference for the piece.

Length

5.1 D >=0.5

Length of the piece listed.

Width

5.1 D >=0.5

Width of the piece listed.

Height

5.1 D >=0.5

Height of the piece listed.

./Packages (1:1)
./RequestedPackages (1:M)

./Dimensions

PAGE 121 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

10.4 REQUESTPICKUP - OUTPUT
The following diagram shows an overview of the requestPickup response structure. The critical
information to derive from this response are the notification codes for the response and the DHL
internal dispatch confirmation number and dispatch confirmation number. .

10.4.1

requestPickup Schema Diagram

Each of the individual sections of requestPickup response is shown below in the schema diagram,
with context, and a detailed description of each field follows in the Output Field List.

10.4.2

ShipmentResponse Output: Notification

10.4.3

ShipmentResponse Output: DispatchConfirmationNumber

PAGE 122 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

10.5 REQUEST PICKUP RESPONSE – OUTPUT FIELD LIST
Request Pickup Response xml Mandatory/
fields (Source)
Optional

Values or
Constraints

Comments

RequestPickUpResponse
./Notification
@code

Message

DispatchConfirmationNumber

Error > 0 or Success Code = 0
Response Message, see Error
codes for more details

AN 15

The booking reference
number.

PAGE 123 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

11.

APPENDIX

RATE REQUEST AND SHIPMENT REQUEST ERROR CODES AND MESSAGES
The following table contains the possible error for the Rate and Shipment Request processes. The
errors are broken down into categories for presentation.

CAPABILITY AND QUOTATION ERRORS- RATEREQUEST AND SHIPMENTREQUEST
For capability and quotation error codes, some errors are not possible to achieve based on schema
validation (for required fields, field format, etc).

Capability and Quotation Errors
(Rate and Shipment Requests)
Error
Code

Error Text

Notes (if applicable)

996 The requested product(s) not available based Condition met if no
products are available for
on your search criteria.
that pickup date/time.
1001 The requested product(s) not available based Condition met if no
products are available for
on your search criteria.
origin, destination.
1003 Pick-up service is not provided on this day.
1004 Product not available between this origin and
destination.
3000 The origin country code could not be found.
Please check the country code.
3001 The location country code could not be found
please check the location country parameter.
3002 The origin zip code could not be found please
check your origin zip code parameter.
3003 The origin city name could not be found
please check the city name.

Condition met for nonpostal code countries only

3004 The origin service area code could not be
found please check the origin service area
code.
3005 The destination country code could not be
found. Please check the country code.

PAGE 124 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

3006 The destination zip code could not be found
please check your destination zip code
parameter.
3007 The destination city name could not be found Condition met for nonplease check the destination city name.
postal code countries
3008 The destination service area code could not
be found please check the destination
service area code.
3010 The format of the ready time is not correct.
Please check the time format.
3011 The format of the dimensions is not correct.
Please check the dimensions format.
3012 The format of the weight is not correct.
Please check the weight format.
3013 The shipment weight is not with the
restrictions for the selected country. Please
check your piece weight.

Condition is covered
under “1001” error if
restrictions not met

3014 The shipment height is not with the
restrictions for the selected country. Please
check your piece height.

Condition is covered
under “1001” error if
restrictions not met

3015 The shipment length is not with the
restrictions for the selected country. Please
check your piece length.

Condition is covered
under “1001” error if
restrictions not met

3016 The shipment width/diameter is not with the
restrictions for the selected country. Please
check your width/diameter

Condition is covered
under “1001” error if
restrictions not met

3018 The payment country could not be found,
please check your payment country.

Returns "6000Unexpected application
error"

3019 The commodity code could not be found,
please check the commodity code.
3020 The origin location is invalid. Please check
the data.
3021 The destination location is invalid. Please
check the data.
3022 The origin postcode does not provide
standard pick up. Please call customer
service for special handling.
3023 The destination postcode does not provide
standard delivery. Please call customer
service for special handling.

PAGE 125 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

3024 Postcode not found. Expected formats:

5001 The origin country code is missing. This is a
mandatory input parameter.
5002 The origin zip code is missing. The zip code
for the selected country is mandatory.
5003 The origin city name is missing. The city
name for the selected country is mandatory.

Confirmed, for non-postal
code countries

5006 The destination zip code is missing. The zip
code for the selected country is mandatory.

5007 The destination city name is missing. The
city name for the selected country is
mandatory.

Confirmed, for non-postal
code countries

5009 The pickup date is missing. The pickup date
is a mandatory field.
5010 The ready time is missing. This is a
mandatory parameter.
5012 The piece weight is missing. This is
mandatory information for the requested
lane.
5013 The number of pieces is missing.
5014 The total shipment volume is missing.
5017 The maximum piece weight is missing.
5018 The maximum piece height is missing.
5019 The maximum piece length is missing.
5020 The maximum piece width/diameter is
missing.
5021 The declared value is missing.
5022 The piece type is invalid.
5023 The pickup date is too old.
5024 The unit of weight is missing.
5025 Sorry the maximum weight is 50kg or
110lbs.

Condition is covered
under “1001” error if
restrictions not met

5026 Sorry the maximum dimensions are
118x88x120cm or 46x35x47ins. (LxWxH)

Condition is covered
under “1001” error if

PAGE 126 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
restrictions not met
5027 Sorry the input declared value cannot exceed
the limit for this country.
5028 Unknown unit of measure for weight.
5029 Unknown unit of measure for dimensions.
5030 The currency is missing.
5031 The maximum piece weight is greater than
the total shipment weight.
5032 Unknown currency symbol.
5033 The location information is missing. Post
code, city name or suburb name should be
provided
5036 The global or local product code(s) missing.
5037 The global or local service code(s) missing.
5038 The combination unit of weight and
dimension is invalid.
5100 Invalid product service combination.
5110 Optional service not applicable.
6000 Unexpected application error

PAGE 127 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

ROUTE CODE ERRORS
For the Shipment service only, the route code is required for most EU countries, so error handling for
that lookup will only be active for those cases. The specific use case is the scenario where the route
code value is not found for the origin address.

Route Errors
(Shipment Requests Only)
Error
Code

Error Text

40050 Route Code not found for
1

Notes (if applicable)
Condition met if no
products are available for
that pickup date.

SHIPMENT DATE VALIDATION
For the Shipment service only, the ShipmentTimestamp is validated to ensure the proposed shipment
date is not in the past, and within 10 days of current date.

Shipment Date Errors
(Shipment Requests Only)
Error
Code

Error Text

Notes (if applicable)

998 The shipment date cannot be in the past or
more than 10 days in future. Please check
the shipment date and retry.

PAGE 128 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

ACCOUNT VALIDATION
For both Rate and Shipment, the account number must be valid and configured for use within the
services. For help for account setup and configuration, please see your DHL integration point of
contact.

Account Validation Errors
(Rate and Shipment Requests)
Error
Code

Error Text

Notes (if applicable)

998 The account number is not found or invalid.
Please check the account number and retry.
998 The account number is not allowed for
PaperLessTrade. Please check the account
number and retry.

LABEL GENERATION ERRORS
For Shipment service, the following errors may occur during label generation.

Label Generation Errors
(Shipment Requests only)
Error
Code

Error Text

Notes (if applicable)

20001 Neither local nor Network Product Code is
present.
20002 Origin country code is absent.
20003 Origin service area code is absent.
20004 Destination country code is absent.
20017 Neither destination postcode nor destination
code is present.
30001 Maximum length of local specific code
exceeded.
30002 Invalid postcode format.
40001 Product short name is not found.

PAGE 129 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

40002 Product content code is not found.
40004 Destination code is not found
50003 More than one destination service area codes
are found.
90001 Unclassified error.
90002 Invalid XML.
90003 Error while accessing the cache.
99999 GLS servers are not reachable.
10000 The Dangerous Goods Content ID requested
2 is invalid. Please update and try again
10000 The Dry Ice Net Weight is missing in the
2 request for the Dangerous Goods Content
ID: 901. Please update and try again.
10000 The UN code is missing in the request for the
2 Dangerous Goods Content ID: E01. Please
update and try again

MANIFEST SUBMISSION ERRORS
For Shipment service, the following errors may occur during submission of the shipment manifest.

Shipment Manifest Errors
(Shipment Requests only)

Error
Code

Error Text

Notes (if applicable)

40020 Failure during booking
1
40020 Missing field(s)",
2
40020 Error occurred while creating GNS521 file
3
40020 Error while uploading manifest file to FTP
4 server
40020 Error while transforming result to XML
5

PAGE 130 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

41140 ShipmentManifest consumer timed out.
2
998 Field
'ShipmentRequest/RequestedShipment/Ship
mentInfo/PaperlessTradeImage' is
mandatory when PaperlessTradeEnabled is
set to true.

PICKUP ERRORS
For select Shipment requests, which include a pickup request (REQUEST_COURIER), the following
errors may occur during processing of the pickup. Each of the pickup adaptor errors below carries
the same Error Code.

Pickup Errors
(Shipment Requests only)

Error
Code

Error Text

Notes (if applicable)

41092 Booking adapter error response failure
8 PU009a, 'Pickup NOT scheduled. There is no
weekend pickup service at the location.
Booking adapter error response failure
PU003, Routing Service could not determine
Origin Service Area. No pickup scheduled
Booking adapter error response failure
PU004, Account number or account type is
some type of external billing account. Pickup
Service requires a domestically billed shipper
account. No pickup scheduled
Booking adapter error response failure
PU005, Account number is not found in IBS
records. No pickup scheduled
Booking adapter error response failure
PU007a, Account number specified has a
credit status of CUT. Directed to IBS. No
pickup scheduled
Booking adapter error response failure
PU007b, Account number does not have a

PAGE 131 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
credit standing of "good standing" or
"removed from credit suspension" No
pickup scheduled
Booking adapter error response failure
PU009a, The pickup date is a weekend at the
origin service area that has no pickup
service. No pickup scheduled
Booking adapter error response failure
PU009b, The Pickup Ready-by time from the
client is before the Station Pickup start time
or after the Station Pickup end time. No
pickup scheduled
Booking adapter error response failure
PU009c, The pickup date is a holiday at
(origin service area). No pickup scheduled
Booking adapter error response failure
PU011a, The pickup request time is less than
1 hour of the station pickup end time. No
pickup scheduled.
Booking adapter error response failure
PU011b, At least one day of advance notice
is required for pickup at .
Sufficient notice not provided. No pickup
scheduled
Booking adapter error response failure
PU012, Ready by time is past the station
ready by cutoff of . No pickup
scheduled.
Booking adapter error response failure
PU013a, Insufficient time between pickup
request time and pickup end time. Pickups
require at least one hour before station
pickup end time.
Booking adapter error response failure
PU013b, Insufficient time between (current
time), and (closing time). A business pickup
requires one hour. A residence pickup
requires two hours.
Booking adapter error response failure
PU012, Ready by time is past the station
ready by cutoff of . No pickup
scheduled.
Booking adapter error response failure
PU012, Ready by time is past the station
ready by cutoff of . No pickup

PAGE 132 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
scheduled.

GENERAL ERRORS
Unexpected errors are handled with a standard error message. These error messages also contain a
process id number, which is used during troubleshooting or follow-up.

Shipment Date Errors
(Shipment Requests Only)

Error
Code

Error Text

998 Process failure occurred. Process ID
associated for that transaction (9999999)

Notes (if applicable)
Where 9999999 is the
process id

TRACKING ERRORS
For TrackingRequest service, the primary exception for the service will be “Shipment Not Found”,
with a corresponding ConditionCode of 101.

SHIPMENT DOCUMENT RETRIEVE ERRORS (EPOD)

Shipment Document Retrieve Error Codes

Error
Code

Error Text

Notes (if applicable)

10000 Service operation execution finished
0 successfully
10000 Service operation request message data
2 validation failed

HP Global Imaging epod
Service returned error
code:No matching ePODs
for search query

10001 When requesting ePod details account
0 number and customer role must be provided

PAGE 133 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

12.

SERVICE INPUT/OUTPUT EXAMPLES FOR RATEREQUEST

SOAP RATEREQUEST: SAMPLE INPUT

REQUEST_COURIER

1-16-24, Minami-gyotoku
Ichikawa-shi, Chiba
272-0138
JP

63 RENMIN LU, QINGDAO SHI
QINGDAO SHI
266033
CN

2.0

13
12
9

2010-11-26T12:00:00GMT-06:00
SU
NON_DOCUMENTS
0000000200
USD
DDP
XXXXXXXXX

PAGE 134 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
SOAP RATEREQUEST: SAMPLE OUTPUT

JPY
20475.00

JPY

EXPRESS EASY
17500.00

FUEL SURCHARGE
2975.00

2010-12-02T23:59:00

JPY
20569.00

JPY

EXPRESS WORLDWIDE
17580.00

FUEL SURCHARGE
2989.00

2010-12-02T23:59:00

SOAP RATEREQUEST: REQUEST WITH ERROR

Pick-up service is not provided on this day.

PAGE 135 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
REST RATEREQUEST: SAMPLE INPUT
{
"RateRequest" : {
"ClientDetails" : null,
"RequestedShipment" : {
"DropOffType" : "REQUEST_COURIER",
"ShipTimestamp" : "2017-09-15T11:00:00GMT+02:00",
"UnitOfMeasurement" : "SU",
"Content" : "NON_DOCUMENTS",
"PaymentInfo" : "DAP",
"NextBusinessDay" : "Y",
"Account" : XXXXXXXXX,
"Ship" : {
"Shipper" : {
"City" : "Washington, D.C.",
"PostalCode" : 20004,
"CountryCode" : "US"
},
"Recipient" : {
"City" : "canberra",
"PostalCode" : 2601,
"CountryCode" : "AU"
}
},
"Packages" : {
"RequestedPackages" : {
"@number" : "1",
"Weight" : {
"Value" : 8.82
},
"Dimensions" : {
"Length" : 4.33,
"Width" : 4.33,
"Height" : 4.33
}
}
}
}
}
}

PAGE 136 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
REST RATEREQUEST: SAMPLE OUTPUT
{"RateResponse": {"Provider": {
"@code": "DHL",
"Notification": {
"@code": "0",
"Message": null
},
"Service": [
{
"@type": "Q",
"TotalNet":
{
"Currency": "GBP",
"Amount": 233.03
},
"Charges":
{
"Currency": "GBP",
"Charge":
[
{
"ChargeType": "MEDICAL EXPRESS",
"ChargeAmount": 208.53
},
{
"ChargeType": "FUEL SURCHARGE",
"ChargeAmount": 24.5
}
]
},
"DeliveryTime": "2017-09-18T09:00:00",
"CutoffTime": "2017-09-15T19:00:00",
"NextBusinessDayInd": "N"
},
{
"@type": "Y",
"TotalNet":
{
"Currency": "GBP",
"Amount": 238.62
},
"Charges":
{
"Currency": "GBP",
"Charge":
[
{
"ChargeType": "EXPRESS 12:00",
"ChargeAmount": 208.53
},
{
"ChargeType": "12:00 PREMIUM",
"ChargeAmount": 5
},
{
"ChargeType": "FUEL SURCHARGE",
"ChargeAmount": 25.09
}
]
},
"DeliveryTime": "2017-09-18T12:00:00",
"CutoffTime": "2017-09-15T19:00:00",
"NextBusinessDayInd": "N"
},
{
"@type": "P",
"TotalNet":
{
"Currency": "GBP",
"Amount": 18.9
},
"Charges":
{
"Currency": "GBP",
"Charge":
[
{
"ChargeType": "EXPRESS WORLDWIDE",
"ChargeAmount": 16.15
},
{
"ChargeType": "FUEL SURCHARGE",
"ChargeAmount": 24.5
},
{
"ChargeType": "FUEL SURCHARGE",
"ChargeAmount": 2.75
}
]
},
"DeliveryTime": "2017-09-18T23:59:00",
"CutoffTime": "2017-09-15T19:00:00",
"NextBusinessDayInd": "N"
}
]
}}}

PAGE 137 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
REST RATEREQUEST: REQUEST WITH ERROR
{
"RateResponse":{
"Provider":{
"@code":"DHL",
"Notification":{
"Message":"The account number is not found or invalid. Please check the account number and retry."
}
}
}
}

PAGE 138 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

13.

SERVICE INPUT/OUTPUT EXAMPLES FOR SHIPMENTREQUEST

SOAP SHIPMENTREQUEST: SAMPLE INPUT

REQUEST_COURIER
U
XXXXXXXXX
EUR
SI
1
PDF
ECOM26_84_001

2010-10-29T09:30:47GMT+01:00
16:12
fragile items
west wing 3rd Floor
DDP

1
ppps sd
CZ
1
10
1

NON_DOCUMENTS

John Smith
DHL
003932423423
John.Smith@dhl.com

V Parku 2308/10
Prague
14800
CZ

Jane Smith
Deutsche Post DHL
004922832432423
Jane.Smith@dhl.de

Via Felice Matteucci 2
Firenze
50127
IT

10
9.0

46
34
31

TEST CZ-IT

PAGE 139 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
SOAP SHIPMENTREQUEST: SAMPLE OUTPUT

JD012038742880009933

PDF
JVBERi0xLjQKJe…GraphicImage>

2324866051
PRG999126012345

SOAP SHIPMENTREQUEST: SAMPLE REQUEST WITH ERROR

The requested product(s) (X) not available based on your search criteria.(8614)

Process failure occurred. Process ID associated for that transaction (8614)

PAGE 140 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
REST SHIPMENTREQUEST: SAMPLE INPUT
{
"ShipmentRequest" : {
"RequestedShipment" : {
"ShipmentInfo" : {
"DropOffType" : "REGULAR_PICKUP",
"ServiceType" : "P",
"Account" : XXXXXXXXX,
"Currency" : "SGD",
"UnitOfMeasurement" : "SI"
},
"ShipTimestamp" : "2017-09-21T12:30:47GMT+01:00",
"PaymentInfo" : "DDP",
"InternationalDetail" : {
"Commodities" : {
"NumberOfPieces" : 1,
"Description" : "Customer Reference 1",
"CountryOfManufacture" : "CN",
"Quantity" : 1,
"UnitPrice" : 5,
"CustomsValue" : 10
},
"Content" : "NON_DOCUMENTS"
},
"Ship" : {
"Shipper" : {
"Contact" : {
"PersonName" : "Tester 1",
"CompanyName" : "DHL",
"PhoneNumber" : 2175441239,
"EmailAddress" : "jb@acme.com"
},
"Address" : {
"StreetLines" : "#05-33 Singapore Post Centre",
"City" : "Singapore ",
"PostalCode" : 408600,
"CountryCode" : "SG"
}
},
"Recipient" : {
"Contact" : {
"PersonName" : "Tester 2",
"CompanyName" : "Acme Inc",
"PhoneNumber" : 88347346643,
"EmailAddress" : "jackie.chan@eei.com"
},
"Address" : {
"StreetLines" : "500 Hunt Valley Road",
"City" : "New Kensington PA",
"StateOrProvinceCode" : "PA",
"PostalCode" : 15068,
"CountryCode" : "US"
}
}
},
"Packages" : {
"RequestedPackages" : [ {
"@number" : "1",
"Weight" : 2,
"Dimensions" : {
"Length" : 1,
"Width" : 2,
"Height" : 3
},
"CustomerReferences" : "Piece 1"
}, {
"@number" : "2",
"Weight" : 2,
"Dimensions" : {
"Length" : 1,
"Width" : 2,
"Height" : 3
},
"CustomerReferences" : "Piece 2"
}]
}
}

PAGE 141 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
REST SHIPMENTREQUEST: SAMPLE OUTPUT
{
"ShipmentResponse":{
"Notification":{
"@code":"0",
"Message":null
},
"PackagesResult":{
"PackageResult":[
{
"@number":"1",
"TrackingNumber":"JD012959120890065400"
},
{
"@number":"2",
"TrackingNumber":"JD012959120890065401"
}
]
},
"LabelImage":{
"LabelImageFormat":"PDF",
"GraphicImage":"JVBERi0....."
},
"ShipmentIdentificationNumber":1117120421
}
}

REST SHIPMENTREQUEST: SAMPLE REQUEST WITH ERROR
{
"ShipmentResponse":{
"Notification":[
{
"@code":"998",
"Message":"The shipment date cannot be in the past or more than 10 days in future. Please check the shipment date and retry.'"
},
{
"@code":"999",
"Message":"Process failure occurred. Process ID associated for that transaction (54293765)"
}
]
}
}

PAGE 142 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

14.

SERVICE INPUT/OUTPUT EXAMPLES FOR SHIPMENTDELETEREQUEST

SOAP SHIPMENTDELETEREQUEST: SAMPLE INPUT

2010-12-03
IT
PRG999126012345
Tom Jones
001

SOAP SHIPMENTDELETEREQUEST: SAMPLE OUTPUT

Successfully cancelled

SOAP SHIPMENTDELETEREQUEST: SAMPLE REQUEST WITH ERROR

Cancellation of booking was not successful. Requested Pickup was not found.

REST SHIPMENTDELETEREQUEST: SAMPLE INPUT
{
"DeleteRequest" : {
"PickupDate" : "2017-07-24",
"PickupCountry" : "SG",
"DispatchConfirmationNumber" : " PRG999126012345",
"RequestorName" : "Terry Kelly",
"Reason" : "001"
}
}

PAGE 143 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
REST SHIPMENTDELETEREQUEST: SAMPLE OUTPUT
{
"DeleteResponse":{
"Notification":{
"@code":"0",
"Message":"Successfully cancelled"
}
}
}

REST SHIPMENTDELETEREQUEST: SAMPLE REQUEST WITH ERROR
{
"DeleteResponse":{
"Notification":{
"@code":"410928",
"Message":"Cancellation of booking was not successful. Requested Pickup was not found."
}
}
}

PAGE 144 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

15.

SERVICE INPUT/OUTPUT EXAMPLES FOR TRACKINGREQUEST

SOAP TRACKINGREQUEST: SAMPLE INPUT

2010-11-24T00:17:20Z
1234

2330982222

ALL_CHECK_POINTS
B

PAGE 145 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

SOAP TRACKINGREQUEST: SAMPLE OUTPUT

2011-01-12T18:41:12Z
86ef86501e7b11e08c81df5507f6bac8

2331017371

Success

FLR
Florence - Italy

BRI
Bari - Italy
WAD

NUOVO PIGNONE SPA
NUOVO PIGNONESPA
2010-11-09T14:33:00+01:00
1
0.500

2010-11-10
15:12:00

MD
Missed Delivery
Cycle

BRI
Bari Italy

2331017371
JD012038742880020267
0.000
0.000
0.000
1.000
1.000
1.000
0.500

0.520
KG

2010-1111
11:52:00

OK
Delivery

DEPALMA

BRI
Bari - Italy
/S

i A

PAGE 146 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
SOAP TRACKINGREQUEST: SAMPLE ERROR

2011-01-12T17:40:58Z
1d136ec01e7311e0a468e3cd6e9dbbd4

2330982222

No Shipments Found

101
No Shipments Found for AWBNumber |
2330982222

REST TRACKINGREQUEST: SAMPLE INPUT
{
"trackShipmentRequest":{
"trackingRequest":{
"TrackingRequest":{
"Request":{
"ServiceHeader":{
"MessageTime":"2017-10-10T12:40:00Z",
"MessageReference":"896ab310ba5311e38d9ffb21b7e57543"
}
},
"AWBNumber":{
"ArrayOfAWBNumberItem":7780184230
},
"LevelOfDetails":"ALL_CHECK_POINTS",
"PiecesEnabled":"B"
}
}
}
}

PAGE 147 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
REST TRACKINGREQUEST: SAMPLE OUTPUT
{
"trackShipmentRequestResponse":{
"trackingResponse":{
"TrackingResponse":{
"Response":{
"ServiceHeader":{
"MessageTime":"2017-09-21T10:59:13",
"MessageReference":"6ea09520923c143aabd7daed6f9f814c"
}
},
"AWBInfo":{
"ArrayOfAWBInfoItem":{
"AWBNumber":7780184230,
"Status":{
"ActionStatus":"Success"
},
"ShipmentInfo":{
"OriginServiceArea":{
"ServiceAreaCode":"KUL",
"Description":"-"
},
"DestinationServiceArea":{
"ServiceAreaCode":"SIN",
"Description":"Singapore-SG",
"FacilityCode":"PEK"
},
"ShipperName":"FRESIA AGUIRRE RIVERA ",
"ConsigneeName":"EMEC INT TRADING ",
"ShipmentDate":"2015-10-11T16:00:00",
"Pieces":1,
"Weight":1,
"ShipmentEvent":{
"ArrayOfShipmentEventItem":[
{
"Date":"2015-10-12",
"Time":"00:00:00",
"ServiceEvent":{
"EventCode":"PU",
"Description":"Shipment Pickup "
},
"ServiceArea":{
"ServiceAreaCode":"KUL",
"Description":"Kuala Lumpur-MY"
}
},
{
"Date":"2015-10-12",
"Time":"00:00:11",
"ServiceEvent":{
"EventCode":"OK",
"Description":"Delivery "
},
"Signatory":"TEST99",
"ServiceArea":{
"ServiceAreaCode":"KUL",
"Description":"Kuala Lumpur-MY"
}
}
]
}
},
"Pieces":{
"PieceInfo":{
"ArrayOfPieceInfoItem":{
"PieceDetails":{
"AWBNumber":7780184230,
"LicensePlate":"JD013060280590274678",
"ActualDepth":39.5,
"ActualWidth":25.5,
"ActualHeight":29,
"Depth":25,
"Width":18,
"Height":5,
"Weight":2.78,
"PackageType":null,
"DimWeight":4.75,
"WeightUnit":"KG"
},
"PieceEvent":{
"ArrayOfPieceEventItem":[
{
"Date":"2013-10-02",
"Time":"13:15:00",
"ServiceEvent":{
"EventCode":"PU",
"Description":"Shipment Pickup "
},
"ServiceArea":{
"ServiceAreaCode":"BCN",
"Description":"Barcelona-ES"
},
"ShipperReference":{
"ReferenceID":null
}
}
]
}
}
}
}
}

PAGE 148 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
REST TRACKINGREQUEST: SAMPLE ERROR
{
"trackShipmentRequestResponse":{
"trackingResponse":{
"TrackingResponse":{
"Response":{
"ServiceHeader":{
"MessageTime":"2017-09-21T11:10:55",
"MessageReference":"46076490c5db1c75a95ebf67a4977f89"
}
},
"AWBInfo":{
"ArrayOfAWBInfoItem":{
"AWBNumber":7782184230,
"Status":{
"ActionStatus":"No Shipments Found",
"Condition":{
"ArrayOfConditionItem":{
"ConditionCode":101,
"ConditionData":"No Shipments Found for AWBNumber | 7782184230"
}
}
}
}
}
}
}
}
}

PAGE 149 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

16.

SERVICE INPUT/OUTPUT EXAMPLES FOR EPOD

SOAP EPOD: SAMPLE INPUT

PAGE 150 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

SOAP EPOD: SAMPLE OUTPUT

SOAP EPOD: SAMPLE ERROR RESPONSE

PAGE 151 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
REST EPOD: SAMPLE INPUT
{
"shipmentDocumentRetrieveReq":
{
"MSG": {
"Hdr": {
"@Dtm": "2013-04-16T23:59:59",
"@Id": "SunnyTesting",
"@Ver": "1.038",
"Sndr": {
"@AppCd": "DCG",
"@AppNm": "DCG",
"@CmptNm": "HP"
}
},
"Bd": {
"Shp": {
"@Id": "8564385550",
"ShpInDoc": {
"SDoc": {
"@DocTyCd": "POD"
}
}
},
"GenrcRq": {"GenrcRqCritr":[
{
"@TyCd": "IMG_CONTENT",
"@Val": "epod-summary-esig"
},
{
"@TyCd": "IMG_FORMAT",
"@Val": "PDF"
},
{
"@TyCd": "DOC_RND_REQ",
"@Val": "true"
},
{
"@TyCd": "EXT_REQ",
"@Val": "true"
},
{
"@TyCd": "DUPL_HANDL",
"@Val": "CORE_WB_NO"
},
{
"@TyCd": "SORT_BY",
"@Val": "$INGEST_DATE,D"
},
{
"@TyCd": "LANGUAGE",
"@Val": "en"
}
]}
}
}
}
}

PAGE 152 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

REST EPOD: SAMPLE OUTPUT
{"shipmentDocumentRetrieveResp": {"MSG": {
"Hdr": {
"@Ver": "1.038",
"@Id": "288890093",
"@Dtm": "2018-01-26T08:08:20",
"Sndr":
{
"@AppNm": "ESB",
"@AppCd": "ESB"
},
"Rcp":
{
"@AppNm": "DCG",
"@AppCd": "DCG",
"GId":
{
"@Id": "SunnyTesting",
"@IdTp": "RQMSGID"
}
}
},
"Bd": {"Shp": {"ShpInDoc": {"SDoc": {
"@DocTyCd": "POD",
"Img":
{
"@ImgMimeTy": "application/pdf",
"@Img": "JVBERi0xLXXXXX........"
}
}}}},
"DatTrErr": {
"OrgHdr": {"@CorrId": "SunnyTesting"},
"Rp": {"@CmptNm": "GWSManagement.ShipmentDocumentRetrieveRequestProvider"},
"ErrMsgGI":
{
"@Pri": "2",
"@Ty": "CF",
"@Sev": "10"
},
"DatErrMsg": {"ErrMsgDtl":
{
"@DtlDsc": "Service operation execution finished successfully",
"@Dsc": "Service operation execution finished successfully",
"@MsgCIgd": "100000",
"@MsgClg": "IPESB"
}}
}
}}}

PAGE 153 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
REST EPOD: SAMPLE ERROR MESSAGE
{"shipmentDocumentRetrieveResp": {"MSG": {
"Hdr": {
"@Ver": "1.038",
"@Id": "288899874",
"@Dtm": "2018-01-26T08:17:59",
"Sndr":
{
"@AppNm": "ESB",
"@AppCd": "ESB"
},
"Rcp":
{
"@AppNm": "DCG",
"@AppCd": "DCG",
"GId":
{
"@Id": "SunnyTesting",
"@IdTp": "RQMSGID"
}
}
},
"Bd": {"Shp": {"ShpInDoc": {"SDoc": {"@DocTyCd": ""}}}},
"DatTrErr": [
{
"OrgHdr": {"@CorrId": "SunnyTesting"},
"Rp": {"@CmptNm": "GWSManagement.ShipmentDocumentRetrieveRequestProvider"},
"ErrMsgGI":
{
"@Pri": "2",
"@Ty": "CF",
"@Sev": "40"
},
"DatErrMsg": {"ErrMsgDtl":
{
"@DtlDsc": "HP Global Imaging epod Service returned error code:No matching ePODs for search query",
"@Dsc": "Service operation execution finished successfully",
"@MsgCIgd": "100000",
"@MsgClg": "IPESB"
}}
},
{
"OrgHdr": {"@CorrId": "SunnyTesting"},
"Rp": {"@CmptNm": "GWSManagement.ShipmentDocumentRetrieveRequestProvider"},
"ErrMsgGI":
{
"@Pri": "2",
"@Ty": "CF",
"@Sev": "10"
},
"DatErrMsg": {"ErrMsgDtl":
{
"@DtlDsc": "Service operation execution finished successfully",
"@Dsc": "Service operation execution finished successfully",
"@MsgCIgd": "100000",
"@MsgClg": "IPESB"
}}
}
]
}}}

PAGE 154 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

17.

SERVICE INPUT/OUTPUT EXAMPLES FOR UPDATESHIPMENT

SOAP UPDATESHIPMENT: SAMPLE INPUT

Sample_Message_Id

P
123456789

123456789
S

1234567890
PDF
ECOM_TC_A4
ARCH_8x4
Y

2018-01-24

5.350
N
Gloves

32.0
10.0
5.0

PAGE 155 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

SOAP UPDATESHIPMENT: SAMPLE OUTPUT

JDAA06000121212121

PDF
JVBERi0xLjQKJfbk/N8KMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovVmVRU9GCg==

1234567890

SOAP UPDATESHIPMENT: SAMPLE ERROR MESSAGE

Piece update is not possible as shipment information not found in the database

Failed to process your request. Process ID associated for this transaction (1234567890)

PAGE 156 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

REST UPDATESHIPMENT: SAMPLE INPUT
{ "UpdateRequest":
{
"MessageId": "Sample_Message_Id",
"UpdatedShipment": {
"ShipmentInfo": {
"ServiceType": "P",
"Account": "123456789",
"Billing": {
"ShipperAccountNumber": "123456789",
"ShippingPaymentType": "S"
},
"ShipmentIdentificationNumber": "1234567890",
"LabelType": "PDF",
"LabelTemplate": "ECOM_TC_A4",
"ArchiveLabelTemplate": "ARCH_8x4",
"IncludePreviousPieceLabels": "Y"
},
"OriginalShipDate": "2018-01-24",
"Packages": {
"RequestedPackages": {
"@number": "1",
"Weight": "5.350",
"UseOwnPieceIdentificationNumber": "N",
"PackageContentDescription": "Gloves2",
"Dimensions": {
"Length": "32.0",
"Width": "10.0",
"Height": "5.0"
}
}
}
}
}
}

REST UPDATESHIPMENT: SAMPLE OUTPUT
{"UpdateResponse": {
"Notification": {
"@code": "0",
"Message": null
},
"PackagesResult": {"PackageResult": {
"@number": "1",
"TrackingNumber": "JD0ASDSFSE3687493085"
}},
"LabelImage": {
"LabelImageFormat": "PDF",
"GraphicImage": "JVBERi0xLjQKJfbk/N8KMSAwIG9iago8PAovVHlwZSAvQ2F0YJUVPRgo="
},
"ShipmentIdentificationNumber": 1234567890
}}

PAGE 157 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

REST UPDATESHIPMENT: SAMPLE ERROR MESSAGE
{"UpdateResponse": {"Notification": [
{
"@code": "998",
"Message": "The account number is not found or invalid. Please check the account number and retry."
},
{
"@code": "999",
"Message": "Failed to process your request. Process ID associated for this transaction (141414145151)"
}
]}}

PAGE 158 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

18.

SERVICE INPUT/OUTPUT EXAMPLES FOR REQUESTPICKUP

SOAP REQUESTPICKUP: SAMPLE INPUT

2364878234817650001982134234

140582622
S

2018-01-26T12:59:00 GMT+01:00
17:00
Collect at reception
Receptoin

1
Computer Parts

Topaz
DHL Express
+31 6 53464291
Topaz.Test@dhl.com
+31 6 53464291

GloWS
Eindhoven
5657 ES
NL

Jack Jones
J and J Company
+44 25 77884444
jack@jjcompany.com
+44 5 88648666

Penny lane
Liverpool
AA21 9AA
GB

12.0

70
21
44

My-PU-Call-1

PAGE 159 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
SOAP REQUESTPICKUP: SAMPLE OUTPUT

PRG999126012345

SOAP REQUESTPICKUP: SAMPLE ERROR MESSAGE

The account number is not found or invalid. Please check the account number and retry.

Failed to process your request. Process ID associated for this transaction (1862502637)

PAGE 160 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

REST REQUESTPICKUP: SAMPLE INPUT
{
"PickUpRequest":
{
"PickUpShipment": {
"ShipmentInfo": {
"ServiceType": "U",
"Billing": {
"ShipperAccountNumber": "123456789",
"ShippingPaymentType": "S"
},
"UnitOfMeasurement": "SI"
},
"PickupTimestamp": "2018-01-26T12:59:00 GMT+01:00",
"PickupLocationCloseTime": "17:00",
"SpecialPickupInstruction": "Collect at reception",
"PickupLocation": "Receptoin",
"InternationalDetail": {
"Commodities": {
"NumberOfPieces": "1",
"Description": "Computer Parts"
}
},
"Ship": {
"Shipper": {
"Contact": {
"PersonName": "Topaz",
"CompanyName": "DHL Express",
"PhoneNumber": "+31 6 53464291",
"EmailAddress": "Topaz.Test@dhl.com",
"MobilePhoneNumber": "+31 6 53464291"
},
"Address": {
"StreetLines": "GloWS",
"City": "Eindhoven",
"PostalCode": "5657 ES",
"CountryCode": "NL"
}
},
"Recipient": {
"Contact": {
"PersonName": "Jack Jones",
"CompanyName": "J and J Company",
"PhoneNumber": "+44 25 77884444",
"EmailAddress": "jack@jjcompany.com",
"MobilePhoneNumber": "+44 5 88648666"
},
"Address": {
"StreetLines": "Penny lane",
"City": "Liverpool",
"PostalCode": "AA21 9AA",
"CountryCode": "GB"
}
}
},
"Packages": {
"RequestedPackages": {
"@number": "1",
"Weight": "12.0",
"Dimensions": {
"Length": "70",
"Width": "21",
"Height": "44"
},
"CustomerReferences": "My-PU-Call-1"
}
}
}
}
}

PAGE 161 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

REST REQUESTPICKUP: SAMPLE OUTPUT
{"PickUpResponse": {
"Notification": {
"@code": "0",
"Message": null
},
"DispatchConfirmationNumber": "PRG999126012345"
}}

REST REQUESTPICKUP: SAMPLE ERROR MESSAGE
{"PickUpResponse": {"Notification": [
{
"@code": "998",
"Message": "The account number is not found or invalid. Please check the account number and retry."
},
{
"@code": "999",
"Message": "Failed to process your request. Process ID associated for this transaction (1231313213132)"
}
]}}

PAGE 162 OF 163

DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE

19.

HELPFUL XML AND WEB SERVICES LINKS

XML.Org Home Page, Organization for the Advancement of Structured Information Standards
(OASIS)
http://www.xml.org/
W3 Schools XML Tutorial, Reference Data
http://www.w3schools.com/xml/default.asp
Java Technology and Web Services, Sun Microsystems, Inc.
http://java.sun.com/webservices/
Apache Web Services Project, The Apache Software Foundation
http://ws.apache.org/
W3 Schools Web Services Tutorial, Reference Data
http://www.w3schools.com/webservices/default.asp

PAGE 163 OF 163

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : Yes
Author                          : Your Name Goes Here (see 'File'  'Properties')
Company                         : DHL
Create Date                     : 2018:01:30 13:02:35Z
Modify Date                     : 2018:01:30 13:03:05Z
Source Modified                 : D:20180130130221
Subject                         : Project Name Goes Here
Tagged PDF                      : Yes
XMP Toolkit                     : Adobe XMP Core 5.4-c005 78.147326, 2012/08/23-13:03:03
Metadata Date                   : 2018:01:30 13:03:05Z
Creator Tool                    : Acrobat PDFMaker 11 for Word
Document ID                     : uuid:9eb7214e-ea80-4295-b719-430a6978b435
Instance ID                     : uuid:c2a2ad70-0c3f-4507-bd13-ad31e2f56761
Format                          : application/pdf
Title                           : Project Brief
Description                     : Project Name Goes Here
Creator                         : Your Name Goes Here (see 'File'  'Properties')
Producer                        : Adobe PDF Library 11.0
Keywords                        : 
Headline                        : Project Name Goes Here
Page Layout                     : OneColumn
Page Count                      : 163

EXIF Metadata provided by EXIF.tools

Project Brief DHL Express Global Web Services Developer Guide V4.0.1

Navigation menu

Versions of this User Manual:

Views

Navigation