DHL Customer Web Service Developer Guide V1 0d - baixardoc

DHL Customer Web Services

Web Services User Guide

Doc. Ref. : DHL Customer Web Service Developer Guide V1.0d.doc

Version : 1.0

Status : Review

Date : 2011-01-10

Author : Harald Wagener, Terry Kelly

DHL Customer Web Service User Guide

DHL Customer Web Service Developer Guide V1 0d.doc - 2 - DHL PROPRIETARY AND CONFIDENTIAL

Version History

Revision Release

Date

Updated by Remarks/Comments Status

0.9 10/18/2010 H Wagener Phase 1 + Draft

1.0a 11/23/2010 T Kelly GE Phase 2 updates, will baseline

version history at 1.0

Draft

1.0b 11/28/2010 T Kelly Updates for Delete Shipment,

Error Codes

Draft

1.0c 12/08/2010 T Kelly Added Atomic Label Service Draft

1.0d 01/10/2011 T Kelly Incorporated feedback, atomic

services in separate document

Review

for

approval



CONTENTS

1 Introduction ............................................................................................................................ 5

1.1 DHL Customer Web Service Overview .................................................................................. 5

1.2 Requirements ............................................................................................................................ 5 1.2.1 Technical Skills .................................................................................................................................... 5 1.2.2 Business Understanding ........................................................................................................................ 5

2 DHL Customer Web Services Overview ................................................................................ 6

2.1 Web Service Definition Language and Reference Documents ............................................. 6

2.2 Testing DHL Web Services with Soap UI............................................................................... 6

2.3 Validation of the Input data .................................................................................................... 7

3 Security and Authentication .................................................................................................. 8

3.1 Authentication using WS-Security .......................................................................................... 8

3.2 User access rights ...................................................................................................................... 9

3.3 How to get a user for the web service authentication ............................................................ 9

3.4 User authentication in SOAP UI test project ....................................................................... 10

4 Web Services Operations ..................................................................................................... 11

4.1 RateRequest ............................................................................................................................ 11 4.1.1 RateRequest: Description ................................................................................................................... 11 4.1.2 RateRequest: Input .............................................................................................................................. 11 4.1.3 RateResponse: Output......................................................................................................................... 20

4.2 ShipmentRequest .................................................................................................................... 24 4.2.1 ShipmentRequest: Description............................................................................................................ 24 4.2.2 ShipmentRequest: Input ...................................................................................................................... 24 4.2.3 ShipmentRequest: Output ................................................................................................................... 37

4.3 ShipmentDeleteRequest ......................................................................................................... 41 4.3.1 ShipmentDeleteRequest: Description ................................................................................................. 41 4.3.2 ShipmentDeleteRequest: Input ........................................................................................................... 41 4.3.3 ShipmentDeleteRequest: Output ......................................................................................................... 42

5 Appendix ............................................................................................................................... 44

5.1 Rate Request and Shipment Request Error codes and messages ....................................... 44 5.1.1 Capability and Quotation Errors ......................................................................................................... 44 5.1.2 Route Code Errors .............................................................................................................................. 46 5.1.3 Shipment Date Validation ................................................................................................................... 46 5.1.4 Account Validation ............................................................................................................................. 46 5.1.5 Label Generation Errors ...................................................................................................................... 47 5.1.6 Manifest Submission Errors ................................................................................................................ 48 5.1.7 Pickup Errors ...................................................................................................................................... 48 5.1.8 General Errors ..................................................................................................................................... 49

5.2 Service Input/Output Examples for RateRequest ............................................................... 50 5.2.1 RateRequest: Sample Input ................................................................................................................ 50 5.2.2 RateRequest: Sample Output ............................................................................................................. 50 5.2.3 RateRequest: Request with error ........................................................................................................ 51

5.3 Service Input/Output Examples for ShipmentRequest ....................................................... 52 5.3.1 ShipmentRequest: Sample Input ......................................................................................................... 52 5.3.2 ShipmentRequest: Sample Output ...................................................................................................... 53 5.3.3 ShipmentRequest: Sample request with error ..................................................................................... 53

5.4 Service Input/Output Examples for ShipmentDeleteRequest ............................................ 54



5.4.1 ShipmentDeleteRequest: Sample Input .............................................................................................. 54 5.4.2 ShipmentDeleteRequest: Sample Output ............................................................................................ 54 5.4.3 ShipmentDeleteRequest: Sample request with error ........................................................................... 54

5.5 Helpful XML and Web Services ............................................................................................ 55



1 Introduction

1.1 DHL Customer Web Service Overview

The DHL customer 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 online as well as booking a courier to pick

up a shipment.

This document describes how to integrate these services to your own applications and is

intended as a user guide for developers.

1.2 Requirements

1.2.1 Technical Skills

Technically speaking, the customer web service 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 customer 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.

Moreover, for many of the popular programming languages there exist tools to generate

stub code from a web service definition file (“.wsdl”). These stub class files will serve as

your SOAP proxy that you can invoke from within your programming environment. For

example, Apache Axis lets you create Java stub code from a wsdl source. Similarly,

NuSOAP or PEAR::SOAP can be used to generate PHP stubs, and for other languages like

Python, Ruby on Rails etc stub code generators is available as well.

1.2.2 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.



2 DHL Customer Web Services Overview

There are some main points that must be noted before getting started with the DHL

customer web service 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 Customer Web Services, including

WSDL and SOAP UI project.

Reference Description Document

WSDL

Description

WSDL of the web service. Please

note, that the accessing URL

endpoint within the WSDL

description is not the real address of

the service. Your DHL contact can

provide the production endpoint

upon completion of certification

testing.

https://wsbuat.dhl.com:8300/amer/

GEeuExpressRateBook?WSDL

DHL

Customer

Web services

SOAP UI

Project

Download SOAP UI tool from

soapui.com

Import the provided SOAP UI

project and start using DHL

Customer Web Services interfaces

immediately.

The SOAP UI project can be

provided by your DHL contact

from the outset of the integration

engagement.

2.2 Testing DHL Web Services with Soap UI

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.

In addition to installing the free product, your DHL contact can provide a Soap UI project,

containing sample requests to be used as a baseline for any testing.

Below are the steps to

1. Download the latest version of the SoapUI tool from their website

(http://www.soapui.org/) and install on the desired machine.



1. SoapUI first start

2. To import an existing project right click on the “Projects” item (marked in red) and

select “Import Project”. Select the project xml file provided by your DHL contact,

which will represent the Soap UI project for these specific DHL services.

3. At this point, the individual requests within the Soap UI project. The content of the

requests is shown within the main area, and can be modified and executed as needed.

For running click on the green arrow button within the toolbar area.

More information on the Soap UI tool can be found on its website.

2.3 Validation of the Input data

The input data for the DHL 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.



3 Security and Authentication

External Web Service calls from the customer to DHL (XML over HTTP – custom, SOAP or

RESTful based web service invocation) 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). Please note, within

test environment, an alternative port for https (port 8300) is used. 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.

3.1 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,

as follows:

<soapenv:Envelope xmlns:rat="http://scxgxtt.phx-dc.dhl.com/euExpressRateBook/RateMsgRequest" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Header> <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 wsu:Id="UsernameToken-5" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <wsse:Username>USER</wsse:Username>

<wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">PASS</wsse:Password>

<wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">eUYebYfsjztETJ4Urt8AJw==</wsse:Nonce>

<wsu:Created>2010-02-12T17:40:39.124Z</wsu:Created> </wsse:UsernameToken> </wsse:Security> </soapenv:Header>

The below diagram details the orchestration of HTTPs for external traffic and HTTP within the

DHL network.



��

��

��

��

��

� ��

� ��

��

!"#�� $��%�& �'(�)�*+� ,

� �

��% �-��$

��

��.��

��

��-��

��

��/%��-

�� /��-

+��/%��-��$��0�/

��-��

��-�

��/%��-��

3.2 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 establish 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 customer web services. Just the application itself will get access to the DHL

customer web services and not each user registered in the application ABC.

3.3 How to get a user for the web service authentication



The authentication credentials will be provided by your DHL point of contact for the integration

project.

3.4 User authentication in SOAP UI test project

Please have a look at the areas marked in red in the below screenshot.

In SOAP UI you have to enter the Username and the password in the “Auth” section.

In addition you have to set the property named WSS-Password-Type to “PasswordText”.

If this property is not set, you might get the following error:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<soap:Fault>

<faultcode>soap:Client</faultcode>

<faultstring>Forbidden</faultstring>

<faultactor>internal-firewall</faultactor>

<detail xmlns:det="http://reactivity.com/">

<det:detailmessage>Forbidden. You are not allowed to access that resource.</det:detailmessage>

</detail>

</soap:Fault>

</soap:Body>

</soap:Envelope>

DHL Customer Web Service Developer Guide V1 0d - baixardoc

Documents

Transcript of DHL Customer Web Service Developer Guide V1 0d - baixardoc