DHL Customer Web Services Web Services User GuideDoc. Ref. Version Status Date Author : DHL Customer Web Service Developer Guide V1.0d.doc : 1.0 : Review : 2011-01-10 : Harald Wagener, Terry Kelly DHL Customer Web Service User Guide Version History Revision 0.9 1.0a 1.0b 1.0c 1.0d Release Updated by Date 10/18/2010 H Wagener 11/23/2010 T Kelly 11/28/2010 T Kelly 12/08/2010 T Kelly 01/10/2011 T Kelly Remarks/Comments Phase 1 + GE Phase 2 updates, will baseline version history at 1.0 Updates for Delete Shipment, Error Codes Added Atomic Label Service Incorporated feedback, atomic services in separate document Status Draft Draft Draft Draft Review for approval DHL Customer Web Service Developer Guide V1 0d.doc -2- DHL PROPRIETARY AND CONFIDENTIAL DHL Customer Web Service User Guide CONTENTS 1 Introduction............................................................................................................................ 5 1.1 1.2 1.2.1 1.2.2 DHL Customer Web Service Overview .................................................................................. 5 Requirements ............................................................................................................................ 5 Technical Skills .................................................................................................................................... 5 Business Understanding ........................................................................................................................ 5 2 DHL Customer Web Services Overview ................................................................................ 6 2.1 2.2 2.3 Web Service Definition Language and Reference Documents ............................................. 6 Testing DHL Web Services with Soap UI............................................................................... 6 Validation of the Input data .................................................................................................... 7 3 Security and Authentication .................................................................................................. 8 3.1 3.2 3.3 3.4 Authentication using WS-Security .......................................................................................... 8 User access rights ...................................................................................................................... 9 How to get a user for the web service authentication ............................................................ 9 User authentication in SOAP UI test project ....................................................................... 10 4 Web Services Operations ..................................................................................................... 11 4.1 4.1.1 4.1.2 4.1.3 RateRequest ............................................................................................................................ 11 RateRequest: Description ................................................................................................................... 11 RateRequest: Input .............................................................................................................................. 11 RateResponse: Output......................................................................................................................... 20 4.2 4.2.1 4.2.2 4.2.3 ShipmentRequest .................................................................................................................... 24 ShipmentRequest: Description............................................................................................................ 24 ShipmentRequest: Input ...................................................................................................................... 24 ShipmentRequest: Output ................................................................................................................... 37 4.3 4.3.1 4.3.2 4.3.3 ShipmentDeleteRequest ......................................................................................................... 41 ShipmentDeleteRequest: Description ................................................................................................. 41 ShipmentDeleteRequest: Input ........................................................................................................... 41 ShipmentDeleteRequest: Output ......................................................................................................... 42 5 Appendix ............................................................................................................................... 44 5.1 5.1.1 5.1.2 5.1.3 5.1.4 5.1.5 5.1.6 5.1.7 5.1.8 Rate Request and Shipment Request Error codes and messages....................................... 44 Capability and Quotation Errors ......................................................................................................... 44 Route Code Errors .............................................................................................................................. 46 Shipment Date Validation ................................................................................................................... 46 Account Validation ............................................................................................................................. 46 Label Generation Errors...................................................................................................................... 47 Manifest Submission Errors................................................................................................................ 48 Pickup Errors ...................................................................................................................................... 48 General Errors ..................................................................................................................................... 49 5.2 5.2.1 5.2.2 5.2.3 Service Input/Output Examples for RateRequest ............................................................... 50 RateRequest: Sample Input ................................................................................................................ 50 RateRequest: Sample Output ............................................................................................................. 50 RateRequest: Request with error ........................................................................................................ 51 5.3 5.3.1 5.3.2 5.3.3 Service Input/Output Examples for ShipmentRequest ....................................................... 52 ShipmentRequest: Sample Input ......................................................................................................... 52 ShipmentRequest: Sample Output ...................................................................................................... 53 ShipmentRequest: Sample request with error ..................................................................................... 53 5.4 Service Input/Output Examples for ShipmentDeleteRequest ............................................ 54 -3DHL PROPRIETARY AND CONFIDENTIAL DHL Customer Web Service Developer Guide V1 0d.doc DHL Customer Web Service User Guide 5.4.1 5.4.2 5.4.3 ShipmentDeleteRequest: Sample Input .............................................................................................. 54 ShipmentDeleteRequest: Sample Output ............................................................................................ 54 ShipmentDeleteRequest: Sample request with error........................................................................... 54 5.5 Helpful XML and Web Services............................................................................................ 55 DHL Customer Web Service Developer Guide V1 0d.doc -4- DHL PROPRIETARY AND CONFIDENTIAL DHL Customer Web Service User Guide 1 1.1 Introduction 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 1.2.1 Requirements 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. DHL Customer Web Service Developer Guide V1 0d.doc -5- DHL PROPRIETARY AND CONFIDENTIAL this tool can be used to independently verify the DHL services in a test environment. Document https://wsbuat. Your DHL contact can provide the production endpoint upon completion of certification testing.org/) and install on the desired machine. service endpoints and service location. your DHL contact can provide a Soap UI project.soapui. Prior to development cycle.soapui. that the accessing URL endpoint within the WSDL description is not the real address of the service. In addition to installing the free product.DHL Customer Web Service User Guide 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.2 Testing DHL Web Services with Soap UI The open source product SoapUI (http://www.com:8300/amer/ GEeuExpressRateBook?WSDL DHL Customer Web services SOAP UI Project The SOAP UI project can be provided by your DHL contact from the outset of the integration engagement. Reference WSDL Description Description WSDL of the web service.1 Web Service Definition Language and Reference Documents These documents will be used to integrate to the DHL Customer Web Services.org/) provides advanced support for testing Web Services. 2.doc -6- DHL PROPRIETARY AND CONFIDENTIAL .com Import the provided SOAP UI project and start using DHL Customer Web Services interfaces immediately. Download the latest version of the SoapUI tool (http://www. Download SOAP UI tool from soapui. from their website DHL Customer Web Service Developer Guide V1 0d. Below are the steps to 1. Please note. 2. and provide verification and context during the system development life cycle.dhl. It is also useful in providing functionality context to the consumer prior to development and independently validating security credentials. containing sample requests to be used as a baseline for any testing. including WSDL and SOAP UI project. 3 Validation of the Input data The input data for the DHL Web Services is validated in several steps. 3. SoapUI first start 2. Select the project xml file provided by your DHL contact. In a second step. which will represent the Soap UI project for these specific DHL services. The service operation always delivers a result message. To import an existing project right click on the “Projects” item (marked in red) and select “Import Project”.e. DHL Customer Web Service Developer Guide V1 0d. The results of these validations are placed in the result message of the service operation. several business rules are applied on the passed data. 2. More information on the Soap UI tool can be found on its website. The content of the requests is shown within the main area. For running click on the green arrow button within the toolbar area. At this point. the individual requests within the Soap UI project. All errors or validation errors are stored in this result messages.doc -7- DHL PROPRIETARY AND CONFIDENTIAL . schema validation).DHL Customer Web Service User Guide 1. Please refer to the Appendix for complete list of error codes. The first step is general XML validation based on data cardinality and data content restrictions defined by the request message format (i. and can be modified and executed as needed. 0...doc -8DHL PROPRIETARY AND CONFIDENTIAL . Please note.org/wss/2004/01/oasis-200401-wsswssecurity-secext-1.org/wss/2004/01/oasis-200401wss-wssecurity-utility-1. For this solution.1 Authentication using WS-Security WS-Security offers a general-purpose mechanism for associating security tokens with message content.phx-dc.org/wss/2004/01/oasis-200401-wss-soap-message-security1. The following XML snippet shows a sample WS-Security UsernameToken: <wsse:UsernameToken wsu:Id="Example"> <wsse:Username> ."> .. </wsu:Created> </wsse:UsernameToken> To authenticate using WS-Security for DHL Web Services. as follows: <soapenv:Envelope xmlns:rat="http://scxgxtt.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.oasis-open. virtualization.. and enhanced performance for web service transactions..DHL Customer Web Service User Guide 3 Security and Authentication External Web Service calls from the customer to DHL (XML over HTTP – custom. an alternative port for https (port 8300) is used..0#PasswordText">PASS</wsse:Password> <wsse:Nonce EncodingType="http://docs..0.. </wsse:Username> <wsse:Password Type=". within test environment.org/soap/envelope/"> <soapenv:Header> <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.com/euExpressRateBook/RateMsgRequest" xmlns:soapenv="http://schemas.oasis-open. the DHL Web Service Broker will validate that the messages are well formed and provide security and data encryption. but for the purposes of these services.xmlsoap. The specification defines three approved token types.dhl.."> .xsd"> <wsse:Username>USER</wsse:Username> <wsse:Password Type="http://docs. This header would contain the WS-Security information.oasis-open.. For example. UsernameToken will be used. The SOAP header also requires the setting of Password Type as ‘PasswordText’. The primary transport protocol for these calls is https (standard port 443).org/wss/2004/01/oasis-200401-wss-username-token-profile1. </wsse:Password> <wsse:Nonce EncodingType=". security. 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. </wsse:Nonce> <wsu:Created> . the consumer would need to add a SOAP header to the SOAP envelope.0#Base64Binary">eUYebYfsjztETJ4Urt8AJw==</wsse:Nonce> <wsu:Created>2010-02-12T17:40:39. SOAP or RESTful based web service invocation) will be handled through the DHL Web Services Broker.. DHL utilizes WS-Security features of the SOAP protocol.. DHL Customer Web Service Developer Guide V1 0d.oasis-open. The Web Services Broker is an XML and web services gateway used by DHL providing governance.xsd"> <wsse:UsernameToken wsu:Id="UsernameToken-5" xmlns:wsu="http://docs. 3. and this solution assumes the customer will have establish integration credentials at application level.3 How to get a user for the web service authentication -9DHL PROPRIETARY AND CONFIDENTIAL DHL Customer Web Service Developer Guide V1 0d. Just the application itself will get access to the DHL customer web services and not each user registered in the application ABC. This web portal will call the DHL customer web services.DHL Customer Web Service User Guide DPWN WS Customer HTTPS DHL Firewall HTTPS DCG Integration Platform Web Services Broker Session key seed Encrypted with Public Key Client and WSB send encrypted messages WSB responds with SSL Certificate HTTP DHL Web Services (XML over http .2 User access rights The applicable statement for user access relates to the authentication properties enforced at the web service broker. Example: Customer XYZ is building a web portal ABC with internal user administration. Credentials will not be managed at the customer user level. REST) 3. 3. Authentication details will be stored on the Web Service broker as a configuration.doc WSB indicates all transmissions are encrypted Client requests Secure Socket .SOAP. xmlsoap. 3. If this property is not set.</det:detailmessage> </detail> </soap:Fault> </soap:Body> </soap:Envelope> DHL Customer Web Service Developer Guide V1 0d. In addition you have to set the property named WSS-Password-Type to “PasswordText”.org/soap/envelope/"> <soap:Body> <soap:Fault> <faultcode>soap:Client</faultcode> <faultstring>Forbidden</faultstring> <faultactor>internal-firewall</faultactor> <detail xmlns:det="http://reactivity.doc .DHL Customer Web Service User Guide The authentication credentials will be provided by your DHL point of contact for the integration project. You are not allowed to access that resource. In SOAP UI you have to enter the Username and the password in the “Auth” section.4 User authentication in SOAP UI test project Please have a look at the areas marked in red in the below screenshot.10 - DHL PROPRIETARY AND CONFIDENTIAL . you might get the following error: <soap:Envelope xmlns:soap="http://schemas.com/"> <det:detailmessage>Forbidden. 4. c) ShipmentDeleteRequest – This service allows the consumer to request the deletion of a pickup.11 - DHL PROPRIETARY AND CONFIDENTIAL . and outputs the corresponding available DHL products.DHL Customer Web Service User Guide 4 Web Services Operations For the orchestrated DHL web services offering. Within the RateRequest. and does not affect functionality. A shipment request can just be successfully executed (assuming the same input data) for a product which is returned by the rate request.1. there are three operations available for use.e. The critical elements are contained within the RequestedShipment node. and outputs reference information (airbill and piece) as well as a shipping label. this operation returns the available products including the shipping price and the potential delivery date considering the planned pickup date. using output from one service as input into the next service) to meet the consumer requirements.2 RateRequest: Input The following diagram shows an overview of the request input structure. The services are called independently.2. the ClientDetail is an optional node for reference use. 4.1 RateRequest: Description The Rate request will return DHL’s product capabilities and prices for a certain set of input data. if it was requested in the original ShipmentRequest. Using the shipper and receiver address as well as the dimension and weights of the pieces belonging to a shipment. a) RateRequest – This service allows the consumer to input characteristics about a prospective shipment. b) ShipmentRequest – This service allows the consumer to input characteristics about a requested shipment and pickup.1 RateRequest 4. 4. but can also be used in concert (i.1 RateRequest Schema Diagram DHL Customer Web Service Developer Guide V1 0d. along with rate estimates and estimated delivery date/time.doc .1.1. REQUEST_COURIER. with context.2.doc .2. 4. and country code. The possible values are as follows. since capability and rate are determined based on city. postal code. based on ShipmentTimeStamp. • 4. • 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. DHL Customer Web Service Developer Guide V1 0d.1. the street address elements are not critical.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.3 RateRequest Input: Ship The Ship section outlines the shipper and receiver for the specific rate request. In the context to rate requests.The rating response returns products for which the pickup capability is given.1.12 - DHL PROPRIETARY AND CONFIDENTIAL .DHL Customer Web Service User Guide Each of the individual sections of RequestedShipment are represented below in schema diagram. There are two possible values to indicate whether a pickup is considered. Please note that the Shipper and Recipient structures are identical. and a detailed description of each field follows in the Input Field List. 13 - DHL PROPRIETARY AND CONFIDENTIAL .DHL Customer Web Service User Guide DHL Customer Web Service Developer Guide V1 0d.doc . DHL Customer Web Service User Guide 4. For example. 4. respectively. In this context.1.4 RateRequest Input: Packages The Packages section details the weight and dimensions of the individual pieces of the shipment.5 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.1. the shipper may tender a single shipment with multiple pieces. a RequestedPackage node represents each individual piece. The value of ‘SI’ corresponds to KG and CM. DHL Customer Web Service Developer Guide V1 0d.2. etc. and each piece may have a distinct shipping label.doc .2. regular pickup. and there is a limitation of 50 RequestedPackage nodes in the request. either as part of a scheduled pickup.2.6 RateRequest Input: UnitOfMeasurement The UnitOfMeasurement node conveys the unit of measurements used in the operation. and should not be considered a system event. 4. station dropoff. respectively.1. This single value corresponds to the units of weight and measurement which are used throughout the message processing. Please note that the timestamp for this event does not represent the time of the execution of the service.14 - DHL PROPRIETARY AND CONFIDENTIAL . while the value of ‘SU’ corresponds to LB and IN. DHL recommends the use the more robust Billing structure. different products may be offered by the DHL web services.2.8 RateRequest Input: PaymentInfo The PaymentInfo node details the potential terms of trade for this specific shipment.9 RateRequest Input: Account The Account field details the DHL account number used for the rate request. and allows for using a payer account different than the shipper account (to allow for bill-to receiver or bill-to third party). When the account number is in this field.1.1.2.DHL Customer Web Service User Guide 4. this account number serves as both the shipper account as well as payer account.doc .15 - DHL PROPRIETARY AND CONFIDENTIAL .10 RateRequest Input: Billing The Billing structure functions as a more robust alternative to the single Account field.7 RateRequest Input: Contents The Contents node details whether a shipment contains documents (value DOCUMENTS) or other contents (NON_DOCUMENTS).2. The web service requestor should use either the Account field or the Billing structure to communicate account information. DHL Customer Web Service Developer Guide V1 0d. 4. Depending on the nature of the contents of the shipment. 4.2.1. and DHL recommends the Billing structure. and the schema itself defines the possible enumerated values for this field. 4.1. /RequestedShipment Value constraints Comments O O This field is for internal use only This field is for internal use only Possible values: ./ClientDetail sso plant . based on ShipmentTimeStamp.DHL Customer Web Service User Guide 4.2. only Insurance service is activated for use.16 - DHL PROPRIETARY AND CONFIDENTIAL ./Ship M DHL Customer Web Service Developer Guide V1 0d.1. the pickup location is already served by a regular courier and an additional pickup does not need to be considered for this service .REGULAR_PICKUP. and the remaining values are included for future use.12 Rate Request Input Field List Mandat ory /Optiona l Rate Request fields RateRequest . 4.11 RateRequest Input: SpecialServices The SpecialServices section communicates additional shipping services.2. DropOffType .REQUEST_COURIER The rating response returns products for which the pickup capability is given.1. such as Insurance (or Shipment Value Protection). For this version of the services.doc . 1 D 5./Dimensions Length Width Height M M M M 15. Width of the piece listed. Height of the piece listed. if feasible. if feasible. Shipper additional address information Shipper additional address information Shipper city name Shipper State or Province Shipper postal code ISO 2 character codes of the Shipper country.doc . @number O Weight . Recipient additional address information Recipient additional address information Recipient city name Recipient State or Province Recipient postal code ISO 2 character codes of the Receiver country. Shipper street number should be sent as separate attribute./Address StreetLines StreetName StreetNumber StreetLines2 StreetLines3 City StateOrProvinceCode PostalCode O O AN35 AN35 AN15 O O O M O M M AN35 AN35 AN35 AN35 AN12 AN2 Shipper street name and number Shipper street name should already be sent as separate attribute if feasible. Sum of the weight of the individual pieces/packages the rating request is for./Shipper StreetLines StreetName StreetNumber StreetLines2 StreetLines3 City StateOrProvinceCode PostalCode CountryCode .DHL Customer Web Service User Guide . This timestamp identifies the ready date and time of the rated shipment. M O AN35 AN35 AN15 O AN35 O AN35 O M M M AN35 AN35 AN12 AN2 CountryCode M .17 - DHL Customer Web Service Developer Guide V1 0d.1 D 5. Length of the piece listed. Recipient street number should be sent as separate attribute./Packages (1:1) .1 D Will be used as Piece Sequence number and returned in the response./Recipient . It needs to be provided in the following format with GMT offset DHL PROPRIETARY AND CONFIDENTIAL ShipTimestamp M ./RequestedPackages (1:M) No length constraint Max 50 occurrences Recipient street name and number Recipient street name should be sent as separate attribute if feasible.3 D 5. 18 - Possible Values . CM) . IN) The unit of measurement for the dimensions of the package. BillingAccountNumber . Possible values . UK. if ShippingPaymentType is equal to R or T. UnitOfMeasurement M N/A Content M N/A PaymentInfo M N/A Account Billing M N/A ShipperAccountNumber O N/A The DHL account number used for the shipment.INS (Insurance) DHL PROPRIETARY AND CONFIDENTIAL DHL Customer Web Service Developer Guide V1 0d.NON-DOCUMENTS Possible values: . the rate request will return this in the error code as it is a non valid request. Internally attached to this account are the customer specific rates. sunday or any other day where there is no pickup. Possible values: ./SpecialServices .T (use BillingAccountNumber as bill-to third party account number) ShippingPaymentType O AN1 The DHL account number used for the shipment.doc .DHL Customer Web Service User Guide YYYY-MM-DDTHH:MM:SS GMT+k 2010-02-26T17:00:00 GMT+01:00 If the date is on a public holiday. Used as the shipper account number. international metric system (KG. Possible values: .See schema enumeration The DHL account number that is used for the shipment.R (use BillingAccountNumber as bill-to receiver account number) ./Service ServiceType O N/A M AN3 .SI.S (use ShipperAccountNumber as payer) .DOCUMENTS .SU. US system of measurement (LB. g. For future use. For future use.doc .19 - DHL PROPRIETARY AND CONFIDENTIAL . DHL Customer Web Service Developer Guide V1 0d. Insured Value) Currency code For future use. For future use.3 D AN3 AN3 Date Date AN50 Monetary value of service (e.DHL Customer Web Service User Guide ServiceValue CurrencyCode PaymentCode StartDate EndDate TextInstruction O O O O O O 15. and the expected delivery time for the shipment. the estimated charges.doc .3.3 RateResponse: Output The following diagram shows an overview of the rate response structure.1 RateResponse Schema Diagram Each of the individual sections of Rate Response are represented below in schema diagram.1.1.1. with context. DHL Customer Web Service Developer Guide V1 0d. and a detailed description of each field follows in the Output Field List.20 - DHL PROPRIETARY AND CONFIDENTIAL . 4.DHL Customer Web Service User Guide 4. 4. while exceptions will be noted with both code and message.3. Successful messages will include a zero error code and no corresponding message. The critical information to derive from this response are the notification codes for the response. the products returned. based on the results of the processing.2 RateResponse Output: Notification The Notification structure includes the result code and message. these nodes will have the summary estimates. DHL Customer Web Service Developer Guide V1 0d. under Charges.3.21 - DHL PROPRIETARY AND CONFIDENTIAL .4 RateResponse Output: TotalNet For successful responses. Nevertheless.DHL Customer Web Service User Guide 4.1. which will include all of the information about the DHL product returned. Please note that the subsequent nodes. The charges and delivery times for that product are in the subsequent nodes within Service.1. the total net structure shows the summary of the net estimated charges (plus currency) for a given Service. provides line item detail of the estimated charge. A critical element of the Service structure is the @type attribute. which designates the DHL global product code that corresponds to that service quotation.3 RateResponse Output: Service For successful responses. 4. there will be 1-to-M Service nodes returned.doc . for consumers only interested in the total estimate.3. 1.1. and details the local timestamp (based on delivery location) when the shipment will be delivered by.5 RateResponse Output: Charges While the previous section.doc . and the ChargeType is a description of the local charge code description for that charge.6 RateResponse Output: DeliveryTime The DeliveryTime field is provided for each Service.22 - DHL PROPRIETARY AND CONFIDENTIAL . The text in the ChargeType may vary.3. The Currency field will apply for all of the subsequent charges. DHL Customer Web Service Developer Guide V1 0d. depending on locale.DHL Customer Web Service User Guide 4. this section provides line item visibility into the components of that charge. TotalNet. provides a single summary charge. 4. In this context. the sum of the charges communicated in this structure will be equal to the charge in TotalNet.3. /Charges Currency ./Charge (1:M) ChargeType ChargeAmount M O O M M This the currency of the rated shipment for the product listed.23 - DHL PROPRIETARY AND CONFIDENTIAL .doc . DHL Customer Web Service Developer Guide V1 0d.7 Rate Response Output Field List Rate Response fields RateResponse ./Provider "@code" . This is the total prize of the rated shipment for the product listed./Service Mandatory Value /Optional constraints Comments M M M Provider Code. Not used.1.DHL Customer Web Service User Guide 4./Notification "@code" Message ./TotalNet Currency Amount . Error > 0 or Success Code = 0 Response Message. always contains DHL. see Error codes for more details This is the code for the product for which the delivery is feasible respecting the input data from the request. This is the estimated date/time the shipment will be delivered by for the rated shipment and product listed "@type" "@account" DeliveryTime . M This the currency for all line item charges listed in the Charge section M M A description of the line item charge The charge amount of the line item charge.3. doc .2 ShipmentRequest 4. Within the ShipmentRequest.2. The key elements in the response of the Shipment Request will be a base64 encoded PDF label and the Shipment and Piece identification numbers.2 ShipmentRequest: Input The following diagram shows an overview of the request input structure. as both perform similar validations in terms of service capability.DHL Customer Web Service User Guide 4. and optionally book a courier for the pickup of a shipment.2.24 - DHL PROPRIETARY AND CONFIDENTIAL . While the RateRequest and ShipmentRequest services can be used independently. DHL Customer Web Service Developer Guide V1 0d. generate a shipping label.1 ShipmentRequest: Description The ShipmentRequest Operation will allow you to generate an AWB number and piece IDs. The global product codes which are output during the RateResponse can be used directly as input into the Shipment Request. the ClientDetail is an optional node for reference use. DHL recommends the use of RateRequest to first validate the products available for the shipper/receiver. and does not affect functionality. which you can use for tracking on the DHL web site. The critical elements are contained within the RequestedShipment node. transmit manifest shipment detail to DHL. 4. 25 - DHL PROPRIETARY AND CONFIDENTIAL .DHL Customer Web Service User Guide 4.2. DHL Customer Web Service Developer Guide V1 0d.2.2. 4. with context. The Billing and Special Services sub-structures are detailed in below sections. pertaining to operational and billing features.2. and a detailed description of each field follows in the Input Field List.2 ShipmentRequest Input: ShipmentInfo The ShipmentInfo section provides general shipment detail.1 ShipmentRequest Schema Diagram Each of the individual sections of RequestedShipment is shown below in schema diagram.doc . It must either be provided in this field or within the Billing structure (see below).26 DHL PROPRIETARY AND CONFIDENTIAL . Otherwise.2. and these values are used to determine whether a driver pickup will be scheduled as part of this orchestrated service. DHL recommends use of more robust Billing structure. If a pickup is requested (REQUEST_COURIER). no pickup will be scheduled.DHL Customer Web Service User Guide 4.4 ShipmentRequest Input: ShipmentInfo ServiceType The ServiceType is a required field which corresponds to the DHL global product code.5 ShipmentRequest Input: ShipmentInfo Account The Account field is a required business field. This schema structure conveys the Shipper Account Number.3 ShipmentRequest Input: ShipmentInfo DropOffType The DropOffType is a required field with two possible values. 4. but is optional within the schema as this information can be provided in one of two structures. These product codes are available as output from Rate Request. DHL Customer Web Service Developer Guide V1 0d. 4. 4.2.2. and no pickup reference information will be provided in the response. which describes the product requested for this shipment. as well as extensibility to convey receiver or third party account number as payer.2.2.2.doc . and the product codes provided will be validated against the origindestination requested in the Shipment Request.2.2. the first two fields are required. 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.6 ShipmentRequest Input: ShipmentInfo Billing If the Billing structure is included. the web service consumer can expect the optional DispatchConfirmationNumber to be populated in the response. This field is validated as a valid account for usage within this process. such as Insurance (or Shipment Value Protection). respectively.2.10 ShipmentRequest Input: ShipmentInfo Other fields DHL Customer Web Service Developer Guide V1 0d.9 ShipmentRequest Input: ShipmentInfo UnitOfMeasurement The UnitOfMeasurement node conveys the unit of measurements used in the operation.2.2. 4. to support Insurance. respectively.8 ShipmentRequest Input: ShipmentInfo Currency The Currency field is a required field which details the currency for the Customs Value. 4.27 - DHL PROPRIETARY AND CONFIDENTIAL .2. only Insurance service has been activated for use. 4. while the value of ‘SU’ corresponds to LB and IN. For this version of the services.DHL Customer Web Service User Guide 4. The value of ‘SI’ corresponds to KG and CM. the ServiceType would have a value of ‘INS’.7 ShipmentRequest Input: ShipmentInfo SpecialServices The SpecialServices section communicates additional shipping services.2.doc .2. For example. respectively. and the remaining values are included for future use. which the ServiceValue and CurrencyCode containing the insured value and currency. This single value corresponds to the units of weight and measurement used throughout the message processing.2.2. 11 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.2.2. station dropoff. 4. and should not be considered a system event.DHL Customer Web Service User Guide The following fields are optional and not used for specific processing.28 - DHL PROPRIETARY AND CONFIDENTIAL . Please note the ShipmentIdentificationNumber field is reserved for future use to allow consumers to pass their own allocated shipment id (or airbill). Please note that the timestamp for this event does not represent the time of the execution of the service.2. either as part of a scheduled pickup. The SendPackage field is not used. regular pickup. and the schema itself defines the possible enumerated values for this field.2. The PackagesCount field is not used.12 ShipmentRequest Input: PaymentInfo The PaymentInfo node details the potential terms of trade for this specific shipment. DHL Customer Web Service Developer Guide V1 0d.doc . 4. etc. but currently not mapped. The NumberOfPieces field is used to transmit the number of pieces in shipment. DHL Customer Web Service Developer Guide V1 0d. used for manifesting.2. and UnitPrice are field which are available for customs processing.doc .DHL Customer Web Service User Guide 4.2. Depending on the nature of the contents of the shipment.14 ShipmentRequest Input: Content The Content node details whether a shipment contains documents (value DOCUMENTS) or other contents (NON_DOCUMENTS).2. but for validation purposes this information is calculated based on the number of pieces in the message.2. The CountryOfManufacture. The CustomsValue field communicates the customs value of the shipment. 4.29 - DHL PROPRIETARY AND CONFIDENTIAL . The Description field is used as a description of goods for the label and manifest. different products may be offered by the DHL web services.13 ShipmentRequest Input: International Detail The InternationalDetail section conveys data elements for international shipping. Quantity. 15 ShipmentRequest Input: ExportReference An optional field ExportReference exists in the InternationalDetail segment to support the requirement for origin specific export references. DHL Customer Web Service Developer Guide V1 0d. Please note that the Shipper. An example of the node contents is below. receiver and optional pickup address for the specific shipment request. since capability and rate are determined based on city. postal code. such as EEI/ITN reference information required for the US export.30 DHL PROPRIETARY AND CONFIDENTIAL .doc . <ExportReference>AES X20101010123456</ExportReference> 4.2. In the context to rate requests.2.16 ShipmentRequest Input: Ship The Ship section outlines the shipper. the street address elements are not critical.DHL Customer Web Service User Guide 4. Pickup and Recipient structures are identical.2.2. and country code. The Pickup address will not be used in manifesting.17 ShipmentRequest Input: Packages The Packages section details the contents of individual pieces (or discrete shipping containers) within the shipment. The InsuredValue field is an optional field in the Packages section which will be deprecated from the interface. 4. The CustomerReferences field is used as the Piece Reference and the first instance is also used as the Shipment Reference. The minimum number of packages or pieces in a shipment is one and the upper limit is unbounded.31 - DHL PROPRIETARY AND CONFIDENTIAL . The Weight and Dimensions fields represent the weight and dims of the individual pieces.2.doc . Currently only the Shipment Reference appears on the label. as the SpecialServices section should be used to convey Insured Value. DHL Customer Web Service Developer Guide V1 0d.2.DHL Customer Web Service User Guide 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 shipping product requested for this shipment.18 Shipment Request Input Field List Shipment Request fields ShipmentRequest . IN) DropOffType M ServiceType Account Currency M O M AN 1 AN 12 AN 3 UnitOfMeasurement M AN 2 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./ShipmentInfo @provider M/O Values or Constraints Comments O O This field is for internal use only This field is for internal use only O "DHL" Possible values: -REGULAR_PICKUP. The unit of measurement for the dimensions of the package. international metric system (KG.SU.2. Number of packages which need DHL PROPRIETARY AND CONFIDENTIAL ShipmentIdentificationNumber PackagesCount O O N/A N/A . CM) . corresponding to the DHL Global Product codes.2./ClientDetail sso plant .REQUEST_COURIER The rating response returns products for which the pickup capability is given./RequestedShipment . Possible values: .SI. based on ShipmentTimeStamp. The customer account to be used as payer in the request. US system of measurement (LB. the pickup location is already served by a regular courier and an additional pickup does not need to be considered for this service .DHL Customer Web Service User Guide 4.doc . UK. The currency of the monetary values presented in the request.32 - DHL Customer Web Service Developer Guide V1 0d. /SpecialServices .33 - Possible Values . Possible values: . AN 3 The DHL account number used for the shipment./Service ServiceType ServiceValue CurrencyCode PaymentCode O N/A M O O O AN3 15.INS (Insurance) Monetary value of service (e. if ShippingPaymentType is equal to R or T. Sunday or any other day where there is no pickup.g.DHL Customer Web Service User Guide to be processed. It needs to be provided in the following format with GMT offset YYYY-MM-DDTHH:MM:SS GMT+k 2010-02-26T17:00:00 GMT+01:00 If the date is on a public holiday. Insured Value) Currency code For future use.R (use BillingAccountNumber as bill-to receiver account number) . the rate YYYY-MMrequest will return this in the DDT24HH:MM:S error code as it is a non valid S GMT+k request. DHL PROPRIETARY AND CONFIDENTIAL DHL Customer Web Service Developer Guide V1 0d. SendPackage O N/A This timestamp identifies the pickup date and time of the rated shipment./Billing M M ShipperAccountNumber O N/A ShippingPaymentType O AN1 BillingAccountNumber .3 D AN3 AN3 .doc .S (use ShipperAccountNumber as payer) . Used as the shipper account number. ShipTimestamp PaymentInfo .T (use BillingAccountNumber as bill-to third party account number) The DHL account number used for the shipment. 3 D Content ExportReference . In case of questions.doc .NON_DOCUMENTS Export Reference field.DOCUMENTS . The country of manufacture of the content of the shipment./Address M O AN 25 N/A A contact name of a person who will ship the shipment. Possible values . appears on label.34 - DHL Customer Web Service Developer Guide V1 0d. e. The company name the person is working in.50 € if one of the books costs 7.50€. M M AN 45 AN 35 PhoneNumber EmailAddress . 7.3 D 18. Shipper street number should be sent as separate attribute.g. 3 books./Ship . M M O O N6 AN 1-35 AN 2 N 10 UnitPrice CustomsValue O O 18./InternationalDetail ./Commodities NumberOfPieces Description CountryOfManufacture Quantity O O O Date Date AN50 For future use. The quantity of the items in the shipment./Contact PersonName CompanyName O O N/A AN40 The number of pieces in the shipment The description of the content of the shipment. Shipper street name should be sent as separate attribute if feasible. if feasible./Shipper .DHL Customer Web Service User Guide StartDate EndDate TextInstruction . The value which needs to be declared for customs. The street line should contain street name and number of the shipper. The contact person phone number. Shipper additional address information Shipper additional address DHL PROPRIETARY AND CONFIDENTIAL StreetLines M AN 35 StreetName O AN 35 StreetNumber StreetLines2 StreetLines3 O O O AN 15 AN 35 AN 35 . this person can be called by the courier. For future use. e. The email address of the contact person. Price per item in the shipment.g. For future use. /Address M O AN 25 N/A A contact name of a person who will receive the shipment. Pickup additional address information Pickup additional address information Pickup city name Pickup State or Province Pickup postal code ISO 2 character codes of the Pickup country. The email address of the contact person./Contact PersonName CompanyName M O M M AN 35 AN 35 AN 12 AN 2 information Shipper city name Shipper State or Provice Shipper postal code ISO 2 character codes of the Shipper country. M M AN 45 AN 35 PhoneNumber EmailAddress ./Pickup . The contact person phone number. The company name the person is working in. Pickup street name should be sent as separate attribute if feasible. The street line should contain street name and number of the pickup location./Address M O AN 25 N/A A contact name of a person who will receive the shipment.DHL Customer Web Service User Guide City StateOrProvinceCode PostalCode CountryCode . this person can be called by the courier. Pickup street number should be sent as separate attribute. The email address of the contact person.doc . The contact person phone number. StreetLines StreetName M O AN 35 AN 35 StreetNumber StreetLines2 StreetLines3 City StateOrProvinceCode PostalCode CountryCode . DHL Customer Web Service Developer Guide V1 0d.35 - DHL PROPRIETARY AND CONFIDENTIAL ./Recipient . this person can be called by the courier. if feasible. In case of questions./Contact PersonName CompanyName O O O M O M M AN 15 AN 35 AN 35 AN 35 AN 35 AN 12 AN 2 M M AN 45 AN 35 PhoneNumber EmailAddress . The company name the person is working in. In case of questions. Insurance values of the package.1 D 5. the DHL Customer Web Service Developer Guide V1 0d. Height of the piece listed.doc . Recipient street number should be sent as separate attribute./Packages (1:1) .36 - DHL PROPRIETARY AND CONFIDENTIAL . M O M M M M M Integer N/A 15. Recipient street name should be sent as separate attribute if feasible. if feasible. Customer Reference for piece. Length of the piece listed.DHL Customer Web Service User Guide StreetLines M AN 35 StreetName O AN 35 StreetNumber StreetLines2 StreetLines3 City StateOrProvinceCode PostalCode CountryCode .1 D AN 1-35 Running number of the packages.3 D 5./Dimensions Length Width Height CustomerReferences O O O M O M M AN 15 AN 35 AN 35 AN 35 AN 35 AN 12 AN 2 The street line should contain street name and number of the reveiver.1 D 5. The weight of the package. Width of the piece listed. Recipient additional address information Recipient additional address information Recipient city name Recipient State or Province Recipient postal code ISO 2 character codes of the Receiver country./RequestedPackages (1:M) @number InsuredValue Weight . with context. Successful messages will include a zero error code and no corresponding message.DHL Customer Web Service User Guide 4. and the optional pickup confirmation reference. based on the results of the processing. and a detailed description of each field follows in the Output Field List. 4.3. The critical information to derive from this response are the notification codes for the response.doc .2. while exceptions have both code and message. the shipment and piece identifiers returned.3 ShipmentRequest: Output The following diagram shows an overview of the shipment response structure. DHL Customer Web Service Developer Guide V1 0d. 4. the encoded label image.2 ShipmentResponse Output: Notification The Notification structure includes the result code and message.37 - DHL PROPRIETARY AND CONFIDENTIAL .2.1 ShipmentResponse Schema Diagram Each of the individual sections of ShipmentResponse is shown below in schema diagram.3.2. 2. The HTML Image is not used. and is the DHL primary reference field in calling application. 4.2.4 ShipmentResponse Output: LabelImage The Label Image section of the response provides the label format in the LabelImageFormat field (i.doc . of which there can be many. if requested.6 ShipmentResponse Output: DispatchConfirmationNumber This field is the confirmation number generated by the creation of a pickup. In order to tie the RequestedPackages from the ShipmentRequest with the PackageResult in the response.e.3 ShipmentResponse Output: PackagesResult The PackagesResult provides the DHL piece ID associated to each RequestedPackage from the ShipmentRequest. PDF).3. This is the primary tracking identifier within DHL.DHL Customer Web Service User Guide 4.2.3. as it is a required field. the @number attribute can be used to referentially link the request and result packages. as well as the base64 encoded label image in the GraphicImage field. This data will need to be persisted if the web service consumer intends to utilize the DeleteShipment functionality. the TrackingNumber is the Piece ID returned from the service.2. 4. In this case.3. 4.38 DHL PROPRIETARY AND CONFIDENTIAL . DHL Customer Web Service Developer Guide V1 0d. The TrackingNumber field is the identifier for that specific piece of the shipment.3.5 ShipmentResponse Output: ShipmentIdentificationNumber This field corresponds to the airbill number associated to this shipment. doc .39 - DHL PROPRIETARY AND CONFIDENTIAL .DHL Customer Web Service User Guide DHL Customer Web Service Developer Guide V1 0d. 40 - DHL PROPRIETARY AND CONFIDENTIAL . The booking reference number./PackageResult "@number" Values or Constraints Comments M M N6 Error > 0 or Success Code = 0 Response Message.2./PackagesResult .DHL Customer Web Service User Guide 4. Currently always AN 3 “PDF” This field contains the actual label as Base64 Binary.3. LabelImageFormat O GraphicImage HTMLImage O O ShipmentIdentificationNumber O DispatchConfirmationNumber O Mapped from Request Document. This field contains a unique number for the individual package./LabelImage O AN 35 Running number of the packages. This number should be used when interacting with the DHL customer service AN 15 regarding the pickup process.7 Shipment Response Output Field List Shipment Response xml fields Mandatory/ (Source) Optional ShipmentResponse . There will be one document containing all the labels for each package/piece on Base64 Binary separate pages. Base64 Binary Not used The shipment identification number also named airwaybill (AWB). DHL Customer Web Service Developer Guide V1 0d./Notification @code Message .doc . see Error codes for more details O Integer TrackingNumber . This number can be used to track the progress of the shipment on the DHL AN 35 webside. 2 ShipmentDeleteRequest: Input The following diagram shows an overview of the request input structure. The DispatchConfirmationNumber is the reference value which was in the original ShipmentResponse for DispatchConfirmationNumber. If a scheduled pickup was not included in the original ShipmentRequest (i. if the ShipmentTimestamp for the successful shipment was “2010-11-30T12:30:47GMT+01:00”. DHL Customer Web Service Developer Guide V1 0d. previously communicated as part of the ShipmentTimestamp of the ShipmentRequest. DropOffType = REGULAR_PICKUP). if included in the original request.DHL Customer Web Service User Guide 4.3 4. then it is not necessary to delete the shipment.doc . The PickupCountry is the two character country code which was used in the original request. 4.1 ShipmentDeleteRequest 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. Within the DeleteRequest. This value is not validated against the original request.3. but will not become an active shipment if the shipment label does not enter the DHL Network. For example. then the PickupDate would be “2010-11-30”. Any shipment manifest data which was included in the original ShipmentRequest will not be deleted as part of this operation.e. and can be defaulted if necessary. and does not affect functionality. The critical elements are the remaining nodes in the request. The PickupDate is the day of the scheduled pickup. but is not validated against the original ShipmentRequest.41 - DHL PROPRIETARY AND CONFIDENTIAL . The RequestorName is a required field.3. the ClientDetail is an optional node for reference use. The country code associated to the origin of the shipment./ClientDetail sso plant 4.2. Reason 001 002 003 004 005 006 007 008 Value Package Not Ready Rates Too High Transit Time Too Slow Take To Service Center or Drop Box Commitment Time Not Met Reason Not Given Other Pickup Modified 4.3.3.doc .42 - DHL PROPRIETARY AND CONFIDENTIAL . Value of 7 (“Other”) used in the absence of transmitted data. and used to indicate the reason for the cancellation.DHL Customer Web Service User Guide The Reason value is an optional field.1 Shipment Request Input Field List ShipmentDeleteRequest fields DeleteRequest PickupDate PickupCountry Mandatory Value /Optional constraints Comments YYYY-MMDD M M AN2 DispatchConfirmationNumber RequestorName Reason . The delete requestor name Optional reason code (see above table) O O This field is for internal use only This field is for internal use only DHL Customer Web Service Developer Guide V1 0d. The possible values are included in the table below.3 ShipmentDeleteRequest: Output M M O AN20 AN45 AN50 The scheduled pickup date of the shipment to be deleted. The confirmation number returned from the original shipment request. 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).DHL Customer Web Service User Guide 4.doc . for the 3rd use case.1 ShipmentDeleteRequest Output field list ShipmentDeleteResponse fields DeleteResponse . see Error codes for more details For this service. the potential error use cases include • Pickup Not Found./Notification @code message Mandatory Value /Optional constraints Comments M M Error > 0 or Success Code = 0 Response Message.43 - DHL PROPRIETARY AND CONFIDENTIAL . DHL Customer Web Service Developer Guide V1 0d. if already deleted • Pickup Not Found.3.3. During this time. if still in process of creation Please note. it may not be possible to delete the pickup request. if manually deleted otherwise • Pickup Not Found. Please check the country code. Please check the country code. 3003 The origin city name could not be found please check the city name. The errors are broken down into categories for presentation. 3001 The location country code could not be found please check the location country parameter. destination. field format.1.1 Appendix Rate Request and Shipment Request Error codes and messages The following table contains the possible error for the Rate and Shipment Request processes. Condition met if no products are available for origin. 3013 The shipment weight is not with the restrictions for the selected country. 1003 Pick-up service is not provided on this day. 3007 The destination city name could not be found please check the destination city name.1 Capability and Quotation Errors For capability and quotation error codes. 3006 The destination zip code could not be found please check your destination zip code parameter.DHL Customer Web Service User Guide 5 5. etc). Please check your piece DHL Customer Web Service Developer Guide V1 0d. 5. some errors are not possible to achieve based on schema validation (for required fields. Capability and Quotation Errors (Rate and Shipment Requests) Error Error Text Code 996 The requested product(s) not available based on your search criteria. 3004 The origin service area code could not be found please check the origin service area code. 1001 The requested product(s) not available based on your search criteria. 3010 The format of the ready time is not correct.44 - Notes (if applicable) Condition met if no products are available for that pickup date/time. 3002 The origin zip code could not be found please check your origin zip code parameter. 3000 The origin country code could not be found.doc . 3005 The destination country code could not be found. Condition met for non-postal code countries only Condition met for non-postal code countries Condition is covered under “1001” error if restrictions DHL PROPRIETARY AND CONFIDENTIAL . Please check the time format. 3008 The destination service area code could not be found please check the destination service area code. 3014 The shipment height is not with the restrictions for the selected country. Please check your width/diameter 3018 The payment country could not be found please check your payment country. 3015 The shipment length is not with the restrictions for the selected country. 5003 The origin city name is missing. 6000 Unexpected application error Condition is covered under “1001” error if restrictions not met Condition is covered under “1001” error if restrictions not met DHL Customer Web Service Developer Guide V1 0d. 5100 Invalid product service combination. Please check your piece length. 5038 The combination unit of weight and dimension is invalid. 5025 Sorry the maximum weight is 50kg or 110lbs. Please check your piece height. 5009 The pickup date is missing. not met Condition is covered under “1001” error if restrictions not met Condition is covered under “1001” error if restrictions not met Condition is covered under “1001” error if restrictions not met Returns "6000-Unexpected application error" Confirmed. for non-postal code countries 5026 Sorry the maximum dimensions are 118x88x120cm or 46x35x47ins. The city name for the selected country is mandatory. Please call customer service for special handling. The zip code for the selected country is mandatory. 3022 The origin postcode does not provide standard pick up. 5006 The destination zip code is missing. (LxWxH) 5027 Sorry the input declared value cannot exceed the limit for this country. 3016 The shipment width/diameter is not with the restrictions for the selected country.45 - DHL PROPRIETARY AND CONFIDENTIAL . for non-postal code countries C Confirmed. Please call customer service for special handling.doc . 3023 The destination postcode does not provide standard delivery. The city name for the selected country is mandatory. This is a mandatory input parameter. 5007 The destination city name is missing. The zip code for the selected country is mandatory. 5110 Optional service not applicable. 5001 The origin country code is missing. 5002 The origin zip code is missing. The pickup date is a mandatory field.DHL Customer Web Service User Guide weight. 3 Shipment Date Validation For the Shipment service only. Notes (if applicable) 5. 5. Please check the shipment date and retry.1. Please check the account number and retry. the route code is required for most EU countries. the ShipmentTimestamp is validated to ensure the proposed shipment date is not in the past.4 Account Validation For both Rate and Shipment. Account Validation Errors (Rate and Shipment Requests) Error Error Text Code 998 The account number is not found or invalid.doc . and within 10 days of current date. so error handling for that lookup will only be active for those cases. the account number must be valid and configured for use within the services.2 Route Code Errors For the Shipment service only. please see your DHL integration point of contact. For help for account setup and configuration. The specific use case is the scenario where the route code value is not found for the origin address. Shipment Date Errors (Shipment Requests Only) Error Error Text Code 998 The shipment date cannot be in the past or more than 10 days in future.1.46 - DHL PROPRIETARY AND CONFIDENTIAL .DHL Customer Web Service User Guide 5. Route Errors (Shipment Requests Only) Error Error Text Code 400501 Route Code not found for <address> Notes (if applicable) Condition met if no products are available for that pickup date. Notes (if applicable) DHL Customer Web Service Developer Guide V1 0d.1. doc .DHL Customer Web Service User Guide 5. 30002 Invalid postcode format.47 - DHL PROPRIETARY AND CONFIDENTIAL . 90001 Unclassified error. Label Generation Errors (Shipment Requests only) Error Error Text Code 20001 Neither local nor Network Product Code is present. Notes (if applicable) DHL Customer Web Service Developer Guide V1 0d.5 Label Generation Errors For Shipment service. 90002 Invalid XML. 20004 Destination country code is absent. 20017 Neither destination postcode nor destination code is present. the following errors may occur during label generation. 30001 Maximum length of local specific code exceeded. 40004 Destination code is not found 50003 More than one destination service area codes are found. 90003 Error while accessing the cache. 99999 GLS servers are not reachable. 40001 Product short name is not found. 20003 Origin service area code is absent. 20002 Origin country code is absent. 40002 Product content code is not found.1. Account number or account type is some type of external billing account. Routing Service could not determine Origin Service Area. Booking adapter error response failure PU003.7 Pickup Errors For select Shipment requests. the following errors may occur during processing of the pickup.6 Manifest Submission Errors For Shipment service. No pickup scheduled Booking adapter error response failure PU007a.1. Shipment Manifest Errors (Shipment Requests only) Error Error Text Code 400201 Failure during booking 400202 Missing field(s)".1. 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. Each of the pickup adaptor errors below carries the same Error Code. Pickup Errors (Shipment Requests only) Error Error Text Code 410928 Booking adapter error response failure PU009a. Account number specified has a credit status of DHL Customer Web Service Developer Guide V1 0d. which include a pickup request (REQUEST_COURIER).48 - Notes (if applicable) DHL PROPRIETARY AND CONFIDENTIAL .doc . Pickup Service requires a domestically billed shipper account. No pickup scheduled Booking adapter error response failure PU004.DHL Customer Web Service User Guide 5. Account number is not found in IBS records. No pickup scheduled Booking adapter error response failure PU005. 'Pickup NOT scheduled. Notes (if applicable) 5. There is no weekend pickup service at the location. the following errors may occur during submission of the shipment manifest. Ready by time is past the station ready by cutoff of <x>. A business pickup requires one hour. Insufficient time between pickup request time and pickup end time. No pickup scheduled Booking adapter error response failure PU009c. The pickup request time is less than 1 hour of the station pickup end time.DHL Customer Web Service User Guide CUT. The Pickup Ready-by time from the client is before the Station Pickup start time or after the Station Pickup end time. Booking adapter error response failure PU012. No pickup scheduled Booking adapter error response failure PU011a. No pickup scheduled. 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. These error messages also contain a process id number. Booking adapter error response failure PU013b. and (closing time). No pickup scheduled Booking adapter error response failure PU012. A residence pickup requires two hours.8 General Errors Unexpected errors are handled with a standard error message. Booking adapter error response failure PU013a. No pickup scheduled. No pickup scheduled. Shipment Date Errors (Shipment Requests Only) Error Error Text Code 998 Process failure occurred. Ready by time is past the station ready by cutoff of <x>. Booking adapter error response failure PU011b. 5. Pickups require at least one hour before station pickup end time. Directed to IBS. Booking adapter error response failure PU012. Process ID associated for that transaction (9999999) DHL Customer Web Service Developer Guide V1 0d.49 - Notes (if applicable) Where 9999999 is the process id DHL PROPRIETARY AND CONFIDENTIAL . No pickup scheduled Booking adapter error response failure PU009b. No pickup scheduled Booking adapter error response failure PU007b. Insufficient time between (current time).1. No pickup scheduled. which is used during troubleshooting or follow-up. The pickup date is a holiday at (origin service area). Ready by time is past the station ready by cutoff of <x>. Sufficient notice not provided.doc . The pickup date is a weekend at the origin service area that has no pickup service. At least one day of advance notice is required for pickup at <location>. 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> <PaymentInfo>DDU</PaymentInfo> <Account>999999999</Account> </RequestedShipment> </RateRequest> 5. QINGDAO SHI</StreetLines> <City>QINGDAO SHI</City> <PostalCode>266033</PostalCode> <CountryCode>CN</CountryCode> </Recipient> </Ship> <Packages> <RequestedPackages number="1"> <Weight> <Value>2. Minami-gyotoku</StreetLines> <City>Ichikawa-shi.doc .DHL Customer Web Service User Guide 5.50 - DHL PROPRIETARY AND CONFIDENTIAL .2.2.2 5.1 Service Input/Output Examples for RateRequest RateRequest: Sample Input <RateRequest> <ClientDetail> </ClientDetail> <RequestedShipment> <DropOffType>REQUEST_COURIER</DropOffType> <Ship> <Shipper> <StreetLines>1-16-24.2 RateRequest: Sample Output <rateresp:RateResponse> <Provider code="DHL"> <Notification code="0"> <Message/> </Notification> <Service type="8"> <TotalNet> <Currency>JPY</Currency> <Amount>20475. Chiba</City> <PostalCode>272-0138</PostalCode> <CountryCode>JP</CountryCode> </Shipper> <Recipient> <StreetLines>63 RENMIN LU.00</ChargeAmount> </Charge> DHL Customer Web Service Developer Guide V1 0d.00</Amount> </TotalNet> <Charges> <Currency>JPY</Currency> <Charge> <ChargeType>EXPRESS EASY</ChargeType> <ChargeAmount>17500. doc .DHL Customer Web Service User Guide <Charge> <ChargeType>FUEL SURCHARGE</ChargeType> <ChargeAmount>2975.51 - DHL PROPRIETARY AND CONFIDENTIAL .00</ChargeAmount> </Charge> </Charges> <DeliveryTime>2010-12-02T23:59:00</DeliveryTime> </Service> </Provider> </rateresp:RateResponse> 5.00</ChargeAmount> </Charge> </Charges> <DeliveryTime>2010-12-02T23:59:00</DeliveryTime> </Service> <Service type="P"> <TotalNet> <Currency>JPY</Currency> <Amount>20569.00</ChargeAmount> </Charge> <Charge> <ChargeType>FUEL SURCHARGE</ChargeType> <ChargeAmount>2989.00</Amount> </TotalNet> <Charges> <Currency>JPY</Currency> <Charge> <ChargeType>EXPRESS WORLDWIDE</ChargeType> <ChargeAmount>17580.2.3 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> DHL Customer Web Service Developer Guide V1 0d. [email protected] DHL PROPRIETARY AND CONFIDENTIAL .doc [email protected]/2001/XMLSchema-instance"> <shipreq:ShipmentRequest> <RequestedShipment> <ShipmentInfo> <DropOffType>REQUEST_COURIER</DropOffType> <ServiceType>U</ServiceType> <Account>950177913</Account> <Currency>EUR</Currency> <UnitOfMeasurement>SI</UnitOfMeasurement> <PackagesCount>1</PackagesCount> </ShipmentInfo> <ShipTimestamp>2010-10-29T09:30:47GMT+01:00</ShipTimestamp> <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.w3.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.3 5.0" encoding="UTF-8"?> <ShipmentRequest xsi:noNamespaceSchemaLocation="ShipmentMsgRequest.3.de</EmailAddress> </Contact> <Address> <StreetLines>Via Felice Matteucci 2</StreetLines> <City>Firenze</City> <PostalCode>50127</PostalCode> <CountryCode>IT</CountryCode> </Address> </Recipient> DHL Customer Web Service Developer Guide V1 0d.DHL Customer Web Service User Guide 5.1 Service Input/Output Examples for ShipmentRequest ShipmentRequest: Sample Input <?xml version="1.xsd" xmlns:xsi="http://www. dhl.phxdc.3.DHL Customer Web Service User Guide </Ship> <Packages> <RequestedPackages number="1"> <InsuredValue>10</InsuredValue> <Weight>9. Process ID associated for that transaction (8614)</Message> </Notification> </ShipmentResponse> DHL Customer Web Service Developer Guide V1 0d.2 ShipmentRequest: Sample Output <ShipmentResponse xmlns:shipresp="http://scxgxtt.(8614)</Message> </Notification> <Notification code="998"> <Message>Process failure occurred.3 ShipmentRequest: Sample request with error <ShipmentResponse xmlns:shipresp="http://scxgxtt.0</Weight> <Dimensions> <Length>46</Length> <Width>34</Width> <Height>31</Height> </Dimensions> <CustomerReferences>TEST CZ-IT</CustomerReferences> </RequestedPackages> </Packages> </RequestedShipment> </shipreq:ShipmentRequest> 5.53 - DHL PROPRIETARY AND CONFIDENTIAL .com/euExpressRateBook/ShipmentMsgResponse"> <Notification code="1001"> <Message>The requested product(s) (X) not available based on your search criteria.doc .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> 5.phxdc.3.dhl. 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> 5.4.0" encoding="UTF-8"?> <delresp:DeleteResponse> <Notification code="410928"> <Message>Cancellation of booking was not successful. Requested Pickup was not found.1 Service Input/Output Examples for ShipmentDeleteRequest ShipmentDeleteRequest: Sample Input <?xml version="1.3 ShipmentDeleteRequest: Sample request with error <?xml version="1.4 5.0" encoding="UTF-8"?> <delresp:DeleteResponse> <Notification code="0"> <Message>Successfully cancelled</Message> </Notification> </delresp:DeleteResponse> 5.DHL Customer Web Service User Guide 5.54 - DHL PROPRIETARY AND CONFIDENTIAL .4.4.2 ShipmentDeleteRequest: Sample Output <?xml version="1.doc .</Message> </Notification> </delresp:DeleteResponse> DHL Customer Web Service Developer Guide V1 0d. org/ W3 Schools XML Tutorial.55 - DHL PROPRIETARY AND CONFIDENTIAL .asp Java Technology and Web Services.com/webservices/ Apache Web Services Project. Organization for the Advancement of Structured Information Standards (OASIS) http://www.Org Home Page.5 Helpful XML and Web Services XML.sun.xml. Inc.w3schools.apache. Reference Data http://www. Sun Microsystems.asp DHL Customer Web Service Developer Guide V1 0d.org/ W3 Schools Web Services Tutorial.com/webservices/default. Reference Data http://www.com/xml/default. http://java.w3schools.DHL Customer Web Service User Guide 5. The Apache Software Foundation http://ws.doc .
Report "DHL Customer Web Service Developer Guide V1 0d"