DHL Web Service Documentation

Retoure Online Version 2.0

Table of Contents
1 Welcome to the DHL web service for online returns............................................ 3
1.1 About the document...................................................................................................... 3
1.2 Technical overview........................................................................................................ 3
1.2.1 System requirements................................................................................................ 4
1.2.2 Access required........................................................................................................ 4
1.3 Technical background full integration into your mail order site ........................... 4
1.3.1 Benefits..................................................................................................................... 6
1.3.2 Possible variants of the solution ............................................................................... 6
1.4 Feedback and support .................................................................................................. 6

2 Brief instructions: Six steps to the return label.................................................... 7

2.1 Step 1: Set up a returns portal with a recipients address ........................................ 7
2.2 Step 2: Setting up the client ......................................................................................... 7
2.3 Step 3: Set up communication ..................................................................................... 7
2.3.1 Web service communication on the basis of SOAP ................................................. 8
2.4 Step 4: Create a user with sufficient authorizations .................................................. 8
2.5 Step 5: Example of taking over a code and testing it ................................................ 8
2.6 Step 6: Activate the web service for online returns on your website ........................... 8

3 API call reference..................................................................................................... 9

3.1 Book label request to input parameters................................................................... 9
3.2 Book Label Response issuing parameters ............................................................ 10
3.3 Malfunctions ................................................................................................................ 11
3.3.1 Types of faults ........................................................................................................ 11

4 Appendix Helpful sources ................................................................................. 13

4.1 XML and web services ................................................................................................ 13
4.2 Code example .............................................................................................................. 13
4.2.1 SOAP POST Retoure Online.................................................................................. 13
4.2.2 SOAP Retoure Online response............................................................................. 14

List of figures
Figure 1: Fictional example of a return screen on the website .................................................. 5
Figure 2: Example of an integrated call of a return label........................................................... 5

List of tables
Table 1: Endpoint, WSDL and Schema URLs of the live system .............................................. 8
Table 2: DHL Retoure Online web service request/call parameters ....................................... 10
Table 3: DHL Retoure Online web service response parameters ........................................... 10

1 Welcome to the DHL web service for online returns

DHL brings mail order returns into line with e-commerce online returns as a web service.
Welcome to the DHL web service for online returns. This interface allows the DHL Retoure Online
[online returns] application to be smoothly integrated into your e-commerce shop pages and
processes. Thus the offering to the customers is improved, and they will also stay on your website
and within your selling process.

1.1 About the document

This documentation contains a description of the interface and is intended as reference
documentation for software developers. Reasons and context are explained, and the connection is
described.
The documentation is subdivided into three sections:
Section 1 explains the conditions which enable you to use the web service.
Section 2 is a brief introduction to the topic and offers a rough overview of the processes involved with
the web service for online returns.
Section 3 gives a more detailed explanation of the way the functions are called and describes its input
and output parameters.
Finally, the appendix contains a list of sources and a code example which helps you to handle the
web service.

1.2 Technical overview

This web service is a synchronous SOAP interface which enables DHL return labels to be
produced locally. Thus as well as letting you call a URL (so-called variants 1 and 2), it also offers
alternative access to the DHL online returns application and enables you, whether you run a shop
or mail order firm or act as their software supplier, to raise your returns management to the next
level. The communication of your back-end system and the web service allows you to design the
return process in a very customer-friendly way, and significantly improve your business.
Do you run a web shop and want to improve the efficiency of the return process? Are you a software
or IT service provider who wants to offer your customers in the mail order business improvements in
your shop products?
DHL Retoure Online enables your software:

To undertake the production of your own return labels for your customers

To ensure that the labels are sent to your desired address(es) and are only invoiced once they
have been used

Technically this web service consists of a single operation, which can be addressed using the
standardized SOAP protocol via HTTPS, or alternatively transferred in the body of an HTTPS
post request.
The input parameters describe the data to create the return label. The web service responds
immediately with an XML document containing the output parameters and the return label coded in
Base64.
To use the service, developers should have a good understanding of, and experience in using
SOAP. The appendix lists some helpful links.

1.2.1 System requirements

Only one Internet access is required so that the web service can be addressed via TCP/IP. In
addition to connection management with the DHL service, SOAP and/or XML tools should be
available to create call documents from the application logic and read the information from the
reply document (parsing).

1.2.2 Access required

User name and password

1.3 Technical background full integration into your mail order site
As a supplier of mail order products or of supporting software, you define in which form you would
like to use the data for the DHL Retoure Online solution. A customer-friendly process of integrated
return label ordering is presented as follows:

The customer would like to send a product back and goes on to your website to call the
offered return service. (You will already have sent him the link address, for instance in the
e-mail to confirm the purchase).

After he has been identified and has selected the product to be returned from the list of
his most recent purchases, he reaches an input screen with pre-filled sender data
which corresponds to the delivery address.

If necessary, he corrects the sender data and sends the form off.

The variable data is transmitted to the DHL Retoure Online service. The recipients
address, however, is stored in advance in the DHL system.

The web service replies with an XML response, which contains the ready-to-use return
label as a PDF document (coded in Base64) and other item data (IDC, etc.).

The return label is printed off by the end customer and affixed to the parcel.

The end customer delivers his parcel (free of charge) to one of our retail outlets.

Figure 1: Fictional example of a return screen on the website

Figure 2: Example of an integrated call of a return label

1.3.1 Benefits
This integration solution brings great benefits, both for you as a mail order company and for
your customers. For you as the operator:

Much reduced cost for customer service

The customer remains within your selling process with a consistent Look and Feel, and
other opportunities for up-selling and cross-selling

You define the complete process

Only those parcels which are actually transported are invoiced, based on the production
data according to the current DHL billing documentation

The customers benefits are:

Only a few process steps when creating the return label

Quick result

Service free of charge

A wide variety of possibilities for posting (retail outlet, collection)

A user-friendly layout

1.3.2 Possible variants of the solution1

Advance notification of the parcels through the Paket-Ident [parcel identity] numbers

Set-up of several accounts by your DHL contact for other possible recipient addresses of
your returns, e.g.

Return to your returns warehouse

Exchange to your goods receipt

Repairs of other service providers

1.4 Feedback and support

If you require additional support, or would like to provide feedback on the web service or the
document, please contact our Sales partner or DHL Customer Service.

You are the only person who can implement the additional features.

2 Brief instructions: Six steps to the return label

2.1 Step 1: Set up a returns portal with a recipients address
Before you can begin the technical set-up, the following configuration steps must be performed:

The returns portal is set up and pre-configured after an application is made for the
DHL web service. You are free to choose the names of the returns portals when you
make the application. After this is complete, you receive an override e-mail which includes
the following
Information: (Example here without function)
For your initial registration, please use the option Request new password and state your
user name on the page:
https://amsel.dpwn.de/abholportal/gw/lp/portal/288Test/admin/AdminLogin.action

Please log in with your user name and password and complete the details to use your
portal in the Settings area.

Then set up your desired recipient address for the returns in the Addresses for return
recipients area.
The following returns portals are already pre-configured
RetourenlagerDeutschland:https://amsel.dpwn.de/abholportall/gw/lp/portal/288Test/custo
mer/RpOrder. action ?delivery=RetourenlagerDeutschland
RetoureFrankreich:https://amsel.dpwn.de/abholportall/gw/lp/portal/288Test/customer/RpO
rder. action ?delivery=RetoureFrankreich
Your web service user name is: TEST123
You can (once only) use the following link to set the password for the web service user:
https://amsel.dpwn.de/abholportal/gw/web/admin/AdminLogin.action?token=12345....

Log in to the administration area, check and save all the necessary information. If you only use
the web service, then only the return recipient address must be checked and saved.

You must set the new password for the web service separately from the admin password.
To do this, please open the link sent and change the password according to the
instructions. Your web service returns portal is then completely configured and may be
contacted.

2.2 Step 2: Setting up the client

Before you call web services, make sure the system has been set up correctly. Apart from the
hardware and the TCP/IP Internet access, you require a released returns portal in the Amsel
application, and a return recipient configured for Variant 3 with a valid recipients address. (You
can maintain these yourselves in the administration area of your returns portal).

2.3 Step 3: Set up communication

Communication is done by SOAP request via a secure HTTPS connection. The examples in the
Appendix make clear the use of the parameters and may be used as a starting-point after the
access data has been adjusted.

2.3.1 Web service communication on the basis of SOAP

First load the relevant web service definitions and Schema files of DHL. These are required to
develop applications for this web service. They specify the required structure of the SOAP
messages, the function signatures, the API service bindings and the service endpoints. The
table below contains the access points for the live system.
LIVE SYSTEM

Resource
WSDL

URL
https://amsel.dpwn.net/abholportal/gw/lp/schema/1.0/var3ws.wsdl

Endpoint

https://amsel.dpwn.net/abholportal/gw/lp/SoapConnector

Table 1: Endpoint, WSDL and Schema URLs of the live system

After downloading these files, you can use a SOAP client service to generate business object
interfaces and network stubs and make your work considerably easier. Finally, the request is
formulated as a SOAP methods call and forwarded to the SOAP service endpoint.

2.4 Step 4: Create a user with sufficient authorizations

Each of the web service operations requires an authentication. So apply to your DHL Sales contact
for the necessary authorizations for the DHL Retour Online service, so-called Variant 3. After
release, you will receive:

A user name and password as a specially set up web service user

2.5 Step 5: Example of taking over a code and testing it

To simplify your programming, you will find a code example in the Appendix, which you can adapt to
your requirements.
To test the example code delivered at the same time, please activate the web service, using the
URLs mentioned under item 2.3.1.

2.6 Step 6: Activate the web service for online returns on your website
Checklist for activating the web service for online returns on your website:

the test has been completed successfully (see 3.3 Malfunctions)

1 the return label is displayed completely and printed out

1 the call is successfully integrated into your website

The web service for online returns will respond synchronously to your request. If the transfer is
successful, the response message will contain the following for the return label produced:

the routing codethe national IDC and the type of IDC (LP or IDC)

the international IDC with its typethe Base64-coded label in PDF format

3 API call reference

To call the web service, the following parameters must be provided.
In line with the focus on SOAP, the WSS user name token was stated in the specification of
the product web service as the basis for document-based security with regard to the highest
possible degree of standardization. The WSS user name token is transferred in the SOAP
header and is not part of the data type definitions or messages.
<wsse:Security soapenv:mustUnderstand="1"
xmlns :wsse="http: //docs . oasis-open . org/wss/2004/01 /oasis-200401-wss-wssecurity-secext-1 .0
.xsd"> <wsse : UsernameToken>
<wsse : Username>Nutzername Webservice-User</wsse : Username> <wsse :
Password >Klartextpasswort</wsse : Password>
</wsse : UsernameToken>
</wsse : Security>
The password is stated in the plain text in the tag <wsse:Password>. More precise information on
the WSS user name token is available at

http://www.oasis-open.org/committees/download.php/5532/oasis-200401-wss-usernametoken-prof ile-1.0.pdf

3.1 Book label request to input parameters

Name

Task

portalId
Yes

deliveryName

Yes

NoNo
customerReference

Yes

Max.
length

The URL Postfix allocated to the portal You will find your
portal ID in the override e-mail here:
(here 288 Test)
For your initial registration, please use the option Request
new password and state your user name on the page:
https://amsel.dpwn.de/abholportal/gw/lp/portal/288Test/a
d
min/AdminLogin.action
The name of the returns portal which is to receive the
returns. You will find the relevant delivery/name in the
override e-mail here: (here RetoureFrankreich [returns
France]) The following returns portals are already
configured: RetoureFrankreich:
https://amsel.dpwn.de/abholportall/gw/lp/portal/288Test/
cu
stomer/RpOrder. action ?delivery=RetoureFrankreich
Contents of the first entry field, Item reference

shipmentReference
labelFormat

Description

40
50

The file format of the label produced, up to now only PDF. 10

Sender Name 1
Sender Name 1 Sender

Yes
No No

Name 1 of sender Name 2 of sender Care of name. Is

50

not currently used for labels.

50
50

Care of Name
senderContactPhone

No

Sender phone contact Is not currently used for labels.

20

senderStreet

Depends on
international
address

Sender street. Is printed on label.

50

Sender house number Is printed on label.

Sender box number. Is not currently used for labels.

Senders postal code. Is printed on label.

Sender town or city Is printed on label.

50

senderStreetNumber

Sender box number

senderPostalCode

senderCity

configuration
Depends on
international
address
configuration
Depends on
international
address
configuration
Depends on
international
address
configuration
Depends on
international
address
configuration

Table 2: DHL Retoure Online web service request/call parameters

3.2 Book Label Response issuing parameters

Name

Description

label issueDate

The Base64-encrypted label as PDF Date of commissioning

routingCode

The routing code of the commissioning

idc

The national (German) identifier of the commissioning The type of

idcType intIdc

national identifier
The international routing code if available

intIdcType

The type of international routing code

Table 3: DHL Retoure Online web service response parameters

3.3 Malfunctions
3.3.1 Types of faults
In cases of faults, the relevant fault is stated in the body of the SOAP response in the <fault> tag.
<env:Envelope xmlns :ns4="http://docs .oasis-open.org/wss/2004/01/oasis200401-wss-wssecuritysecext-1 .0 .xsd" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns :var3bl="https : //amsel . dpwn . net/abholportal/gw/lp/schema/1 . 0/var3bl" xmlns:ns1="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wsswssecurity-utility-1 .0. xsd">
<env : Header/>
<env:Body env:encodingStyle="">
<env: Fault>
<faultcode>var3bl: InvalidXml</faultcode>
<faultstring>Invalid XML</faultstring>
</env: Fault>
</env : Body>
</env : Envelope>
The following fault codes can be returned in the response:
<faultcode>

<faultstring>

Description

InternalError

Internal Error

There was an internal server error in

processing.

InvalidXml NoPortal

Invalid XML

The request contains an invalid XML

No returns portal could be

No portal could be found for the ID sent in
found for the Portal ID stated the Portal ID field.
Locked Portal

The portal is blocked

NoDivision

No return recipient could be The name of the return recipient provided in

the Delivery Name
found for the delivery ID
field could not be found.
stated.

LockedOrDeletedDivision

The desired return recipient is The name of the return recipient provided in
blocked or deleted
the Delivery Name
was found, but it is blocked or has been
The desired return recipient deleted.

No variant 3 division

is not released for variant 3

The length of a field is not
correct

The name of the return recipient provided in

the Delivery Name
has been found, but is not configured for
variant 3 (web service).
The length of a field provided is not correct
The figures entered were either too short or
too long.

FieldLength

MandatoryField

The portal ID referenced in the field was

found, but is blocked. Commissioning is
impossible.

No mandatory field is set

No figure was provided for a mandatory

field

InvalidSenderAddress

Sender address could not

be validated successfully

Validation of the sender address was not

successful. It must be ensured that the
sender address takes the form typical for
that country.

NoDeliveryAddress

No recipient address was set

up

In the Corporate Customers admin frontend, no recipient address has yet been
provided for the return recipient.
Therefore commissioning is impossible.

for the recipient of the

return

4 Appendix Helpful sources

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

4.2 Code example

4.2.1 SOAP POST Retoure Online
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:var="https: //amsel.dpwn.net/abholportal/gw/lp/schema/1. 0/var3bl">
<soapenv : Header>
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1. 0.xsd"> <wsse:
UsernameToken>
<wsse:Username>ws _online _retoure< /wsse : Username>
<wsse : Password
Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-tokenprofile1. 0#PasswordText">Anfang1!</wsse : Password> </wsse :UsernameToken>
</wsse: Security>
</soapenv: Header>
<soapenv : Body>
<var: BookLabelRequest
portalId="OnlineRetoure"
deliveryName="Spanien_Var3" shipmentReference="ShipRef Nextt"
customerReference="1.Feld via Webservice"
labelFormat="PDF"
senderName1="Willi Webservice" senderName2="via Webservice"
senderCareOfName=" careOfName" senderContactPhone=" 0800 123456"
senderStreet="Webservice Street" senderStreetNumber=" 8080"
senderBoxNumber="12"
senderPostalCode="28010"
senderCity="Madrid" />
</soapenv: Body>
</soapenv : Envelope>

4.2.2 SOAP Retoure Online response

<env: Envelope
xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:var3bl="https://amsel.dpwn.net/abholportal/gw/lp/schema/1.0/var3bl"
xmlns:ns1="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
xmlns:ns5="http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-secext1.0.xsd">
<env : Header/>
<env:Body env:encodingStyle="">
<var3bl:BookLabelResponse
intIdcType="ID_ESP_PPO"
intIdc="PP600095823000000000923"
idc="00340435019999802143"
routingCode="53113019020746"
issueDate="2010-11-09T12:52:11.430+0100">
<var3bl: label>LABEL-Daten Base64-kodiert</var3bl : label>
</var3bl:BookLabelResponse>
</env : Body> </env:Envelope>