API Developer Guidelines

DPD Shipper Webservice API

DPD Shipper Webservice is an API service provided by DPD Belux (referred to below as “DPD“). The service is available via the internet and is only available to customers of DPD Belgium and Luxemburg. Credentials are needed to access the service. Just like any other internet-based application, maintaining its stability in performance is very important. In order to do so, certain key  rules must be followed.

The following guidelines explain these important rules when using the DPD Shipper Webservice  and serve as a quick overview. Failure to adhere to these guidelines will trigger DPD issued warnings and may even  result in an application ban. These guidelines do not replace the existing terms of use.

GENERAL INFORMATION – 2

•                 Live and Stage environments                                                                                                                     
•                 Use of different API credentials                                                                                                                
•                 Services and endpoints for SOAP                                                                                                             
•                 Lifetime of service endpoints                                                                                                                     

LOGIN SERVICE – 3

•                 Generating only one authentication token per day                                                                            
•                 Automating the process of calling the login service                                                                           

SHIPMENT SERVICE – 3

•                 Shipment service API calls must be done in a sequential manner                                                
•                 The limit for each account is 30 shipment service calls per minute                                              
•                 Correct address labelling is key for successful delivery                                                                      

PARCELSHOP FINDER SERVICE  – 4                                                                                                                      

•                 Retrieving up-to-date DPD Pickup parcelshops in E-commerce Checkouts                                 
•                 Storing the ID including the full address with each client order                                                       

PARCEL LIFE CYCLE SERVICE – 5

•                 Terms of use: For on-demand track and trace purposes only                                                             
•                 Valid tracking numbers consist of exactly 14 numeric digits                                                               
•                 The parcel life cycle service cannot be used for bulk requests                                                             

API CALL LIMIT – 6

•                 The maximum possible API call limit for each service                                                                           

ADDITIONAL INFORMATION – 6

•                 Current specifications, endpoints and URLs                                                                                                
•                 Each development using the DPD Shipper API service must be validated                                       
•                 Contacting the DPD Customer IT team for further information                                                          

General information

Each application must be able to differentiate between Live and Stage environment

• The Stage environment must be used for development and testing purposes only. Shipments made in the Stage environment will not be treated by DPD and the labels created will not be valid.
• The Live environment must be used for production purposes only.

Each application implementing the DPD Shipper Webservice must be able to switch between both environments. The environments are distinguished by their base URL:

Stage and prod environments use different API credentials

Hence a different username password combination applies.

Different availabilities for SOAP on Stage and Live

Different endpoints

Please visit our development portal to obtain all available endpoints, last update as well as specifications.

• Shipper Webservice Archives – BE (dpd.be)
• WSDL’s – BE (dpd.be)

The website provides up-to-date documentation and code examples.

There is no fixed lifetime for any service endpoint

DPD did not determine a fixed interval or a specific lifetime for any of the services provided by DPD Shipper Webservice. However, due to technical changes, new product developments, bug fixing as well as enhanced performance it is possible that DPD will release a new service endpoint version. DPD reserves the right to phase out older service versions. The end of life of each service will be announced in due time, per service. Adjustments to a new service endpoint version will be mandatory and can result in additional changes and development effort for a user.

Login service/Shipment service

Generating only one authentication token per day

To protect each account and password, an authentication token must be generated via the login service. This token is used in all following API calls. Each token is valid for one business day CET / CEST and must be cached.

• Calling the login service more than 10 times a day is prohibited.
• Calling the login service in combination with each shipment service, parcel life cycle service or parcelshop finder service is specifically prohibited.

Exception:

Once the authentication has expired, every DPD Shipper Webservice service will provide a corresponding errorCode:

• LOGIN_5 The authentication token is invalid
• LOGIN_6 Your session has expired

If these errorCodes are received by any of the DPD Shipper Webservice services, it is mandatory to make a login service call and cache a new authentication token.

 The process of calling the login service may be automated

Every token will become invalid 24 hours after it has been generated. A good time to call the login service and generate a new authentication token is 24 hours and a few seconds after the first request was made. The next login service call can take plake 24 hours+ later.

Shipment service

All shipment service API calls must be done in a sequential manner

Only a single API request at a time is permitted. Only when the service has responded to the initial API call, a new API call can be sent.

• Sending multiple shipment service calls at the same time is prohibited.

When using more than one IP address, e.g. a load balancing cluster, please ensure no API calls are being sent simultaneously.

Failure to do so can cause an application ban.

The limit for each account is 30 shipment service calls per minute

Generating one shipping label takes on average about 1 second per label. Working in a safe sequential manner, including a buffer of 100% therefore gives a limit of 30 shipping labels per minute or 1,800 per hour. Exceeding this limit may cause a warning and even result in an application ban.

Correct address labelling is key for successful delivery!

The shipment service provides the following address fields which are being printed on the shipping label:

• name1
• name2
• contact
• street
• houseNo
• phone
• country
• zipCode
• city

Parcel finder service

During the checkout of a shipment to a Parcelshop an up-to-date list of available DPD Pickup parcelshops must be requested

This service is mandatory for shipments which are being shipped directly to a DPD Pickup parcelshop. The service is designed for e-commerce businesses and must be implemented into the checkout process to make sure only available shops are being used, since the list of available shop can very day by day.

More details on how to properly request a list of Parcelshops can be found on our Shipment page in section 5.

Every response will contain multiple DPD Pickup parcelshops nearby. Each parcelshop is identified via a unique ID, the so-called parcelshop id. Also, the shop address as well as geographical coordinates (latitude and longitude) are provided. These coordinates can be used for an additional maps service integration. A maps service integration must take place separately.

It is important to store the ID including the full address with each client order

The parcelshop ID and address which has been stored with each order

must later be used to create the corresponding DPD shipping label. You must save the DPD parcelshop data which has been accessed only for the length of time required for the processing of the order and not connect such data with the data of other shipments.

As a prerequisite for the use of the DPD Shipper Webservice, you are not allowed to create any automated queries using programs, scripts, robots or similar tools or to build or use any tool aimed at extracting or collecting large volumes of data.

Parcel life cycle service

Simplified tracking events to be used for on-demand track and trace purpose only

This service is designed for real-time tracking applications which need on-demand track and trace information. Each tracking request must be executed by a real user, a customer or a customer service employee. The service will provide the current tracking status of each parcel requested.

A valid tracking number exists of exactly 14 numeric digits The parcel life cycle service must not be used for mass processing or bulk requests in any way

As a prerequisite for the use of the DPD Shipper Webservice, you are not allowed to create any automated queries using programs, scripts, robots or similar tools or to build or use any tool aimed at extracting or collecting large volumes of data.

In need of more detailed tracking information? Want to keep track of your entire shipping volume?

Our EDI file exchange is your best option for mass tracking, including a high level of transparency with all available track and trace details. For more information, please contact us and we will provide you with the documentation of SCANINFO.

API call limit / Additional information

API call limit

The maximum possible API call limit for each service are as follows:

These limits must be adhered to, failing to do so can cause a ban from the system.

Separate approval is required for the extended API limits. Obtaining such an approval is a manual process and you must contact DPD Customer IT to apply for extended API usage. Please find the contact details below.

Rate limiting

Rate limiting will apply to all services and environments. An excess in number of calls will result in a temporary suspension (error 429 – Too many requests). This limitation is implemented at account and IP level.

Additional information

Current specifications, endpoints, URLs can be found within our development portal

• Shipper Webservice Archives – BE (dpd.be)

The website provides up-to-date documentation and code examples.

Each development using the DPD Shipper Webservice service must be validated and approved by DPD

This validation is mandatory to get started with the DPD Shipper Webservice service.

In order to gain access to the production environment, the correct handling, the implemented services themselves as well as products must first be tested and validated.

Contacting the DPD Customer IT team for further information

A team of specialists will assist your API integration to ensure an easy, flawless and quick start of your project.

Contact us at it.cs@dpd.be

Important legal notice when using the Shipper API stage environment:

Shipment data submitted on the stage environment (storeOrders endpoint at https://shipperadmintest.dpd.be/PublicApi/soap/WSDL/ShipmentServiceV33.wsdl) is prone to GDPR, Data and Security regulations. We are storing your requests for a reasonable amount of time to perform metrics and analysis. The environment is also used for internal testing and training purposes and thus has a privacy sensitivity factor. You are responsible for anonymising your requests in case your data is privacy sensitive or if you have certain agreements with third parties that enforce you to this level of privacy.

Please (manually) alter sender/receiver names, phone numbers, e-mail addresses and other references to a non-recognisable form in your requests to guarantee anonymity (by ex. “Test Sender”, “Stage Recipient”, “+32400000000”, “onlineorder123@gmail.com”)