Eshop provider's guide

If you wish to properly integrate our services into your platform, you should enable your customers to do the following:

Pick-up points

The end-user needs to select a pickup-point for his package and you should allow them to do so. For example here is a screenshot of pickup-point selection taken from www.bux.cz:

Pick-up point select example

Since our delivery costs for each country differ, you should make sure that:

  • Either the customer is able to create multiple carrier instances with pick-up points for different countries.
  • Or that they can set different prices per country/zone for your carriers.

Pick-up point management

As a data source for the pick-up points you should use our XML/JSON feed. Which you should make sure is kept up to date with daily updates.

Accessing feeds

There are 2 ways of accessing our pick-up point feed:

1. Via customer's API key

This option is most commonly used on self-hosted applications, where the customer is not sharing webspace or database with anyone else.

2. Via special URL parameter

We are able to create to create an URL parameter, which allows you to access the feeds without a specific API key. This way you don't need an user account to access the feed.

This approach is best utilized in cloud services with many users, where you can download and keep up to date only single central pick-up point database accessed by many users.

If you want this parameter created for you, please contact our tech support at technicka.podpora@zasilkovna.cz.

Managing local pick-up point database

Since you will probably want to be able to perform some kind of searching and filtering on the pick-up point list, you are likely to store them in a local database.

As we mentioned above, the daily updates are important as we change pick-up point availability every day based on their capacity and workload.

We often found problems properly managing pick-up point database at the side of plugins/eshop providers, where the local database update was done by purging old data from the database and simply filling the database with new data. This might seem simple enough, however if you use the same pick-up point database for back office purposes (validation on data export, loading pick-up point info at order detail view etc), you might find that the next day after an order was made, you can't load this information because the selected pick-up point is missing in your database.

Therefore we suggest keeping the local database up to date by simple status updates, where when the pick-up point is missing in today's feed, you just flag the pick-up point unavailable and you don't offer it to the end-user, while you still make it available for the back office.

External carriers and address delivery

We cooperate with several european carrier companies and are thus able to aggregate our customer's orders. This allows our customers to consign all of their packages at one place, using one type of label and also uploading all the data just to one place.

You can download list of these carriers and their specific IDs using our XML/JSON feed.

We found that the best way to approach this issue is by allowing the user to still use any preexisting carriers with their specific settings and just allow orders created using these carriers get exported into our system.

These are the most common (UI) solutions:

  • Checkboxes at each carrier with an option like "Send via Packetery"

  • Lists like the one below, where for each available carrier user can assign one of our partnered carriers.

    Address delivery solution example

Exporting orders

Packetery API

For more information about our API see our API description.

CSV export

For format specification see our page on CSV import.

Common issues

The eshop parameter

Our users often run more than 1 website and they need to be able to differentiate between them. This parameter serves as an identifier to determine from which eshop does each packet come from.

In ideal circumstances, you should allow users to set it themselves. If you wish not to, you can use the eshop's name or somethihng similar. However it is not very safe to use current request URI as the eshop might be using several different domains, which would cause you to send different information based on the domain from which the order was created or the domain from which the export was handled.

Single field for name and surname

If you don't keep the end user's name and surname separate, you don't need to worry. You can just send the whole string as name and we will try to split the surname from name for you.

Single field for street and house number

The same applies as for name and surname, if you send us the whole address in one string as street, we will try our best to separate the house number from the street name properly. However we can't guarantee proper split in case of complicated addresses when users specify apartment numbers etc.

Supported cash on delivery values

Our pick-up points need to be able to collect the whole value in cash, as well as they need to be able to return exact change. Because of these necessities, the values we accept for COD need to be in multiples of the lowest nominal value of the destination country's currency.

I.e. for CZK the value needs to be a whole number, while for HUF the value needs to be a multiple of 5.

Currency conversions

We strongly suggest to always specify the currency of packet's value and COD amount. If not specified, our system will assume, that the entered values are in the destination country's currency.

I.e. let's try to consign a packet with value of 500. If we send this packet to a czech pick-up point, the value will be 500 CZK, while if we send it to a Hungarian pick-up point, the value will be 500 HUF.

Phone number country codes

Similar logic as with currency conversions is applied to phone numbers. If you don't specify a country phone code, we will assume the number is from the destination country and we will attempt to notify the user on this number with the corresponding destination country code.

I.e. when you enter a phone number "123456789" while sending to Hungary, we will assume the correct phone number is "+36123456789".

Examples of phone number formats are in phone number formats.

Editing exported orders

Unfortunately we don't support editing existing orders via API.

Label download

As we require our clients to print out a label for each package we deliver for them, they need to be able to download those. Usually they need to go to log in to our system to download the labels, but you can make this easy for them by enabling them to download them directly from your eshop's back office.

You can download labels in any of our supported formats via our API.