Content in this article:
- Introduction
- Information in the Request
- Own Locations
-
Response structure
- 4.1 Reference address
- 4.2 Carrier information
- 4.3 Locations per carrier
- 4.4 Using the response in the booking
1. Introduction
Consumers want more control over where and when goods are delivered. One of the services that carriers provide is pick-up points. Some carriers call it pick-up points, while others call it service points, PUDO (Pick-up/Drop-off) or an equivalent. All mean the same. It is a location where the end customer can pick up the goods during opening times. Transsmart has an option to do location select calls for carriers who have this available.
2. Information in the Request
A location request call can be done on the service /v2/locations/{account}. There are a few parameters that can or must be provided in the call. The calls start with an address. The address is normally provided by the end customer who also has the option to select the pick-up point provided as an outcome of this call. Normally this is for webshop integration in the check-put.
Whenever you encounter the term address, it refers to the location where the requested pick-up point should be near. Usually, this is an address close to the end customer's home or workplace.
| Parameter | Description |
| street | The street of the address |
| houseNumber | Housenumber |
| houseNumberExt | Housenumber addition for example the a in 1a |
| zipCode | The zipcode |
| city | The city of the address |
| countryFrom | The country from which the shipment will be sent |
| countryTo | The country to which the shipment will be sent. |
| ownLocationOnly | Parameter for showing or displaying own locations from a customer. This will be explained in detail later. |
| The email of the receiver. (this is a mandatory field and only needed for carrier GLS) | |
| provider | The carrier of which you want to get the locations from. If the parameter is not included in the request, you will receive all available locations from all the possible carriers you have configured on your account, you can also add multiple carriers in this section. For further explanation, see the technical documentation |
| limit | Possibility to limit the results per carrier. The default is on 20 results per carrier |
3 Own Locations
There is a possibility to add your own locations with a logo. A location of your own can be a physical store where you can ship to and where your customers can also pick up the goods. To be able to add own locations, you need to contact the support department so they can activate it for you. Maintaining own locations can be done in menu Manage account > Locations & Cost Centers.
4 Response structure
In the response, you will receive the requested locations with subsequent details that could be relevant to the end user. For example, you will receive the carrier with a logo for displaying on your website, the opening hours, the location (geo coordinates), etc. With this information, a location can be selected.
4.1 Reference address
First of all, you will find the reference address (the original address which has to be close to the locations). The reference address will also have geo coordinates and a Google Maps URL, to display the location on a map.
4.2 Carrier information
After the reference address, you will receive carrier information. This is general information that is specific to the carrier. After this general information, you will get detailed information per service point. For each carrier, you will receive the carrier code, a carrier description, a logo of the carrier (base64 encoded), and a marker to display at the check-out.
4.3 Locations per carrier
Per carrier, you will receive pick-up locations. By default, you will receive 20, but a limit can be set in a parameter. The locations have the following information; a distance in kilometers to the reference address, a name, and the address information. Depending on the carrier you will also receive a locationId which if available needs to be used in the booking (will be explained later).
Per day you will receive opening times and at the end of the location, the geo coordinates and a Google Maps URL are given. This is repeated per location and carrier.
4.4 Using the response in the booking
After a location is selected by an end customer based on the display on the map at the front end you need to make a booking. In general, you need to copy the given locationId parameter to the additional reference value of type SERVICEPOINT. Furthermore, the original address details of the receiver address need to be copied to the invoice segment. These are normally the address details of the end user. The address details of the selected pickup location must then be placed in the receiver segment. This is the shipping address for the parcel. There may be a slightly different procedure per carrier.