Project Brief DHL Express Global Web Services Developer Guide V3.1

User Manual: Pdf

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

DHL Express Global Web Services – Developer Guide
DHL EXPRESS GLOBAL WEB SERVICES
Web Services Developer Guide
Doc. Ref. DHL Express Global Web Services –
Developer User
Guide
Version Number: 3.1
Status FINAL
Created by SUNNY ARORA [EU IT CIM Project Manager]
Date 15/08/2017
Page 1 of 104
DHL Express Global Web Services – Developer Guide
Document Control
Revision history:
Version Release
Date
Updated by Comments Status
1.0h 05/09/2012 J Penmatcha Modified XML structure to include label template in
creation service
Approved
1.0i 04/08/13 V Rodriguez Modified XML structure of Rate Request to add two
more fields
Approved
1.0j 04/15/13 S Arora Simplification of User guide with Tips and Notes and
change of UAT endpoint (Sandpit)
Approved
1.0k 13/09/13 S Arora Description around state province field added Approved
1.0L 20/11/13 S Arora Updated with Email field length Approved
1.0M 03/12/13 S Arora/ V Rodriguez Added Value Added Services for getRateRequest Approved
1.0N 08/04/14 S Arora Updated Service tag information and Account tag
information for createShipmentRequest
Approved
2.1 22/04/14 S Arora/D Hill Updated version control, added Tracking & ePOD Approved
2.2 15/07/14 S Arora Updated Non_Documents tag Approved
2.3 14/08/14 T Sukardjo Updated ShipmentRequest tags:
PickupLocationCloseTime, SpecialPickupInstruction,
PickupLocation.
Approved
2.4 09/03/15 S Arora Updated minimum dimensions Approved
2.5 29/06/15 S Arora Updated package number requirement Approved
2.6 15/12/15 S Arora New release: DG,PLT, Data Staging etc Approved
2.7 16/12/15 S Arora / D Hill Re-formatting Approved
2.8 10/05/16 S Arora Clarification on Content Approved
2.9 28/06/16 D Hill Added info on WS Security Approved
3.0 05/08/16 S Arora Aligned max number of packages to WSDL Approved
3.1 15/08/17 S Arora Aligned packagetype in tracking response to 3 char Approved
Page 2 of 104
DHL Express Global Web Services – Developer Guide
CONTENT
1. INTRODUCTION ............................................................................................................................................... 4
1.1 DHL EXPRESS GLOBAL WEB SERVICES OVERVIEW ................................................................................................. 4
1.2 REQUIREMENTS – TECHNICAL SKILLS ................................................................................................................... 4
1.3 REQUIREMENTS – BUSINESS UNDERSTANDING ....................................................................................................... 4
2. DHL EXPRESS GLOBAL WEB SERVICES OVERVIEW ....................................................................................... 5
2.1 WEB SERVICE DEFINITION LANGUAGE AND REFERENCE DOCUMENTS ......................................................................... 5
2.2 SECURITY AND AUTHENTICATION ....................................................................................................................... 6
3. WHAT WEB SERVICES OPERATIONS ARE AVAILABLE? ................................................................................ 7
4. RATEREQUEST ................................................................................................................................................. 8
4.1 RATEREQUEST - DESCRIPTION............................................................................................................................ 8
4.2 RATEREQUEST - INPUT ..................................................................................................................................... 8
4.3 RATEREQUEST – INPUT FIELD LIST ..................................................................................................................... 13
4.4 RATEREQUEST - OUTPUT ................................................................................................................................ 17
4.5 RATE RESPONSE – OUTPUT FIELD LIST ............................................................................................................... 20
5. SHIPMENTREQUEST ...................................................................................................................................... 22
5.1 SHIPMENTREQUEST - DESCRIPTION ................................................................................................................... 22
5.2 SHIPMENTREQUEST - INPUT ............................................................................................................................. 22
5.3 SHIPMENT REQUEST – INPUT FIELD LIST ............................................................................................................. 31
5.4 SHIPMENTREQUEST - OUTPUT ......................................................................................................................... 38
5.5 SHIPMENT RESPONSE – OUTPUT FIELD LIST ......................................................................................................... 40
6. SHIPMENTDELETEREQUEST .......................................................................................................................... 41
6.1 SHIPMENTDELETEREQUEST - DESCRIPTION ......................................................................................................... 41
6.2 SHIPMENTDELETEREQUEST - INPUT ................................................................................................................... 41
6.3 SHIPMENTDELETEREQUEST – INPUT FIELD LIST ..................................................................................................... 42
6.4 SHIPMENTDELETEREQUEST – OUTPUT ............................................................................................................... 43
6.5 SHIPMENTDELETEREQUEST – OUTPUT FIELD LIST ................................................................................................. 43
7. TRACKINGREQUEST ...................................................................................................................................... 44
7.1 TRACKINGREQUEST - DESCRIPTION ................................................................................................................... 44
7.2 TRACKINGREQUEST - INPUT ............................................................................................................................ 45
7.3 TRACKINGREQUEST – INPUT FIELD LIST .............................................................................................................. 46
7.4 TRACKINGRESPONSE - OUTPUT ....................................................................................................................... 47
7.5 TRACKINGRESPONSE – OUTPUT FIELD LIST ......................................................................................................... 52
8. DOCUMENTRETRIEVE - EPOD ....................................................................................................................... 56
8.1 DOCUMENTRETRIEVE-EPOD - DESCRIPTION ....................................................................................................... 56
8.2 DOCUMENTRETRIEVE-EPOD - INPUT ................................................................................................................. 56
8.3 SHIPMENTDOCUMENTRETRIEVE-EPOD – INPUT FILED LIST ..................................................................................... 66
8.4 SHIPMENTDOCUMENTRETRIEVE-EPOD – OUTPUT ............................................................................................... 69
8.5 DOCUMENTRETRIEVE-EPOD – OUTPUT FIELD LIST ............................................................................................... 83
9. APPENDIX ...................................................................................................................................................... 86
10. SERVICE INPUT/OUTPUT EXAMPLES FOR RATEREQUEST ....................................................................... 94
11. SERVICE INPUT/OUTPUT EXAMPLES FOR SHIPMENTREQUEST .............................................................. 96
12. SERVICE INPUT/OUTPUT EXAMPLES FOR SHIPMENTDELETEREQUEST .................................................. 98
13. SERVICE INPUT/OUTPUT EXAMPLES FOR TRACKINGREQUEST .............................................................. 99
14. SERVICE INPUT/OUTPUT EXAMPLES FOR EPOD .................................................................................... 102
15. HELPFUL XML AND WEB SERVICES LINKS ............................................................................................. 104
Page 3 of 104
DHL Express Global Web Services – 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 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 4 of 104
DHL Express Global Web Services – 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/sndpt/e
xpressRateBook?WSDL
WSDL
Description
TrackingRequest https://wsbexpress.dhl.com:443/sndpt/g
lDHLExpressTrack?WSDL
WSDL
Description
DocumentRetrieve (ePOD) https://wsbexpress.dhl.com:443/sndpt/g
etePOD?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 5 of 104
DHL Express Global Web Services – 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 of the SOAP protocol.
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. 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 6 of 104
DHL Express Global Web Services – 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.
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.
Reference Description Document
WSDL
Description
a) RateRequest
b) ShipmentRequest
c) ShipmentDeleteRequest
https://wsbexpress.dhl.com:443/sndpt/e
xpressRateBook?WSDL
WSDL
Description
d) TrackingRequest
https://wsbexpress.dhl.com:443/sndpt/g
lDHLExpressTrack?WSDL
WSDL
Description
e) DocumentRetrieve (ePOD)
https://wsbexpress.dhl.com:443/sndpt/g
etePOD?WSDL
Page 7 of 104
DHL Express Global Web Services – 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 8 of 104
DHL Express Global Web Services – 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 9 of 104
DHL Express Global Web Services – 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 10 of 104
DHL Express Global Web Services – 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.
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.
Page 11 of 104
DHL Express Global Web Services – Developer Guide
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).
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 12 of 104
DHL Express Global Web Services – 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
RequestValueAddedServices 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
CountryCode M
AN 2 ISO 2 character codes of the Shipper
country.
Page 13 of 104
DHL Express Global Web Services – Developer Guide
./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
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:
Page 14 of 104
DHL Express Global Web Services – Developer Guide
- 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
DeclaredValueCurrecyCode 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)
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.
Page 15 of 104
DHL Express Global Web Services – Developer Guide
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 16 of 104
DHL Express Global Web Services – Developer Guide
BR
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.
Page 17 of 104
DHL Express Global Web Services – Developer Guide
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.
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.
Page 18 of 104
DHL Express Global Web Services – Developer Guide
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
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 19 of 104
DHL Express Global Web Services – 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
shipment for the product listed.
./Charges
Currency M
This the currency for all line item
charges listed in the Charge section
Page 20 of 104
DHL Express Global Web Services – Developer Guide
./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 21 of 104
DHL Express Global Web Services – 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.
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 22 of 104
DHL Express Global Web Services – 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.
Page 23 of 104
DHL Express Global Web Services – Developer Guide
5.2.4 ShipmentRequest Input: RateRequestConfirmed
Currently not in use
5.2.5 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.
5.2.6 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.7 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.
Page 24 of 104
DHL Express Global Web Services – Developer Guide
5.2.8 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.
5.2.9 ShipmentRequest Input: ShipmentInfo Currency
The Currency field is a required field which details the currency for the Customs Value.
5.2.10 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.
Page 25 of 104
DHL Express Global Web Services – Developer Guide
5.2.11 ShipmentRequest Input: ShipmentInfo Other fields
The following fields are optional and not used for specific processing. Please note the ShipmentIdentificationNumber
field is reserved for future use to allow consumers to pass their own allocated shipment id (or airbill). The
PackagesCount field is not used. The SendPackage field is not used.
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
5.2.14 ShipmentRequest Input: ShipmentInfo PaperlessTradeEnabled
The PaperlessTradeEnabled node is an optional flag indicating if the request includes a Paperless Trade
image/document.
5.2.15 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.
Page 26 of 104
DHL Express Global Web Services – Developer Guide
5.2.16 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.17 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.18 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’.
5.2.19 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.20 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.
Page 27 of 104
DHL Express Global Web Services – Developer Guide
5.2.21 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.
5.2.22 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.
5.2.23 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>
Page 28 of 104
DHL Express Global Web Services – Developer Guide
5.2.24 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 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 29 of 104
DHL Express Global Web Services – Developer Guide
5.2.25 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.26 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 30 of 104
DHL Express Global Web Services – Developer Guide
5.3 Shipment Request – Input Field List
Shipment Request fields M/O Values or
Constraints 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.
RateRequestConfirmed O AN 1 NOT IN USE
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.
Page 31 of 104
DHL Express Global Web Services – Developer Guide
UnitOfMeasurement M AN 2
The unit of measurement for the
dimensions of the package.
Possible values:
- SI, international metric system (KG,
CM)
- SU, UK, US system of measurement
(LB, IN)
ShipmentIdentificationNumber O N/A
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.
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.
PaperlessTradeEnabled O N1 or A5
Possible values (case sensitive):
- true
- false
- 0
- 1
PaperlessTradeImage O Base64 binary
Base64 encoded image. Max size 1MB
A4
ShipTimestamp M
YYYY-MM-
DDT24HH:MM: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
Page 32 of 104
DHL Express Global Web Services – Developer Guide
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.
PickupLocationCloseTime O HH:mm
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
SpecialPickupInstruction 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
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.
Page 33 of 104
DHL Express Global Web Services – Developer Guide
./SpecialServices
./Service
ServiceType M AN 2
Please enter the Value Added 2
digit/letter Service code here (e.g. II for
Insurance). The valid Service code for
the product you wish to ship to can be
queried using RateRequest operation
first.
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.
CountryOfManufacture 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
ExportReference O AN 40
Export Reference field, appears on
label.
./Ship
./Shipper
./Contact
PersonName M AN 45
A contact name of a person who will
ship the shipment.
Page 34 of 104
DHL Express Global Web Services – 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 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 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
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.
Page 35 of 104
DHL Express Global Web Services – Developer Guide
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 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
Page 36 of 104
DHL Express Global Web Services – Developer Guide
country.
./Packages (1:1)
./RequestedPackages (1:M)
@number M Integer Running number of the packages.
InsuredValue O N/A Insurance values of the package.
Weight M 15.3 D The weight of the package.
./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)
UNCode C AN
Comma separated UN codes – eg.
“UN-7843268473”,
“7843268473,123”
Page 37 of 104
DHL Express Global Web Services – 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 38 of 104
DHL Express Global Web Services – 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 39 of 104
DHL Express Global Web Services – 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 40 of 104
DHL Express Global Web Services – 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 41 of 104
DHL Express Global Web Services – 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
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
Page 42 of 104
DHL Express Global Web Services – Developer Guide
6.4 ShipmentDeleteRequest – Output
6.5 ShipmentDeleteRequest – Output Field List
ShipmentDeleteResponse
fields
Mandatory
/Optional
Value
constraints 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 43 of 104
DHL Express Global Web Services – 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 44 of 104
DHL Express Global Web Services – 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 45 of 104
DHL Express Global Web Services – 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:
- Y, EDD requested
- N, EDD not requested
(Estimated Delivery Date is not always
returned and is subject to the scans by
the DHL Operations team)
Page 46 of 104
DHL Express Global Web Services – 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
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.
Page 47 of 104
DHL Express Global Web Services – Developer Guide
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.
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 48 of 104
DHL Express Global Web Services – 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 49 of 104
DHL Express Global Web Services – 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 50 of 104
DHL Express Global Web Services – 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 51 of 104
DHL Express Global Web Services – 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.
OutboundSortCode O AN 4
Outbound Sort Code of Origin
(currently not available)
Page 52 of 104
DHL Express Global Web Services – Developer Guide
/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
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)
Page 53 of 104
DHL Express Global Web Services – Developer Guide
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
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
Page 54 of 104
DHL Express Global Web Services – Developer Guide
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
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 55 of 104
DHL Express Global Web Services – 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 56 of 104
DHL Express Global Web Services – 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 57 of 104
DHL Express Global Web Services – 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 58 of 104
DHL Express Global Web Services – 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 59 of 104
DHL Express Global Web Services – 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 60 of 104
DHL Express Global Web Services – 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 61 of 104
DHL Express Global Web Services – 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 62 of 104
DHL Express Global Web Services – 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 63 of 104
DHL Express Global Web Services – Developer Guide
8.2.24 Bd Input: GenrcRq
The Generic Request GenrcRq) contains the type and value criteria of the request.
Page 64 of 104
DHL Express Global Web Services – 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 65 of 104
DHL Express Global Web Services – 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 66 of 104
DHL Express Global Web Services – 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 optional 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.
"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
Page 67 of 104
DHL Express Global Web Services – Developer Guide
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 68 of 104
DHL Express Global Web Services – 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 69 of 104
DHL Express Global Web Services – 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 70 of 104
DHL Express Global Web Services – 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 71 of 104
DHL Express Global Web Services – 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 72 of 104
DHL Express Global Web Services – 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 73 of 104
DHL Express Global Web Services – 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 74 of 104
DHL Express Global Web Services – 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 75 of 104
DHL Express Global Web Services – 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 76 of 104
DHL Express Global Web Services – 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”.
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.
Page 77 of 104
DHL Express Global Web Services – Developer Guide
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.
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.
Page 78 of 104
DHL Express Global Web Services – Developer Guide
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
8.4.39 ErrMsgDtl Output:Dsc
The error message description
8.4.40 ErrMsgDtl Output: DtlDsc
Additional details about the error message.
Page 79 of 104
DHL Express Global Web Services – Developer Guide
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.
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
Page 80 of 104
DHL Express Global Web Services – Developer Guide
8.4.45 ErrMsgDtl Output:Dsc
The error message description
8.4.46 ErrMsgDtl Output: DtlDsc
Additional details about the error message.
8.4.47 DatErrMsg Output:BOErr
Backend returns error messages when mandatory fields are missing. The error message will be in the section FldErr.
Page 81 of 104
DHL Express Global Web Services – Developer Guide
8.4.48 BOErr Output: FldErr
Errors related to mandatory missing fields:
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 82 of 104
DHL Express Global Web Services – Developer Guide
8.5 DocumentRetrieve-ePOD – Output Field List
Shipment Document
Retrieve fields
Mandator
y
/Optional
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)
@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
Page 83 of 104
DHL Express Global Web Services – Developer Guide
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.ShipmentDocumen
tRetrieveProvider”
./ErrMsgGI(0:1) Only 3 fields from this section sometimes are returned
@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:
Page 84 of 104
DHL Express Global Web Services – Developer Guide
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/Sdoc@
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 85 of 104
DHL Express Global Web Services – Developer Guide
9. 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.
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.
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
Page 86 of 104
DHL Express Global Web Services – Developer Guide
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.
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"
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.
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.
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 restrictions
not met
Page 87 of 104
DHL Express Global Web Services – Developer Guide
5027
Sorry the input declared value cannot exceed the
limit for this country.
5038
The combination unit of weight and dimension is
invalid.
5100
Invalid product service combination.
5110
Optional service not applicable.
6000
Unexpected application error
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)
400501
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 88 of 104
DHL Express Global Web Services – 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.
40002
Product content code is not found.
Page 89 of 104
DHL Express Global Web Services – Developer Guide
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.
100002
The Dangerous Goods Content ID requested is
invalid. Please update and try again
100002
The Dry Ice Net Weight is missing in the request
for the Dangerous Goods Content ID: 901. Please
update and try again.
100002
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)
400201
Failure during booking
400202
Missing field(s)",
400203
Error occurred while creating GNS521 file
400204
Error while uploading manifest file to FTP server
400205
Error while transforming result to XML
411402
ShipmentManifest consumer timed out.
998
Field
'ShipmentRequest/RequestedShipment/Shipment
Info/PaperlessTradeImage' is mandatory when
PaperlessTradeEnabled is set to true.
Page 90 of 104
DHL Express Global Web Services – Developer Guide
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)
410928
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 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
Page 91 of 104
DHL Express Global Web Services – Developer Guide
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 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
Page 92 of 104
DHL Express Global Web Services – Developer Guide
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)
100000
Service operation execution finished successfully
100002
Service operation request message data
validation failed HP Global Imaging epod
Service returned error
code:No matching ePODs for
search query
100010
When requesting ePod details account number
and customer role must be provided
Page 93 of 104
DHL Express Global Web Services – Developer Guide
10. Service Input/Output Examples for RateRequest
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>000000000</Account>
</RequestedShipment>
</RateRequest>
Page 94 of 104
DHL Express Global Web Services – Developer Guide
RateRequest: Sample Output
RateRequest: Request with error
<rateresp:RateResponse>
<Provider code="DHL">
<Notification code="1003">
<Message>Pick-up service is not provided on this day.</Message>
</Notification>
</Provider>
</rateresp:RateResponse>
<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>
Page 95 of 104
DHL Express Global Web Services – Developer Guide
11. Service Input/Output Examples for ShipmentRequest
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>000000000</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 96 of 104
DHL Express Global Web Services – Developer Guide
ShipmentRequest: Sample Output
ShipmentRequest: Sample request with error
<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>
<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>FLR
-150103</DispatchConfirmationNumber>
</ShipmentResponse>
Page 97 of 104
DHL Express Global Web Services – Developer Guide
12. Service Input/Output Examples for ShipmentDeleteRequest
ShipmentDeleteRequest: Sample Input
ShipmentDeleteRequest: Sample Output
ShipmentDeleteRequest: Sample request with error
<?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>
<?xml version="1.0" encoding="UTF-8"?>
<delresp:DeleteResponse>
<Notification code="0">
<Message>Successfully cancelled</Message>
</Notification>
</delresp:DeleteResponse>
<?xml version=
"1.0" encoding="UTF-8"?>
<del:DeleteRequest>
<PickupDate>2010-12-03</PickupDate>
<PickupCountry>IT</PickupCountry>
<DispatchConfirmationNumber>FLR-804</DispatchConfirmationNumber>
<RequestorName>Tom Jones</RequestorName>
<Reason>001</Reason>
</del:DeleteRequest>
Page 98 of 104
DHL Express Global Web Services – Developer Guide
13. Service Input/Output Examples for TrackingRequest
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 99 of 104
DHL Express Global Web Services – Developer Guide
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>
</ServiceArea>
<ShipperReference>
<ReferenceID/>
<ReferenceType/>
</ShipperReference>
</ArrayOfPieceEventItem>
<ArrayOfPieceEventItem>
<Date>2010-11-11</Date>
<Time>09:03:00</Time>
<ServiceEvent>
<EventCode>WC</EventCode>
<Description>With Delivering
Courier</Description>
</ServiceEvent>
<Signatory/>
<ServiceArea>
<ServiceAreaCode>BRI</ServiceAreaCode>
<Description>Bari - Italy</Description>
</ServiceArea>
<ShipperReference>
Page 100 of 104
DHL Express Global Web Services – Developer Guide
TrackingRequest: Sample Error
<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>
Page 101 of 104
DHL Express Global Web Services – Developer Guide
14. Service Input/Output Examples for 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 102 of 104
DHL Express Global Web Services – Developer Guide
Sample Output
Sample Error Response
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-
ENC="http://schemas.xmlsoap.o
rg/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:shipmentDocumentRetri
eveResp 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 for search query"></ErrMsgDtl>
</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://sc
hemas.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>
Page 103 of 104
DHL Express Global Web Services – Developer Guide
15. 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 104 of 104

Navigation menu