Pickup Delivery service

Pickup delivery service allows delivering your parcels to a collection place based on the receiver’s needs. You would need to integrate Pickup finder into your e-shop to allow your customers to choose a proper place of collection. There are several possibilities how to do it described in this document.

INTEGRATION POSSIBILITIES

Implementation of DPD widget into your e-shop (recommended)

The following information is rather technical and is intended primarily for your IT department or administrator of your e-shop

Demo application of our widget can be found here:

https://api.dpd.cz/widget/latest/demo.html

Alternatively, the raw version:

https://api.dpd.cz/widget/latest/index.html

How to implement the widget

To display the widget on your website, please paste iframe into the code with the address: https://api.dpd.cz/widget/latest/index.html

  <iframe
    src="https://api.dpd.cz/widget/latest/index.html"
  ></iframe>

To obtain a user-selected Pickup point or box, insert input into the code (ideally hidden) with id: DPDPickupPointResult, where the ID of the Pickup point/box and its full address are displayed when selecting the particular Pickup point/box.

  <input id="DPDPickupPointResult" type="hidden"/>

For a more complex implementation, it is possible to listen to the event (DPDPickupPointSubmit) on the object document, which returns the complete object of the Pickup point in path event.data.dpdWidget:

  window.addEventListener("message", (event) => {
    if(event.data.dpdWidget) {
      console.log(event.data.dpdWidget);
    }
  }, false);

If you want to have the option to close the widget, an event (DPDPickupPointClose) is also sent about the click on the cross (if the user tries to close the widget), you have to verify you received the correct message by (event.data.dpdWidget.message === “widgetClose”:

  window.addEventListener("message", (event) => {
    if(event.data.dpdWidget && event.data.dpdWidget.message === "widgetClose") {
      console.log("DPD pickup point widget is closed")
    } 
  }, false);

To display the widget without close button, it is necessary to set the query parameter hideCloseButton to true

  <iframe
    src="https://api.dpd.cz/widget/latest/index.html?hideCloseButton=true"
  ></iframe>

To display the widget only with Pickup points without DPD boxes, it is necessary to set the query parameter disableLockers to true

  <iframe
    src="https://api.dpd.cz/widget/latest/index.html?disableLockers=true"
  ></iframe>

To preset one of the available countries, use the ?countries= parameter, for example:

  <iframe
    src="https://api.dpd.cz/widget/latest/index.html?countries=SK"
  ></iframe>

To limit displayed countries, use parameter ?enabledCountries=, for example:

  <iframe
    src="https://api.dpd.cz/widget/latest/index.html?enabledCountries=CZ&enabledCountries=SK"
  ></iframe>

Other types of integration

Notice:

We have extended our network by adding Pickup Points abroad. Currently, it is not allowed to send cash on delivery parcels to Pickup Points abroad. Please respect this restriction. If the customers select the Pickup Point abroad, do not allow them to select the cash on delivery as a payment method. All outputs of methods are now extended by a cod_allowed field which enables you to verify if the option of sending a parcel with a cash on delivery payment method is allowed or not.

cod_allowed = 0 – cash on delivery not allowed
cod_allowed = 1 – cash on delivery allowed

We have added a crossboarder parameter to methods which are designed for a direct integration into the Order Form. This parameter is used to limit the display of Pickup Points as follows:

Parameter not used – the resulting methods are limited only to Pickup Points in the Czech Republic
crossboarder = 0 - the resulting methods are limited only to Pickup Points in the Czech Republic
crossboarder = 1 – the resulting methods are not limited by a location of a Pickup Points

Valid for the following methods:

- Redirection

Your order form (shopping cart) can redirect your customers to https://pickup.dpd.cz/?address=Město, ulice, PSČ&return=https://example.com/objednavka, where they can choose the nearest place of collection. After making a selection, the customer will be redirected back to your e-shop. Based on the customer’s selection, the following POST parameters are passed:

parcelshop_id: ID of selected place of collection; more information can be obtained through the API.
parcelshop_name: Place of collection name.
parcelshop_address: Place of collection address.
parcelshop_cod_allowed: Allowing / not allowing cash on delivery
parcelshop_cod_allowed = 1 – cash on delivery allowed
parcelshop_cod_allowed = 0 – cash on delivery not allowed

If you wish to have the option to view also the Pickup Points abroad and you have implemented the cash on delivery restriction according to the cod_allowed field at the same time, then set the parameter crossboarder = 1.

https://pickup.dpd.cz/api/get-parcel-shops-by-address?address=Mesto%2C+Ulice%2C+PSC&return=https%3A%2F%2Fexample.com%2Fobjednavka&crossboarder=1&lang=en

- Web service

DPD offers to integrate through a web service. This method can be used in several ways. A sample of custom integration using PHP can be downloaded here.

https://pickup.dpd.cz/api/get-countries

To obtain the list of the Parcel Points abroad, it is necessary to obtain the list of available countries via the following method.

{
  'status': [returns 'ok' if executed well, otherwise 'error'],
  'code': [[return code, 200 = ok],
  'count': [[number of returned countries of collection],
  'data': {
    'items': [list of all countries of collection]
  }
}

The id field (ISO 3166-1 numeric) is important in the output, as it allows to obtain the list of the Parcel Points abroad, which is possible only if the value of the id field is set in the country parameter in the following methods:

https://pickup.dpd.cz/api/get-all?country=203&lang=en

A list of all pickup places can be downloaded from this address. The data is in the JSON format. If the country parameter is not indicated, only the list of Parcel Points in the Czech Republic is downloaded.

{
  'status': [returns 'ok' if executed well, otherwise 'error'],
  'code': [return code, 200 = ok],
  'count': [number of returned places of collection],
  'hash': [same places of collection in the same order have the same hashcode],
  'data': {
    'items': [list of all places of collection]
  }
}

https://pickup.dpd.cz/api/get-parcel-shop-by-id?id=CZ10190&lang=en

Another method is to download a single place of collection by its ID.

{
  'status': [returns 'ok' if executed well, otherwise 'error'],
  'code': [return code, 200 = ok, 404 = id not found],
  'count': 1,
  'data': { [places of collection data] }
}

https://pickup.dpd.cz/api/get-parcel-shops-by-address?address=Mesto%2C+Ulice%2C+PSC&limit=5&lang=en

A list of several closest places of collection can be downloaded from this address. The number of places can be altered using the „limit‟ parameter. The maximum is 100.

{
  'status': [returns 'ok' if executed well, otherwise 'error'],
  'code': [return code, 200 = ok, 1001 = unknown address],
  'count': [number of returned places of collection],
  'hash': [same places of collection in the same order have the same hashcode],
  'data': {
    'items': [list of all places of collection]
  }
}

- Integration into shopping cart

DPD also offers to integrate directly into your form using Javascript. The script requires jQuery framework and its input parameters are: a select box field to specify the pickup places location, and the address fields from the user.

If you wish to specify the result, you can use optional atribut country of object dpdShipping and set it using dpdShipping.setCountry(country code numerical variant (in compliance with the ISO 3166-1 standard)).

<script src="//ajax.googleapis.com/ajax/libs/jquery/2.0.0/jquery.min.js"></script>
<script src="https://pickup.dpd.cz/api/formIntegration"></script>
<script>
$(document).ready(function() {
  dpdShipping.setBox($('select[name="odberne_misto"]'));
  dpdShipping.addField($('input[name="ulice"]'));
  dpdShipping.addField($('input[name="mesto"]'));
  dpdShipping.addField($('input[name="psc"]'));
  dpdShipping.setCrossBoarder(0);
});
</script>

Ulice <input type="text" name="ulice" value=""><br />
Město <input type="text" name="mesto" value=""><br />
PSČ <input type="text" name="psc" size="5" value=""><br />
Odběrné místo <select name="odberne_misto" id="dpd_shippingplace"></select>

- Individual solution - Pickup list download

You can download the list of Pickup parcelshops for your own integration solution or just for Pickup list creation. The list can be downloaded in two formats: XML or CSV. We recommend daily updates to ensure you offer the most updated list to your customers. Usage of un-actual information can cause delay in delivery or return to the sender.

Updated list can be obtained on the links below:

It is possible to modify the output by several GET parameters:

country – country code numerical variant (in compliance with the ISO 3166-1 standard), returns the Pickup Points of the given country. The is default setting is country=203.
charset – output coding. Might occur in the following form - UTF-8, windows-1250
output=file – parameter for https://pickup.dpd.cz/export/xml. The result of the calling is saved in a file.

Example: https://pickup.dpd.cz/export/xml?country=703&charset=utf-8&lang=en

- Information for customers with own software

Customers using their own software are obliged to amend generated labels and shipment data before they start to use Pickup delivery service accordingly to the specification.

There is a need to print an additional label for Pickup delivery with full receiver address, as the main label contains Pickup address and receiver name.

There must be Pickup address as a receiver address in MPSEXPDATA file in row HEADER. New row PERS with the switch 4 (Pickup delivery service) and with full receiver address needs to be added.

More information about label shipment data structure can be found at https://www.dpd.cz/dokumentace/.

- Particular places of collection allowance

If there is a need to allow just some places of collection, you can do it via creation of allowed (or restricted) PS IDs - depends on the way how the filter is used. Any restriction is applicable for the map.

The best to do it is using of the complete list:

https://pickup.dpd.cz/export/xml?lang=en or https://pickup.dpd.cz/export/csv?lang=en

Filter can be applied to column Company to create the list with allowed IDs (column ID).

Example: Only DPD CZ places of collection should be displayed to customer (receiver). Filtr is applied to column Company ensuring that only parcelshops where company name starts with “DPD CZ” are shown. List of appropriate IDs is obtained; all IDs not listed needs to be hidden when data is returned.

Attention: Regular updating of all places of collection is strongly recommended as PS ID can be changed in the future.