- Name: Timeframe Webservice.
- Reason to Call: To get an expected day and time of arrival in a number of hours.
- Input: Details of dates, delivery option and address of the customer.
- Output: Timeframes and reason of no timeframes.
The following methods are defined within the Timeframe WebService:
|Method||JSON Action (GET)|
|GetTimeframes||Returns the timeframe indication for the specified delivery options and address|
* If you already use the former SOAP API’s and/or you want to make use of the REST API’s, you can fill in the Request for API key form or contact your PostNL account manager to arrange this.
Changes compared to the previous (SOAP) versions
Jun 01, 2017
Different namespaces (1.1)
Timeframe.SundaySorting has been added to the interface (1.2)
The methods GetDeliveryTimeframes, GetDaytimeTimeframes, GetEveningTimeframes and GetMorningTimeframes
have been replaced by a single GetTimeframes method.
To specify the delivery option(s) for which timeframes should be returned, the field Options has been added to the Timeframe element. (2.0)
The new options Sunday and Sameday are also available in the new GetTimeframes method. (2.0)
New and updated address fields
Street, HouseNrExt, City and CountryCode. CountryCode is a mandatory field.
For an address in the Netherlands, specify NL for this field. Furthermore, the HouseNumber field has been renamed to HouseNr. (2.0)
The following fields have been added to the interface: Interval, TimeframeRange.Start and TimeframeRange.End (2.1)
New deliveryoption: MyTime (2.1)
Using this method will give you the opportunity to predict a timeframe for a maximum of 1 month. In this period you will receive timeframes for all the delivery options you specify. This method is ideal when you want to show a calendar to your customer where he can make a decision for the deliverydate.
It is possible to offer your customer a couple of delivery timeframes, for example you can show the possible evenings or mornings in the coming week. Realize that in that case, the customer can choose a delivery timeframe in the future, and that you will have to keep the parcel in stock. Handing over the parcel to PostNL too early, will result in a delivery that is too early. You can use the Deliverydate WebService to determine the exact date when you should deliver the parcel to PostNL to ensure the consumer gets his/her parcel delivered on the time specified.
Evening and Same day delivery
It is possible that PostNL Pakketten delivers at every evening on a weekday. However, we do not deliver to every address. To know if we deliver to a given postal code, you will have to specify the “Evening” option in the GetTimeframes method call.
We also have the option to ship parcels on the same day. To know if Same day delivery is available, you must select both the “Sameday” and the “Evening” option in the GetTimeframes method.
If you want to offer Evening and Same day timeframes, realize that you will also have to adjust your shipping software (labels and confirming).
To not disappoint your customer, we advise you to request Evening timeframes first, and only show the possibility when Evening timeframes are returned by the webservice call. Otherwise, the suggestion is made that the parcel can be delivered in the evening, and in some areas there is no evening delivery possible.
PostNL Pakketten offer the possibility to deliver parcels on a Sunday. You can use the delivery options “Sunday” in the request to receive the timeframe for Sunday.
Note: Not all the products can be used for Sunday delivery. For a list of available products, click here.
The response is divided in two parts, ReasonNoTimeframe en Timeframe. TimeFrame is the most interesting because all the available periods between the given start and end dates are shown in this response.
Every Timeframe in the response has at least one period under TimeFrames. Exact information of each period is shown at TimeFrameTimeFrame, whereby all values are strings. This allows to distinguish between normal periods, morning and evening delivery periods. The following values can be specified in the options element:
Morning delivery before 10:00
Morning delivery before 12:00
Sameday delivery (must be used in combination with Evening)
Afternoon delivery before 17:00
|MyTime||MyTime delivery (in Dutch: Op Afspraak Bezorgd)|
All the above delivery options can be used in the request of the timeframe webservice. PostNL will charge an additional amount for delivery of the parcels with the options Evening, Morning, (After)Noon and Sunday. For specific costs and the activation of this delivery options, it is recommended to consult your PostNL Pakketten account manager.
There are several reasons why there isn’t timeframe information available. Below you can find the codes and the specific reasons.
|Code 01||Geen routeplan tijdvak (no timeframe available for this address in combination with this particular delivery option)|
|Code 03||Dag uitgesloten van tijdvak (no timeframe available at this day for this particular delivery option)|
|Code 05||Geen avondbelevering mogelijk (no evening delivery possible at this address/date)|
Error codes have been specified in the Error code doucment. Errors from the backend services will be caught and returned as standard API errors according to the generic error handling procedures in API.
Request and Response codes
For explanation of the request and response codes, you can take a look at the Documentation page of this API. Here you can find all information about the attributes of the json call, like descriptions, formats and examples.
Test the RESTful API's with JSON content type format with the below Swagger tooling. To easily test the API: Click at 'Expand Operations', fill in at least the requirerd parameters and click at the 'Try it Out!' button. You can find the response code under Response Messages.
You can also test this API's by using the following Swagger url: http://petstore.swagger.io/(expand the url with /swagger.json and click Explore)