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

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 163 [warning: Documents this large are best viewed by clicking the View PDF Link!]

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. INTRODUCTION.................................................................................................................. 6
1.1 DHL EXPRESS GLOBAL WEB SERVICES OVERVIEW ........................................................................ 6
1.2 REQUIREMENTS – TECHNICAL SKILLS ......................................................................................... 6
1.3 REQUIREMENTS – BUSINESS UNDERSTANDING .............................................................................. 6
2. DHL EXPRESS GLOBAL WEB SERVICES OVERVIEW........................................................... 7
2.1 WEB SERVICE DEFINITION LANGUAGE AND REFERENCE DOCUMENTS ................................................ 7
2.2 SECURITY AND AUTHENTICATION ............................................................................................. 8
3. WHAT WEB SERVICES OPERATIONS ARE AVAILABLE? .................................................... 9
4. 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 Document
WSDL
Description
RateRequest
ShipmentRequest
ShipmentDeleteRequest
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:
<wsse:UsernameToken wsu:Id="Example">
<wsse:Username> ... </wsse:Username>
<wsse:Password Type="..."> ... </wsse:Password>
<wsse:Nonce EncodingType="..."> ... </wsse:Nonce>
<wsu:Created> ... </wsu:Created>
</wsse: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 Description Document
WSDL
Description
a) RateRequest
b) ShipmentRequest
c) ShipmentDeleteRequest
https://wsbexpress.dhl.com:443/snd
pt/expressRateBook?WSDL
WSDL
Description
d) TrackingRequest
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
f) updateShipment
https://wsbexpress.dhl.com:443/snd
pt/updateShipment?WSDL
WSDL
Description
g) requestPickup
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 O This field is for internal use only
plant O This field is for internal use only
./RequestedShipment
DropOffType M
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
The rating response returns products for
which the pickup capability is given,
based on ShipmentTimeStamp.
NextBusinessDay O AN 1 Possible values include Y, N
RequestValueAddedServi
ces O AN 1
If the value is "Y" all the additional
services available for the product
selected will be returned. The default
value is "N".
./Ship
./Shipper
StreetLines O AN 35 Shipper street name and number
StreetName O
AN 35 Shipper street name should already be
sent as separate attribute if feasible.
StreetNumber O
AN 15 Shipper street number should be sent as
separate attribute, if feasible.
StreetLines2 O AN 35 Shipper additional address information
StreetLines3 O AN 35 Shipper additional address information
City M AN 35 Shipper city name
StateOrProvinceCode O AN 2 2 letter state code for the USA only
PostalCode M AN 12 Shipper postal code
PAGE 17 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
CountryCode M
AN 2 ISO 2 character codes of the Shipper
country.
./Recipient
./Address
StreetLines M AN 35 Recipient street name and number
StreetName O
AN 35 Recipient street name should be sent as
separate attribute if feasible.
StreetNumber O
AN 15 Recipient street number should be sent
as separate attribute, if feasible.
StreetLines2 O AN 35 Recipient additional address information
StreetLines3 O AN 35 Recipient additional address information
City M AN 35 Recipient city name
StateOrProvinceCode O AN 2 2 Letter State code for the USA only
PostalCode M AN 12 Recipient postal code
CountryCode M
AN 2 ISO 2 character codes of the Receiver
country.
./Packages (1:1)
./RequestedPackages (1:M)
@number M
No length
constraint
Max 50
occurrences
Will be used as Piece Sequence number
and returned in the response.
Weight M 15.3 D
Sum of the weight of the individual
pieces/packages the rating request is
for.
./Dimensions
Length M 5.1 D >=1 Length of the piece listed.
Width M 5.1 D >=1 Width of the piece listed.
Height M 5.1 D >=1 Height of the piece listed.
ShipTimestamp M
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
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.
UnitOfMeasurement M N/A
Possible values:
- SI, international metric system (KG,
CM)
- SU, UK, US system of measurement
(LB, IN)
The unit of measurement for the
dimensions of the package.
Content M N/A
Possible values
- DOCUMENTS
- NON_DOCUMENTS
DeclaredValue O 15.3 Declared value of the shipment
DeclaredValueCurrecyCo
de O AN 3
3 character currency code for the
declared value
PaymentInfo M N/A
Possible values:
- See schema enumeration
Account M 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
<Account> tag then the Billing section
below is not needed
Billing
ShipperAccountNumber O 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
<Account> tag is not needed.
<ShipperAccountNumber> is mandatory
then.
ShippingPaymentType O AN 1
Possible values:
- 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
<BillingAccountNumber> is also
mandatory
BillingAccountNumber O N/A
The DHL account number used for the
shipment, if ShippingPaymentType is
equal to R or T.
./SpecialServices
./Service
ServiceType M 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.
ServiceValue O 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 O AN 3
Currency code) – this is needed if you
wish to get a quote on Insurance with
your prospect shipment
PaymentCode O AN 3 For future use.
StartDate O Date For future use.
EndDate O Date For future use.
TextInstruction O 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 <ChargeCode> 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.
<ChargeType> 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
Rate Response fields
Mandatory
/Optional
Value
constraints Comments
RateResponse
./Provider
"@code" M
Provider Code, always contains
DHL.
./Notification
"@code" M Error > 0 or Success Code = 0
message M
Response Message, see Error
codes for more details
./Service
"@type" M
This is the code for the product for
which the delivery is feasible
respecting the input data from the
request.
"@account" O Not used.
DeliveryTime O
This is the estimated date/time the
shipment will be delivered by for
the rated shipment and product
listed
CutoffTime O
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.
NextBusinessDayInd O
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).
./TotalNet
Currency M
This the currency of the rated
shipment for the product listed.
Amount M
This is the total prize of the rated
PAGE 24 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
shipment for the product listed.
./Charges
Currency M
This the currency for all line item
charges listed in the Charge
section
./Charge (1:M)
ChargeCode O
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 M Name of the Value Added Service
ChargeAmount M
The charge amount of the line
item charge.
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
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.
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
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.
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.
<ExportReference>AES X20101010123456</ExportReference>
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
M
/O
Values
or
Constr
aints
Comments
ShipmentRequest
./ClientDetail
sso O This field is for internal use only
plant O This field is for internal use only
./RequestedShipment
./ShipmentInfo
@provider O "DHL"
DropOffType M
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
The rating response returns products for which the
pickup capability is given, based on
ShipmentTimeStamp.
ServiceType M AN 1
The shipping product requested for this shipment,
corresponding to the DHL Global Product codes.
Account
M/
O AN 9
The customer account to be used as payer in the
request. If the <Account> tag is used then there is
no need to populate the Billing section further down
below in this table as the <Account> tag will
override any other accounts entered.
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 M AN 3
The currency of the monetary values presented in
the request.
UnitOfMeasurement M AN 2
The unit of measurement for the dimensions of the
package.
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 O
“Y”,“
N”
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
UseOwnShipmentdentificationNumber set to Y and
this feature enabled within client profile.
UseOwnShipmentIde
ntificationNumber O
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.
PackagesCount O N/A Number of packages which need to be processed.
SendPackage O N/A
LabelType O AN 3
Possible values:
- PDF
- ZPL
- EPL
- LP2
LabelTemplate O 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.
ArchiveLabelTemplate O 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.
PaperlessTradeEnable
d O
N1 or
A5
Possible values (case sensitive):
- true
- false
PAGE 39 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
- 0
- 1
PaperlessTradeImage O
Base64
binary Base64 encoded image. Max size 1MB A4
ShipTimestamp M
YYYY-
MM-
DDT24
HH:M
M:SS
GMT+
k
This timestamp identifies the pickup 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
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.
PickupLocationCloseTi
me O
HH:m
m
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
Sample: 17:00
SpecialPickupInstructi
on O AN 75
This node details special pickup instructions you may
wish to send to the DHL Courier
PickupLocation O AN 40
This node provides information on where the
package should be picked up by DHL courier.
PaymentInfo M AN 3
Possible values:
- See schema enumeration
./Billing
ShipperAccountNumb
er
O
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
<Account> tag is not needed.
<ShipperAccountNumber> is mandatory then.
ShippingPaymentType
M/
O AN 1
Possible values:
- 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
<BillingAccountNumber> is also mandatory
PAGE 40 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
BillingAccountNumbe
r O AN 9
The DHL account number used for the shipment, if
ShippingPaymentType is equal to R or T.
./SpecialServices
./Service
ServiceType M 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.
ServiceValue O 15.3 D Monetary value of service (currently only applicable
for Insurance)
CurrencyCode O AN 3 Currency code
PaymentCode O AN 3 For future use.
StartDate O Date For future use.
EndDate O Date For future use.
TextInstruction O AN50 For future use.
./InternationalDetail
./Commodities
NumberOfPieces M N6 The number of pieces in the shipment
Description M
AN 1-
35 The description of the content of the shipment.
CountryOfManufactu
re O AN 2
The country of manufacture of the content of the
shipment.
Quantity O N 10
The quantity of the items in the shipment, e.g. 3
books.
UnitPrice O 18.3 D
Price per item in the shipment, e.g. 7.50 € if one of
the books costs 7.50€.
CustomsValue O 18.3 D The value which needs to be declared for customs.
Content M N/A
Possible values
- DOCUMENTS
- NON_DOCUMENTS
USFillingTypeValue O AN 20 The US filing Type Value for shipments from the US
ExportReference O 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”,”
SW”,”
SX”
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:
PAGE 41 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
Location O AN15
Mandatory if the above delivery option is SX and
should advise DHL where exactly to leave the
shipment (ie.front door etc)
Instructions O AN110
Additional information that is useful for the DHL
Express courier
GateCode O AN10
Entry code to gain access to an apartment complex
or gate
LWNTypeCode O
“N”,”
C”
Mandatory if the above delivery option is SW . The
possible values are
N – Leave with neighbour
C – Leave with concierge
NeighbourName O AN20
Mandatory if the delivery option is SW and the
LWNTypeCode is N (Neighbour) – this is where the
name of the neighbour is required
NeighbourHouseNum
ber O AN20
Mandatory if the delivery option is SW and the
LWNTypeCode is N (Neighbour) – this is the house
number of the neighbour
AuthorizerName O 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 O 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 O AN29 Reserved for future use
./Ship
./Shipper
./Contact
PersonName M AN 45 A contact name of a person who will ship the
shipment.
CompanyName M AN 35 The company name the person is working in.
PhoneNumber M AN 25
The contact person phone number. In case of
questions, this person can be called by the courier.
EmailAddress O AN 50 The email address of the contact person.
MobilePhoneNumber O AN 25 The mobile phone number of the contact person.
./Address
StreetLines M AN 35 The street line should contain street name and
PAGE 42 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
number of the shipper.
StreetName O AN 35
Shipper street name should be sent as separate
attribute if feasible.
StreetNumber O AN 15
Shipper street number should be sent as separate
attribute, if feasible.
StreetLines2 O AN 35 Shipper additional address information
StreetLines3 O AN 35 Shipper additional address information
City M AN 35 Shipper city name
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Shipper postal code
CountryCode M AN 2 ISO 2 character codes of the Shipper country.
./Pickup
./Contact
PersonName M AN 45 A contact name of a person who will give the
shipment.to the courier
CompanyName M AN 35 The company name the person is working in.
PhoneNumber M AN 25
The contact person phone number. In case of
questions, this person can be called by the courier.
EmailAddress O AN 50 The email address of the contact person.
MobilePhoneNumber O AN 25 The mobile phone number of the contact person.
./Address
StreetLines M AN 35 The street line should contain street name and
number of the pickup place.
StreetName O AN 35
Pickup street name should be sent as separate
attribute if feasible.
StreetNumber O AN 15
Pickup street number should be sent as separate
attribute, if feasible.
StreetLines2 O AN 35 Pickup additional address information
StreetLines3 O AN 35 Pickup additional address information
City M AN 35 Pickup city name
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Pickup postal code
CountryCode M AN 2 ISO 2 character codes of the Pickup country.
./BookingRequestor
PAGE 43 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
./Contact
PersonName M AN 45 A contact name of a person who is requesting the
pickup.
CompanyName M AN 35 The company name the person is working in.
PhoneNumber M AN 25
The contact person phone number. In case of
questions, this person can be called by the courier.
EmailAddress O AN 50 The email address of the contact person.
MobilePhoneNumber O AN 25 The mobile phone number of the contact person.
./Address
StreetLines M AN 35 The street line should contain street name and
number of pickup requestor
StreetName O AN 35
Pickup street name should be sent as separate
attribute if feasible.
StreetNumber O AN 15
Pickup street number should be sent as separate
attribute, if feasible.
StreetLines2 O AN 35 Pickup additional address information
StreetLines3 O AN 35 Pickup additional address information
City M AN 35 Pickup city name
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Pickup postal code
CountryCode M AN 2
ISO 2 character codes of the Pickup Requestor
country.
./Buyer
./Contact
PersonName M AN 45 A contact name of a person who acts as Buyer
CompanyName M AN 35 The company name the person is working in.
PhoneNumber M AN 25
The contact person phone number. In case of
questions, this person can be called by the courier.
EmailAddress O AN 50 The email address of the contact person.
MobilePhoneNumber O AN 25 The mobile phone number of the contact person.
./Address
StreetLines M AN 35 The street line should contain street name and
number of the shipper.
StreetName O AN 35
Pickup street name should be sent as separate
attribute if feasible.
PAGE 44 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
StreetNumber O AN 15
Pickup street number should be sent as separate
attribute, if feasible.
StreetLines2 O AN 35 Pickup additional address information
StreetLines3 O AN 35 Pickup additional address information
City M AN 35 Pickup city name
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Pickup postal code
CountryCode M AN 2 ISO 2 character codes of the Buyer country.
./Recipient
./Contact
PersonName M AN 45 A contact name of a person who will ship the
shipment.
CompanyName M AN 35 The company name the person is working in.
PhoneNumber M AN 25
The contact person phone number. In case of
questions, this person can be called by the courier.
EmailAddress O AN 50 The email address of the contact person.
MobilePhoneNumber O AN 25 The mobile phone number of the contact person.
./Address
StreetLines M AN 35 The street line should contain street name and
number of the shipper.
StreetName O AN 35
Recipient street name should be sent as separate
attribute if feasible.
StreetNumber O AN 15
Recipient street number should be sent as separate
attribute, if feasible.
StreetLines2 O AN 35 Recipient additional address information
StreetLines3 O AN 35 Recipient additional address information
City M AN 35 Recipient city name
StateOrProvinceCode O AN 2 2 Letter state code for the USA only
PostalCode M AN 12 Recipient postal code
CountryCode M AN 2 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 O N/A Insurance values of the package.
Weight M 15.3 D The weight of the package.
UseOwnPieceIdentific
ationNumber O
“Y”,”
N”
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.
In addition this special function needs to be enabled
for your username by your DHL Express IT
Consultant.
PieceIdentificationNu
mber O AN35
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.
If you wish to use this function then the above tag
UseOwnPieceIdentificationNumber needs to be set
as Y
PackageContentDescr
iption O AN70
This optional field allows you to provide the content
description on a piece level instead of Shipment
level.
./Dimensions
Length M 5.1 D
>=0.5
Length of the piece listed.
Width M
5.1 D
>=0.5 Width of the piece listed.
Height M
5.1 D
>=0.5 Height of the piece listed.
CustomerReferences M
AN 1-
35 Customer Reference for the piece.
./DangerousGoods
./Content
ContentId M AN 3 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)
DryIceTotalNetWeight C AN 1-7
This is a numeric string with up to 7 char (i.e.
1000,00 or 1000.00)
PAGE 46 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
UNCode C AN
Comma separated UN codes – eg. “UN-
7843268473”, “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
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 have both code and message.
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 Comments
ShipmentResponse
./Notification
@code M N 6 Error > 0 or Success Code = 0
Message M
Response Message, see Error
codes for more details
./PackagesResult
./PackageResult
"@number" O Integer
Running number of the
packages.
TrackingNumber O AN 35
This field contains a unique
number for the individual
package.
./LabelImage
LabelImageFormat O AN 3
Mapped from Request
Document. Currently always
“PDF”
GraphicImage O 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 O Base64 Binary Not used
ShipmentIdentificationNumber O 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.
DispatchConfirmationNumber O 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 value which was in the original
ShipmentResponse for DispatchConfirmationNumber.
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
ShipmentDeleteRequest fields
Mandatory
/Optional
Value
constraints Comments
DeleteRequest
PickupDate M
YYYY-MM-
DD
The scheduled pickup date of
the shipment to be deleted.
PickupCountry M AN 2
The country code associated to
the origin of the shipment.
DispatchConfirmationNumber M AN 20
The confirmation number
returned from the original
shipment request.
RequestorName M AN 45 The delete requestor name
Reason O AN 50
Optional reason code (see
above table)
./ClientDetail
sso O This field is for internal use only
plant O 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 M Error > 0 or Success Code = 0
message M
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.
• LAST_CHECK_POINT_ONLY
• ALL_CHECK_POINTS
7.2.4 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.
• B = Both Piece and Shipment Details (recommended value)
• S = Shipment Details Only
• P = Piece Details Only.
7.2.5 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
MessageTime M Date
The format of the should be YYYY-
MM-DD(T)hh:mm:ss-Time Zone
e.g.
2010-11-24T00:17:20Z
2010-11-24T00:17:20-07:00
MessageReference M AN 32
Message reference, between 28-32
characters in length.
./AWBNumber
ArrayOfAWBNumberItem M AN 11 DHL Waybill number
./LPNumber
ArrayOfTrackingPieceIDItem O AN 35 DHL Piece ID (future use, not active)
LevelOfDetails M Enumerated
Checkpoint Detail Indicator
ALL_CHECK_POINTS
LAST_CHECK_POINT_ONLY
PiecesEnabled O Enumerated
Pieces Indicator
B = Both Piece and Shipment
S = Shipment Details Only
P = Piece Details Only.
EstimatedDeliveryDateEnabled O Enumerated
Possible values:
- 1, EDD requested
- 0, EDD not requested
(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
• AWBNumber
• Status
• ShipmentInfo
• Pieces
7.4.3 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
TrackingResponse
Mandatory
/Optional
Value
constraints Comments
./Response
./ServiceHeader
MessageTime M Date
The format of the should be YYYY-
MM-DD(T)hh:mm:ssZ (GMT
e.g 2011-01-12T18:41:12Z
MessageReference M AN 32
The unique message reference for
this response.
./AWBInfo
./ArrayOfAWBInfoItem
AWBNumber M AN 11
Identifies the piece number as a
counter, same as input.
./Status
ActionStatus M AN 20
The summary status of the request.
Values include;
“Success”
“No Shipments Found”
./Condition/ArrayOfConditionItem
ConditionCode O N 3
Error Code associated to the request
e.g. 101
ConditionData O AN 50 Error Description
/ShipmentInfo
/OriginServiceArea
ServiceAreaCode O AN 3
The DHL Service Area Code for the
origin of the Shipment
Description O AN 40
The description of the Service Area
Code.
PAGE 64 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
OutboundSortCode O AN 4
Outbound Sort Code of Origin
(currently not available)
/DestinationServiceArea
ServiceAreaCode O AN 3
The DHL Service Area Code for the
destination of the Shipment
Description O AN 40 Description
FacilityCode O AN 3
The DHL Facility Code for the
Destination
InboundSortCode O AN 4
Inbound Sort Code of Destination
(currently not available)
ShipperName M AN 35 Shipper Name
ShipperAccountNumber O N 10
Shipper’s Account Number
(currently not populated for
tracking)
ConsigneeName M N 35 Receiver’s Name
ShipmentDate M Date
The shipment initiation date, local to
origin
YYYY-MM-DD(T)HH:MM:SS+GMT
2010-11-09T14:30:00+01:00
Pieces O N 6 Number of pieces in shipment
Weight O AN 9
Weight of shipment
Format 99999.999
WeightUnit O AN 1
L = Pounds
K = Kilogram
G = Grams
/ShipmentEvent/ArrayOfShipmentEventItem (1:m)
Date M Date
Local Date of Shipment Event
YYYY-MM-DD
Time M Time
Local Time of Shipment Event
HH:MM:SS
ServiceEvent
PAGE 65 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
EventCode M AN 2
The event code for this specific
event.
Description M AN 50 The description of the event
Signatory O AN 20
The signee for the shipment, only
occurs for final disposition events
(such as OK event)
ServiceArea
ServiceAreaCode O AN 3
The DHL Service Area Code for the
event
Description O AN 40
The description of the service area
code.
/ShipperReference (currently not used)
ReferenceID O AN 35 Reference ID for shipment
ReferenceType O AN 2 Reference Type
EstimatedDeliveryDate O Date
Estimted delivery date (EDD)
YYYY-MM-DD(T)HH:MM:SS+GMT
2010-11-09T14:30:00+01:00
/Pieces/PieceInfo/ArrayOfPieceInfo
PieceDetails
AWBNumber M AN 11
Airbill associated to the Piece (same
as
the parent node airbill)
LicensePlate M AN 35 Piece ID associated to the Piece
PieceNumber O N 6 Number of the Piece
ActualDepth O AN 9
Actual Depth of shipment
Format 99999.999
ActualWidth O AN 9
Actual Width of shipment
Format 99999.999
ActualHeight O AN 9
Actual Height of shipment
Format 99999.999
ActualWeight O AN 9 Actual Weight of shipment
PAGE 66 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
Format 99999.999
Depth O AN 9
Depth of shipment
Format 99999.999
Width O AN 9
Width of shipment
Format 99999.999
Height O AN 9
Height of shipment
Format 99999.999
Weight O AN 9
Weight of shipment
Format 99999.999
PackageType O AN 3 Package Type of Shipment
DimWeight O AN 9
Volumetric Weight of shipment
Format 99999.999
WeightUnit O AN 1
L = Pounds
K = Kilogram
G = Grams
PieceContents O AN 20 Contents or description of the piece
/PieceEvent/ArrayOfPieceEventItem (1:m)
Date M Date
Local Date of Piece Event
YYYY-MM-DD
Time M Time
Local Time of Shipment Event
HH:MM:SS
ServiceEvent
EventCode M AN 2
The event code for this specific
event.
Description M AN 50 The description of the event
Signatory O AN 20
The signee for the piece, only occurs
for final disposition events (such as
OK event)
ServiceArea
ServiceAreaCode O AN 3
The DHL Service Area Code for the
event
PAGE 67 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
Description O AN 40
The description of the service area
code.
/ShipperReference (currently not used)
ReferenceID O AN 35 Reference ID for shipment
ReferenceType O 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-table-
summary: 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 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 O AN 30 Request Id
@Ver O AN 7 Use always this value: 1.038
@Dtm O DateTime Format: 2013-04-07T23:59:59
@CorrId O AN 20
Correlation ID. This field is only used in
the response. No need to send in the
request.
./Sndr
@AppCd M AN 5 Value: DCGAP
@AppNm O AN 20 Value: DCGAP
@CmptNm O AN 256 Your own unique system name
./Rcp This section is not used in the request, only in the response.
./Bd
./Ship(1:M)
@Id M AN 35 Shipment Id (AWB)
./ShpTr(0:M)
@PuDtm O
DateTime
Pickup Date-Time:
We recommend not
to enter the pick up date. However,
the format of the pickup date is 2012-
01-31T00:00:00.
./SCDtl():M)
@AccNo O
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).
PAGE 80 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
@CRlTyCd O AN 2
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.
The possible codes are PY=Payer, RV
=Receiver, SP=Shipper – You only
need to specify this field if you are
requesting a detailed ePOD
@CtryCd O AN 2
Country code: this is optio
nal for ePOD
retrieval. This is the origin country
code..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)
./ShpInDoc(1:M)
./SDoc(1:M)
@DocTyCd M AN3
Document type code: identifies
uniquely a document type. Value =
POD (electronic proof of delivery)
./GenrcRq(0:M)
@ TyCd O 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.
PAGE 81 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
"LANGUAGE" – Optional. Language
code.
@Val O 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 / epod-
summary: Summary ePOD in letter
format. c. epod-table-detail / epod-
table-esig / epod-table: Detailed ePOD
in table format. d. epod-table-
summary: 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: <FldId
FldXPth="/ns:MSG/Bd/Shp/ShpInDoc/Sdoc@DocTyCd"/>
8.4.50 FldErr Output: ErrMsgDtl
ErrMsgDtl returns the field Dsc with the description of the missing field, for example: <ErrMsgDtl
Dsc="DocTyCd is not set"/>
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 M AN 30 Response Id
@Ver M AN 7
Version of the response schema used:
e.g.: 1.038
@Dtm M DateTime
Date-time when the response was
created. Format: 2013-04-07T23:59:59
./Sndr
@AppCd M AN 5 Value: ESB
@AppNm O AN 20 Possible values ESB
@CmptNm O AN 256 This field is not returned.
./Bd
./Ship(1:M)
@Id M 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 O DateTime Pickup Date-Time (Not returned)
./SCDtl():M)
@AccNo O 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).
(NOT RETURNED)
@CRlTyCd O 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 O 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-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) (NOT
RETURNED)
./ShpInDoc(1:M)
./SDoc(1:M)
@DocTyCd M
AN 3 Document type code: Value returned:
POD (electronic proof of delivery)
./Img (0:M)
@Img O Base64Binary Base64 encoded image
./DatTrErr(0:M)
./OrgHdr(0:1)
@Id M AN 20
Unique identifier of the response. In this
case the field is returned with an empty
value
@Ver M AN 7
Version schema format. Service returns
null value in this field.
@Dtm M 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 M AN 5 This field is not returned.
@AppNm O AN 20 This field is not returned.
@CmptNm O AN 256 This field is not returned.
./Rp(0:1)
@AppCd M AN 5
The service returns a null value in this
field.
@AppNm O AN 20 The service does not return this field.
@CmptNm O AN 256
The service returns value
“DocumentManagement.ShipmentDocu
mentRetrieveProvider”
./ErrMsgGI(0:1) Only 3 fields from this section sometimes are returned
PAGE 99 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
@Ty O AN 20 Error message type identifier: e.g.:CF
@Pri O NUMBER Priority:e.g.:2
@Sev O NUMBER Severity: e.g.: 10
./TfErrMsg(0:M)
./ ErrMsgDtl(0:1)
@ MsgCIgd O AN 128
Error message identifier. For example:
100000
@ MsgClg O AN 128
The message name regarding the
identifier MsgClgd. For example: IPESB
@Dsc O AN 128 The error message description.
@ DtlDsc O AN 128
Additional details about the error
message.
./ DatErrMsg (0:M)
./ ErrMsgDtl(0:1)
@ MsgCIgd O AN 128
Error message identifier. For example:
100000
@ MsgClg O AN 128
The message name regarding the
identifier MsgClgd. For example: IPESB
@Dsc O AN 128 The error message description.
@ DtlDsc O AN 128
Additional details about the error
message.
./ BOErr (0:1)
./FldErr(0:M)
./FldId(0:1)
@ FldXPth O AN 512
This structure returns FldXPth with the
Xpath of the field that is missing, for
example: <FldId
FldXPth="/ns:MSG/Bd/Shp/ShpInDoc/Sd
oc@DocTyCd"/>
./ ErrMsgDtl(0:1)
@ Dsc O AN 128
ErrMsgDtl returns the field Dsc with the
description of the missing field, for
example: <ErrMsgDtl Dsc="DocTyCd is
not set"/>
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
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 Weight and Dimensions fields represent the weight and dims of the individual pieces.
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 O This field is for internal use only
plant O This field is for internal use only
./UpdatedShipment
OriginalShipDate M YYYY-mm-dd
Has to match with
ShipmentTimestamp from
createShipment (only the date
part)
Example (2017-11-15)
./ShipmentInfo
ServiceType M AN 1
The shipping product requested
for this shipment, corresponding
to the DHL Global Product codes.
Account M/O AN 9
The customer account to be used
as payer in the request. If the
<Account> tag is used then there
is no need to populate the Billing
section further down below in this
table as the <Account> tag will
override any other accounts
entered.
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
ShipmentIdentificationNumber M N
Please provide the Shipment
Identification Number (Waybill) of
the shipment you wish to update.
LabelType O AN 3
Possible values:
- PDF
- ZPL
PAGE 104 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
- EPL
- LP2
LabelTemplate O 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.
ArchiveLabelTemplate O 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.
IncludePreviousPieceLabels
M AN1
Y or 1= All previously
pieces/packages will be included
when the label image is returned
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
ShipperAccountNumber M/O AN 9
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 <Account> tag is not
needed.
<ShipperAccountNumber> is
mandatory then.
Please note if you did declare the
<Account> section above then the
account number within will
overwrite the entire Billing section.
ShippingPaymentType M/O AN 1
Possible values:
- 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
<BillingAccountNumber> is
also mandatory
BillingAccountNumber O AN 9
The DHL account number used for
the shipment, if
ShippingPaymentType is equal to
R or T.
./Packages (1:1)
./RequestedPackages (1:M)
@number M Integer Running number of the packages.
Weight M 15.3 D The weight of the package.
UseOwnPieceIdentificationNumb
er
O “Y”,”N”
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.
In addition this special function
needs to be enabled for your
username by your DHL Express IT
Consultant.
PieceIdentificationNumber
O AN35
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.
If you wish to use this function
then the above tag
UseOwnPieceIdentificationNumber
needs to be set as Y or 1
PackageContentDescription
O 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 M 5.1 D >=0.5 Length of the piece listed.
Width M 5.1 D >=0.5 Width of the piece listed.
Height M 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
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 have both code and message.
PAGE 108 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
9.4.3 updateShipmentResponse 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.
9.4.4 updateShipmentResponse 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.
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 Comments
UpdateShipmentResponse
./Notification
@code M N 6 Error > 0 or Success Code = 0
Message M
Response Message, see Error
codes for more details
./PackagesResult
./PackageResult
"@number" O Integer
Running number of the
packages.
TrackingNumber O AN 35
This field contains a unique
number for the individual
package.
./LabelImage
LabelImageFormat O AN 3
Mapped from Request
Document. Currently always
“PDF”
GraphicImage O 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 O Base64 Binary Not used
ShipmentIdentificationNumber O 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 O This field is for internal use only
plant O This field is for internal use only
./PickUpShipment
PickupTimestamp M AN29
Identifies the date and time the
package is tendered.
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-MM-
DD; 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).
PickupLocationCloseTime O 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 i
n local time. The
value component must be HH:MM
(using a 24-
hours clock format,
e.g. 14:00).
SpecialPickupInstruction O AN75
any special instructions you wish
to send to the courier for the
order pick-up
PickupLocation O AN40
where the package should be
picked up by DHL courier
./ShipmentInfo
ServiceType M AN 1
The shipping product requested
for this shipment, corresponding
to the DHL Global Product codes.
UnitOfMeasurement M “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
ShipperAccountNumber M/O AN 9
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 <Account> tag is not
needed.
<ShipperAccountNumber> is
mandatory then.
Please note if you did declare the
<Account> section above then the
account number within will
overwrite the entire Billing section.
ShippingPaymentType M/O AN 1
Possible values:
- 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
<BillingAccountNumber> is
also mandatory
BillingAccountNumber O AN 9
The DHL account number used for
the shipment, if
ShippingPaymentType is equal to
R or T.
./InternationalDetail
./Commodities
NumberOfPieces O N6
The number of pieces in the
shipment
Description M AN 1-35
The description of the content of
the shipment.
PAGE 117 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
./Ship
./Shipper
./Contact
PersonName M AN 45
A contact name of a person who
will ship the shipment.
CompanyName M AN 35
The company name the person is
working in.
PhoneNumber M AN 25
The contact person phone
number. In case of questions, this
person can be called by the
courier.
EmailAddress O AN 50
The email address of the contact
person.
MobilePhoneNumber O AN 25
The mobile phone number of the
contact person.
./Address
StreetLines M AN 35
The street line should contain
street name and number of the
shipper.
StreetName O AN 35
Shipper street name should be
sent as separate attribute if
feasible.
StreetNumber O AN 15
Shipper street number should be
sent as separate attribute, if
feasible.
StreetLines2 O AN 35
Shipper additional address
information
StreetLines3 O AN 35
Shipper additional address
information
City M AN 35 Shipper city name
StateOrProvinceCode O AN 2
2 Letter state code for the USA
only
PostalCode M AN 12 Shipper postal code
CountryCode M AN 2
ISO 2 character codes of the
Shipper country.
./Pickup (0:1)
./Contact
PersonName M AN 45
A contact person of the pickup
location.
PAGE 118 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
CompanyName M AN 35
The company name the person is
working in.
PhoneNumber M AN 25
The contact person phone
number. In case of questions, this
person can be called by the
courier.
EmailAddress O AN 50
The email address of the contact
person.
MobilePhoneNumber O AN 25
The mobile phone number of the
contact person.
./Address
StreetLines M AN 35
The street line should contain
street name and number of the
pickup location.
StreetName O AN 35
Pickup street name should be sent
as separate attribute if feasible.
StreetNumber O AN 15
Pickup street number should be
sent as separate attribute, if
feasible.
StreetLines2 O AN 35
Pickup additional address
information
StreetLines3 O AN 35
Pickup additional address
information
City M AN 35 Pickup city name
StateOrProvinceCode O AN 2
2 Letter state code for the USA
only
PostalCode M AN 12 Pickup postal code
CountryCode M AN 2
ISO 2 character codes of the
Pickup country.
./BookingRequestor (0:1)
./Contact
PersonName M AN 45
A contact person of the pickup
location.
CompanyName M AN 35
The company name the person is
working in.
PhoneNumber M AN 25
The contact person phone
number. In case of questions, this
person can be called by the
courier.
EmailAddress O AN 50
The email address of the contact
PAGE 119 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
person.
MobilePhoneNumber O AN 25
The mobile phone number of the
contact person.
./Address
StreetLines M AN 35
The street line should contain
street name and number of the
pickup location.
StreetName O AN 35
Pickup street name should be sent
as separate attribute if feasible.
StreetNumber O AN 15
Pickup street number should be
sent as separate attribute, if
feasible.
StreetLines2 O AN 35
Pickup additional address
information
StreetLines3 O AN 35
Pickup additional address
information
City M AN 35 Pickup city name
StateOrProvinceCode O AN 2
2 Letter state code for the USA
only
PostalCode M AN 12 Pickup postal code
CountryCode M AN 2
ISO 2 character codes of the
Pickup country.
./Recipient
./Contact
PersonName M AN 45
A contact name of a person who
will receive the shipment.
CompanyName M AN 35
The company name the person is
working in.
PhoneNumber M AN 25
The contact person phone
number. In case of questions, this
person can be called by the
courier.
EmailAddress O AN 50
The email address of the contact
person.
MobilePhoneNumber O AN 25
The mobile phone number of the
contact person.
./Address
StreetLines M AN 35 The street line should contain
street name and number of the
PAGE 120 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
reveiver.
StreetName O AN 35
Recipient street name should be
sent as separate attribute if
feasible.
StreetNumber O AN 15
Recipient street number should be
sent as separate attribute, if
feasible.
StreetLines2 O AN 35
Recipient additional address
information
StreetLines3 O AN 35
Recipient additional address
information
City M AN 35 Recipient city name
StateOrProvinceCode O AN 2
2 Letter state code for the USA
only
PostalCode M AN 12 Recipient postal code
CountryCode M AN 2
ISO 2 character codes of the
Receiver country.
./Packages (1:1)
./RequestedPackages (1:M)
@number M Integer Running number of the packages.
Weight M 15.3 D The weight of the package.
CustomerReferences M AN35 Customer Reference for the piece.
./Dimensions
Length M 5.1 D >=0.5 Length of the piece listed.
Width M 5.1 D >=0.5 Width of the piece listed.
Height M 5.1 D >=0.5 Height of the piece listed.
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
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 have both code and message.
10.4.3 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 122 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
10.5 REQUEST PICKUP RESPONSE – OUTPUT FIELD LIST
Request Pickup Response xml
fields (Source)
Mandatory/
Optional
Values or
Constraints Comments
RequestPickUpResponse
./Notification
@code M N 6 Error > 0 or Success Code = 0
Message M
Response Message, see Error
codes for more details
DispatchConfirmationNumber O 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
on your search criteria. Condition met if no
products are available for
that pickup date/time.
1001
The requested product(s) not available based
on your search criteria. Condition met if no
products are available for
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 non-
postal 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
please check the destination city name. Condition met for non-
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 "6000-
Unexpected 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:
<country specific post code format>
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. C
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 Notes (if applicable)
40050
1
Route Code not found for <address> 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
2
The Dangerous Goods Content ID requested
is invalid. Please update and try again
10000
2
The Dry Ice Net Weight is missing in the
request for the Dangerous Goods Content
ID: 901. Please update and try again.
10000
2
The UN code is missing in the request for the
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
1
Failure during booking
40020
2
Missing field(s)",
40020
3
Error occurred while creating GNS521 file
40020
4
Error while uploading manifest file to FTP
server
40020
5
Error while transforming result to XML
PAGE 130 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
41140
2
ShipmentManifest consumer timed out.
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
8
Booking adapter error response failure
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 <location>.
Sufficient notice not provided. No pickup
scheduled
Booking adapter error response failure
PU012, Ready by time is past the station
ready by cutoff of <x>. 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 <x>. No pickup
scheduled.
Booking adapter error response failure
PU012, Ready by time is past the station
ready by cutoff of <x>. 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 Notes (if applicable)
998
Process failure occurred. Process ID
associated for that transaction (9999999) 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
0
Service operation execution finished
successfully
10000
2
Service operation request message data
validation failed HP Global Imaging epod
Service returned error
code:No matching ePODs
for search query
10001
0
When requesting ePod details account
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
<RateRequest>
<ClientDetail>
</ClientDetail>
<RequestedShipment>
<DropOffType>REQUEST_COURIER</DropOffType>
<Ship>
<Shipper>
<StreetLines>1-16-24, Minami-gyotoku</StreetLines>
<City>Ichikawa-shi, Chiba</City>
<PostalCode>272-0138</PostalCode>
<CountryCode>JP</CountryCode>
</Shipper>
<Recipient>
<StreetLines>63 RENMIN LU, QINGDAO SHI</StreetLines>
<City>QINGDAO SHI</City>
<PostalCode>266033</PostalCode>
<CountryCode>CN</CountryCode>
</Recipient>
</Ship>
<Packages>
<RequestedPackages number="1">
<Weight>
<Value>2.0</Value>
</Weight>
<Dimensions>
<Length>13</Length>
<Width>12</Width>
<Height>9</Height>
</Dimensions>
</RequestedPackages>
</Packages>
<ShipTimestamp>2010-11-26T12:00:00GMT-06:00</ShipTimestamp>
<UnitOfMeasurement>SU</UnitOfMeasurement>
<Content>NON_DOCUMENTS</Content>
<DeclaredValue>0000000200</DeclaredValue>
<DeclaredValueCurrecyCode>USD</DeclaredValueCurrecyCode>
<PaymentInfo>DDP</PaymentInfo>
<Account> XXXXXXXXX</Account>
</RequestedShipment>
</RateRequest>
PAGE 134 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
SOAP RATEREQUEST: SAMPLE OUTPUT
SOAP RATEREQUEST: REQUEST WITH ERROR
<rateresp:RateResponse>
<Provider code="DHL">
<Notification code="0">
<Message/>
</Notification>
<Service type="8">
<TotalNet>
<Currency>JPY</Currency>
<Amount>20475.00</Amount>
</TotalNet>
<Charges>
<Currency>JPY</Currency>
<Charge>
<ChargeType>EXPRESS EASY</ChargeType>
<ChargeAmount>17500.00</ChargeAmount>
</Charge>
<Charge>
<ChargeType>FUEL SURCHARGE</ChargeType>
<ChargeAmount>2975.00</ChargeAmount>
</Charge>
</Charges>
<DeliveryTime>2010-12-02T23:59:00</DeliveryTime>
</Service>
<Service type="P">
<TotalNet>
<Currency>JPY</Currency>
<Amount>20569.00</Amount>
</TotalNet>
<Charges>
<Currency>JPY</Currency>
<Charge>
<ChargeType>EXPRESS WORLDWIDE</ChargeType>
<ChargeAmount>17580.00</ChargeAmount>
</Charge>
<Charge>
<ChargeType>FUEL SURCHARGE</ChargeType>
<ChargeAmount>2989.00</ChargeAmount>
</Charge>
</Charges>
<DeliveryTime>2010-12-02T23:59:00</DeliveryTime>
</Service>
</Provider>
</rateresp:RateResponse>
<rateresp:RateResponse>
<Provider code="DHL">
<Notification code="1003">
<Message>Pick-up service is not provided on this day.</Message>
</Notification>
</Provider>
</rateresp:RateResponse>
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
<?xml version="1.0" encoding="UTF-8"?>
<ShipmentRequest xsi:noNamespaceSchemaLocation=
"ShipmentMsgRequest.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<shipreq:ShipmentRequest>
<RequestedShipment>
<ShipmentInfo>
<DropOffType>REQUEST_COURIER</DropOffType>
<ServiceType>U</ServiceType>
<Account> XXXXXXXXX</Account>
<Currency>EUR</Currency>
<UnitOfMeasurement>SI</UnitOfMeasurement>
<PackagesCount>1</PackagesCount>
<LabelType>PDF</LabelType>
<LabelTemplate>ECOM26_84_001</LabelTemplate>
</ShipmentInfo>
<ShipTimestamp>2010-10-29T09:30:47GMT+01:00</ShipTimestamp>
<PickupLocationCloseTime>16:12</PickupLocationCloseTime>
<SpecialPickupInstruction>fragile items</SpecialPickupInstruction>
<PickupLocation>west wing 3rd Floor</PickupLocation>
<PaymentInfo>DDP</PaymentInfo>
<InternationalDetail>
<Commodities>
<NumberOfPieces>1</NumberOfPieces>
<Description>ppps sd</Description>
<CountryOfManufacture>CZ</CountryOfManufacture>
<Quantity>1</Quantity>
<UnitPrice>10</UnitPrice>
<CustomsValue>1</CustomsValue>
</Commodities>
<Content>NON_DOCUMENTS</Content>
</InternationalDetail>
<Ship>
<Shipper>
<Contact>
<PersonName>John Smith</PersonName>
<CompanyName>DHL</CompanyName>
<PhoneNumber>003932423423</PhoneNumber>
<EmailAddress>John.Smith@dhl.com</EmailAddress>
</Contact>
<Address>
<StreetLines>V Parku 2308/10</StreetLines>
<City>Prague</City>
<PostalCode>14800</PostalCode>
<CountryCode>CZ</CountryCode>
</Address>
</Shipper>
<Recipient>
<Contact>
<PersonName>Jane Smith</PersonName>
<CompanyName>Deutsche Post DHL</CompanyName>
<PhoneNumber>004922832432423</PhoneNumber>
<EmailAddress>Jane.Smith@dhl.de</EmailAddress>
</Contact>
<Address>
<StreetLines>Via Felice Matteucci 2</StreetLines>
<City>Firenze</City>
<PostalCode>50127</PostalCode>
<CountryCode>IT</CountryCode>
</Address>
</Recipient>
</Ship>
<Packages>
<RequestedPackages number="1">
<InsuredValue>10</InsuredValue>
<Weight>9.0</Weight>
<Dimensions>
<Length>46</Length>
<Width>34</Width>
<Height>31</Height>
</Dimensions>
<CustomerReferences>TEST CZ-IT</CustomerReferences>
</RequestedPackages>
</Packages>
</RequestedShipment>
</shipreq:ShipmentRequest>
PAGE 139 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
SOAP SHIPMENTREQUEST: SAMPLE OUTPUT
SOAP SHIPMENTREQUEST: SAMPLE REQUEST WITH ERROR
<ShipmentResponse xmlns:shipresp="http://scxgxtt.phx-dc.dhl.com/euExpressRateBook/ShipmentMsgResponse">
<Notification code="0">
<Message/>
</Notification>
<PackagesResult>
<PackageResult number="1">
<TrackingNumber>JD012038742880009933</TrackingNumber>
</PackageResult>
</PackagesResult>
<LabelImage>
<LabelImageFormat>PDF</LabelImageFormat>
<GraphicImage>JVBERi0xLjQKJe…GraphicImage>
</LabelImage>
<ShipmentIdentificationNumber>2324866051</ShipmentIdentificationNumber>
<DispatchConfirmationNumber>
PRG999126012345</DispatchConfirmationNumber>
</ShipmentResponse>
<ShipmentResponse xmlns:shipresp="http://scxgxtt.phx-dc.dhl.com/euExpressRateBook/ShipmentMsgResponse">
<Notification code="1001">
<Message>The requested product(s) (X) not available based on your search criteria.(8614)</Message>
</Notification>
<Notification code="998">
<Message>Process failure occurred. Process ID associated for that transaction (8614)</Message>
</Notification>
</ShipmentResponse>
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
REST SHIPMENTREQUEST: SAMPLE REQUEST WITH ERROR
{
"ShipmentResponse":{
"Notification":{
"@code":"0",
"Message":null
},
"PackagesResult":{
"PackageResult":[
{
"@number":"1",
"TrackingNumber":"JD012959120890065400"
},
{
"@number":"2",
"TrackingNumber":"JD012959120890065401"
}
]
},
"LabelImage":{
"LabelImageFormat":"PDF",
"GraphicImage":"JVBERi0....."
},
"ShipmentIdentificationNumber":1117120421
}
}
{
"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
SOAP SHIPMENTDELETEREQUEST: SAMPLE OUTPUT
SOAP SHIPMENTDELETEREQUEST: SAMPLE REQUEST WITH ERROR
REST SHIPMENTDELETEREQUEST: SAMPLE INPUT
<?xml version="1.0" encoding="UTF-8"?>
<del:DeleteRequest>
<PickupDate>2010-12-03</PickupDate>
<PickupCountry>IT</PickupCountry>
<DispatchConfirmationNumber> PRG999126012345</DispatchConfirmationNumber>
<RequestorName>Tom Jones</RequestorName>
<Reason>001</Reason>
</del:DeleteRequest>
<?xml version="1.0" encoding="UTF-8"?>
<delresp:Dele
teResponse>
<Notification code="0">
<Message>Successfully cancelled</Message>
</Notification>
</delresp:DeleteResponse>
<?xml version="1.0" encoding="UTF-8"?>
<delresp:DeleteResponse>
<Notification code="410928">
<Message>Cancellation of booking was not successful. Requested Pickup was not found.</Message>
</Notification>
</delresp:DeleteResponse>
{
"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
REST SHIPMENTDELETEREQUEST: SAMPLE REQUEST WITH ERROR
{
"DeleteResponse":{
"Notification":{
"@code":"0",
"Message":"Successfully cancelled"
}
}
}
{
"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
<trackShipmentRequest>
<trackingRequest>
<TrackingRequest>
<Request>
<ServiceHeader>
<MessageTime>2010-11-24T00:17:20Z</MessageTime>
<MessageReference>1234</MessageReference>
</ServiceHeader>
</Request>
<AWBNumber>
<ArrayOfAWBNumberItem>2330982222</ArrayOfAWBNumberItem>
</AWBNumber>
<LevelOfDetails>ALL_CHECK_POINTS</LevelOfDetails>
<PiecesEnabled>B</PiecesEnabled>
</TrackingRequest>
</trackingRequest>
</trackShipmentRequest>
PAGE 145 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
SOAP TRACKINGREQUEST: SAMPLE OUTPUT
<trackingResponse xmlns:ns="http://www.dhl.com">
<TrackingResponse>
<Response>
<ServiceHeader>
<MessageTime>2011-01-12T18:41:12Z</MessageTime>
<MessageReference>86ef86501e7b11e08c81df5507f6bac8</MessageReference>
</ServiceHeader>
</Response>
<AWBInfo>
<ArrayOfAWBInfoItem>
<AWBNumber>2331017371</AWBNumber>
<Status>
<ActionStatus>Success</ActionStatus>
</Status>
<ShipmentInfo>
<OriginServiceArea>
<ServiceAreaCode>FLR</ServiceAreaCode>
<Description>Florence - Italy</Description>
</OriginServiceArea>
<DestinationServiceArea>
<ServiceAreaCode>BRI</ServiceAreaCode>
<Description>Bari - Italy</Description>
<FacilityCode>WAD</FacilityCode>
</DestinationServiceArea>
<ShipperName>NUOVO PIGNONE SPA</ShipperName>
<ConsigneeName>NUOVO PIGNONESPA</ConsigneeName>
<ShipmentDate>2010-11-09T14:33:00+01:00</ShipmentDate>
<Pieces>1</Pieces>
<Weight>0.500</Weight>
<ShipmentEvent>
<ArrayOfShipmentEventItem>
<Date>2010-11-10</Date>
<Time>15:12:00</Time>
<ServiceEvent>
<EventCode>MD</EventCode>
<Description>Missed Delivery
Cycle</Description>
</ServiceEvent>
<Signatory/>
<ServiceArea>
<ServiceAreaCode>BRI</ServiceAreaCode>
<Description>Bari -
Italy</Description>
</ServiceArea>
</ArrayOfShipmentEventItem>
</ShipmentEvent>
</ShipmentInfo>
<Pieces>
<PieceInfo>
<ArrayOfPieceInfoItem>
<PieceDetails>
<AWBNumber>2331017371</AWBNumber>
<LicensePlate>JD012038742880020267</LicensePlate>
<ActualDepth>0.000</ActualDepth>
<ActualWidth>0.000</ActualWidth>
<ActualHeight>0.000</ActualHeight>
<Depth>1.000</Depth>
<Width>1.000</Width>
<Height>1.000</Height>
<Weight>0.500</Weight>
<PackageType/>
<DimWeight>0.520</DimWeight>
<WeightUnit>KG</WeightUnit>
</PieceDetails>
<PieceEvent>
<ArrayOfPieceEventItem>
<Date>2010-11-
11</Date>
<Time>11:52:00</Time>
<ServiceEvent>
<EventCode>OK</EventCode>
<Description>Delivery</Description>
</ServiceEvent>
<Signatory>DEPALMA</Signatory>
<ServiceArea>
<ServiceAreaCode>BRI</ServiceAreaCode>
<Description>Bari - Italy</Description>
/S i A
PAGE 146 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
SOAP TRACKINGREQUEST: SAMPLE ERROR
REST TRACKINGREQUEST: SAMPLE INPUT
<trackingResponse xmlns:ns="http://www.dhl.com">
<TrackingResponse>
<Response>
<ServiceHeader>
<MessageTime>2011-01-12T17:40:58Z</MessageTime>
<MessageReference>1d136ec01e7311e0a468e3cd6e9dbbd4</MessageReference>
</ServiceHeader>
</Response>
<AWBInfo>
<ArrayOfAWBInfoItem>
<AWBNumber>2330982222</AWBNumber>
<Status>
<ActionStatus>No Shipments Found</ActionStatus>
<Condition>
<ArrayOfConditionItem>
<ConditionCode>101</ConditionCode>
<ConditionData>No Shipments Found for AWBNumber |
2330982222</ConditionData>
</ArrayOfConditionItem>
</Condition>
</Status>
</ArrayOfAWBInfoItem>
</AWBInfo>
</TrackingResponse>
</trackingResponse>
{
"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
<doc:shipmentDocumentRetrieveReq>
<MSG>
<Hdr Id="123testrq" Ver="1.038" Dtm="2011-04-07T23:59:59">
<Sndr AppNm="DCG" AppCd="DCG"/>
</Hdr>
<Bd>
<Shp Id="2638825350">
<ShpTr>
<!--Zero or more repetitions:-->
<SCDtl AccNo="000000000" CRlTyCd="TC"/>
</ShpTr>
<ShpInDoc>
<SDoc DocTyCd="POD"/>
</ShpInDoc>
</Shp>
<GenrcRq>
<GenrcRqCritr TyCd="IMG_CONTENT" Val="epod-detail-esig"/>
<GenrcRqCritr TyCd="IMG_FORMAT" Val="PDF"/>
<GenrcRqCritr TyCd="DOC_RND_REQ" Val="true"/>
<GenrcRqCritr TyCd="EXT_REQ" Val="true"/>
<GenrcRqCritr TyCd="DUPL_HANDL" Val="CORE_WB_NO"/>
<GenrcRqCritr TyCd="SORT_BY" Val="$INGEST_DATE,D"/>
<GenrcRqCritr TyCd="LANGUAGE" Val="en"/>
</GenrcRq>
</Bd>
</MSG>
</doc:shipmentDocumentRetrieveReq>
PAGE 150 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
SOAP EPOD: SAMPLE OUTPUT
SOAP EPOD: SAMPLE ERROR RESPONSE
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema
-instance">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<tns:shipmentDocumentRetrieveResp xmlns:tns="glDHLExpressePOD/providers/DocumentRetrieve">
<MSG>
<Hdr Id="73475768" Ver="1.038" Dtm="2013-05-24T20:34:34">
<Sndr AppCd="ESB" AppNm="ESB"/>
<Rcp AppCd="DCG" AppNm="DCG">
<GId Id="SunnyTesting" IdTp="RQMSGID"/>
</Rcp>
</Hdr>
<Bd>
<Shp>
<ShpInDoc>
<SDoc DocTyCd="POD">
<Img Img="JVBERi0xLjQKJeLjz9MKNiAwIG9.....==" ImgMimeTy="application/pdf"/>
</SDoc>
</ShpInDoc>
</Shp>
</Bd>
<DatTrErr>
<OrgHdr CorrId="SunnyTesting"/>
<Rp CmptNm="DocumentManagement.ShipmentDocumentRetrieveProvider"/>
<ErrMsgGI Ty="CF" Pri="2" Sev="10"/>
<DatErrMsg>
<ErrMsgDtl MsgCIgd="100000" MsgClg="IPESB" Dsc="Service operation execution finished successfully" DtlDsc="Service
operation execution finished successfully"/>
</DatErrMsg>
</DatTrErr>
</MSG>
</tns:shipmentDocumentRetrieveResp>
</SOAP-ENV:Body>
</SOAP
-ENV:Envelope>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-
ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/20
01/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema
-instance">
<SOAP
-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"></SOAP-ENV:Header><SOAP-ENV:Body>
<tns:shipmentDocumentRetrieveResp xmlns:tns="DocumentManagement/WSConsumer/WS/DocumentManagement">
<MSG>
<Hdr Id="72048040" Ver="1.038" Dtm="2013-05-16T13:58:09">
<Sndr AppCd="ESB" AppNm="ESB"></Sndr>
<Rcp AppCd="WEBP" AppNm="WEBP">
<GId Id="1368626289303" IdTp="RQMSGID"></GId>
</Rcp>
</Hdr>
<DatTrErr>
<OrgHdr CorrId="1368626289303"></OrgHdr>
<Rp CmptNm="DocumentManagement.ShipmentDocumentRetrieveProvider"></Rp>
<ErrMsgGI Ty="CF" Pri="2" Sev="40"></ErrMsgGI>
<DatErrMsg>
<ErrMsgDtl MsgCIgd="100002" MsgClg="IPESB" Dsc="Service operation request message data validation failed" DtlDsc="HP Global
Imaging epod Service returned error co
de:No matching ePODs fo
r search query"></ErrMsgDtl>
</DatErrMsg>
</DatTrErr>
</MSG></tns:shipmentDocumentRetrieveResp></SOAP
-ENV:Body>
</SOAP
-ENV:Envelope>
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
<?xml version="1.0" encoding="UTF-8"?>
<upd:UpdateRequest>
<MessageId>Sample_Message_Id</MessageId>
<UpdatedShipment>
<ShipmentInfo>
<ServiceType>P</ServiceType>
<Account>123456789</Account>
<Billing>
<ShipperAccountNumber>123456789</ShipperAccountNumber>
<ShippingPaymentType>S</ShippingPaymentType>
</Billing>
<ShipmentIdentificationNumber>1234567890</ShipmentIdentificationNumber>
<LabelType>PDF</LabelType>
<LabelTemplate>ECOM_TC_A4</LabelTemplate>
<ArchiveLabelTemplate>ARCH_8x4</ArchiveLabelTemplate>
<IncludePreviousPieceLabels>Y</IncludePreviousPieceLabels>
</ShipmentInfo>
<OriginalShipDate>2018-01-24</OriginalShipDate>
<Packages>
<RequestedPackages number="1">
<Weight>5.350</Weight>
<UseOwnPieceIdentificationNumber>N</UseOwnPieceIdentificationNumber>
<PackageContentDescription>Gloves</PackageContentDescription>
<Dimensions>
<Length>32.0</Length>
<Width>10.0</Width>
<Height>5.0</Height>
</Dimensions>
</RequestedPackages>
</Packages>
</UpdatedShipment>
</upd:UpdateRequest>
PAGE 155 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
SOAP UPDATESHIPMENT: SAMPLE OUTPUT
SOAP UPDATESHIPMENT: SAMPLE ERROR MESSAGE
<?xml version="1.0" encoding="UTF-8"?><updateresp:UpdateResponse xmlns:updateresp="http://scxgxtt.phx-
dc.dhl.com/euExpressRateBook/UpdateShipmentResponse">
<Notification code="400101">
<Message>Piece update is not possible as shipment information not found in the database</Message>
</Notification>
<Notification code="999">
<Message>Failed to process your request. Process ID associated for this transaction (1234567890)</Message>
</Notification>
</updateresp:UpdateResponse>
<updateresp:UpdateResponse xmlns:updateresp="http://scxgxtt.phx-dc.dhl.com/euExpressRateBook/UpdateShipmentResponse">
<Notification code="0">
<Message/>
</Notification>
<PackagesResult>
<PackageResult number="1">
<TrackingNumber>JDAA06000121212121</TrackingNumber>
</PackageResult>
</PackagesResult>
<LabelImage>
<LabelImageFormat>PDF</LabelImageFormat>
<GraphicImage>JVBERi0xLjQKJfbk/N8KMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovVmVRU9GCg==</GraphicImage>
</LabelImage>
<ShipmentIdentificationNumber>1234567890</ShipmentIdentificationNumber>
</updateresp:UpdateResponse>
PAGE 156 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
REST UPDATESHIPMENT: SAMPLE INPUT
REST UPDATESHIPMENT: SAMPLE OUTPUT
{"UpdateResponse": {
"Notification": {
"@code": "0",
"Message": null
},
"PackagesResult": {"PackageResult": {
"@number": "1",
"TrackingNumber": "JD0ASDSFSE3687493085"
}},
"LabelImage": {
"LabelImageFormat": "PDF",
"GraphicImage": "JVBERi0xLjQKJfbk/N8KMSAwIG9iago8PAovVHlwZSAvQ2F0YJUVPRgo="
},
"ShipmentIdentificationNumber": 1234567890
}}
{ "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"
}
}
}
}
}
}
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
<pic:PickUpRequest>
<MessageId>2364878234817650001982134234</MessageId>
<PickUpShipment>
<ShipmentInfo>
<ServiceType>U</ServiceType>
<Billing>
<ShipperAccountNumber>140582622</ShipperAccountNumber>
<ShippingPaymentType>S</ShippingPaymentType>
</Billing>
<UnitOfMeasurement>SI</UnitOfMeasurement>
</ShipmentInfo>
<PickupTimestamp>2018-01-26T12:59:00 GMT+01:00</PickupTimestamp>
<PickupLocationCloseTime>17:00</PickupLocationCloseTime>
<SpecialPickupInstruction>Collect at reception</SpecialPickupInstruction>
<PickupLocation>Receptoin</PickupLocation>
<InternationalDetail>
<Commodities>
<NumberOfPieces>1</NumberOfPieces>
<Description>Computer Parts</Description>
</Commodities>
</InternationalDetail>
<Ship>
<Shipper>
<Contact>
<PersonName>Topaz</PersonName>
<CompanyName>DHL Express</CompanyName>
<PhoneNumber>+31 6 53464291</PhoneNumber>
<EmailAddress>Topaz.Test@dhl.com</EmailAddress>
<MobilePhoneNumber>+31 6 53464291</MobilePhoneNumber>
</Contact>
<Address>
<StreetLines>GloWS</StreetLines>
<City>Eindhoven</City>
<PostalCode>5657 ES</PostalCode>
<CountryCode>NL</CountryCode>
</Address>
</Shipper>
<Recipient>
<Contact>
<PersonName>Jack Jones</PersonName>
<CompanyName>J and J Company</CompanyName>
<PhoneNumber>+44 25 77884444</PhoneNumber>
<EmailAddress>jack@jjcompany.com</EmailAddress>
<MobilePhoneNumber>+44 5 88648666</MobilePhoneNumber>
</Contact>
<Address>
<StreetLines>Penny lane</StreetLines>
<City>Liverpool</City>
<PostalCode>AA21 9AA</PostalCode>
<CountryCode>GB</CountryCode>
</Address>
</Recipient>
</Ship>
<Packages>
<RequestedPackages number="1">
<Weight>12.0</Weight>
<Dimensions>
<Length>70</Length>
<Width>21</Width>
<Height>44</Height>
</Dimensions>
<CustomerReferences>My-PU-Call-1</CustomerReferences>
</RequestedPackages>
</Packages>
</PickUpShipment>
</pic:PickUpRequest>
PAGE 159 OF 163
DHL EXPRESS GLOBAL WEBSERVICES – DEVELOPER GUIDE
SOAP REQUESTPICKUP: SAMPLE OUTPUT
SOAP REQUESTPICKUP: SAMPLE ERROR MESSAGE
<pickupresp:PickUpResponse xmlns:pickupresp="http://scxgxtt.phx-dc.dhl.com/euExpressRateBook/PickUpResponse">
<Notification code="998">
<Message>The account number is not found or invalid. Please check the account number and retry.</Message>
</Notification>
<Notification code="999">
<Message>Failed to process your request. Process ID associated for this transaction (1862502637)</Message>
</Notification>
</pickupresp:PickUpResponse>
<pickupresp:PickUpResponse xmlns:pickupresp="http://scxgxtt.phx-dc.dhl.com/euExpressRateBook/PickUpResponse">
<Notification code="0">
<Message/>
</Notification>
<DispatchConfirmationNumber>PRG999126012345</DispatchConfirmationNumber>
</pickupresp:PickUpResponse>
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
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)"
}
]}}
{"PickUpResponse": {
"Notification": {
"@code": "0",
"Message": null
},
"DispatchConfirmationNumber": "PRG999126012345"
}}
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

Navigation menu