Documentation REST

Timeframe webservice

Summary

  • 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.

Methods

The following methods are defined within the Timeframe WebService:

MethodJSON Action (GET)
GetTimeframesReturns the timeframe indication for the specified delivery options and address

Call details

Interface Version

2_1

Sandbox endpoint

https://api-sandbox.postnl.nl/shipment/v2_1/calculate/timeframes

Sandbox Swagger

https://api-sandbox.postnl.nl/shipment/v2_1/calculate/timeframes/swagger.json

Production endpoint

https://api.postnl.nl/shipment/v2_1/calculate/timeframes

Production Swagger

https://api.postnl.nl/shipment/v2_1/calculate/timeframes/swagger.json

* 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. 

Versioning

API

Version

Release Date

Status

Changes compared to the previous (SOAP) versions

Schema Changes

Timeframe

2_1

Jun 01, 2017

Supported

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
Several address fields have been added to the Timeframe element to specify the delivery address more precisely. These fields are:

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)

Yes

Guidelines

GetTimeframes method
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.

Sunday delivery
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.

Response
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:

Option

Description

Daytime

Daytime delivery

Evening

Evening delivery

Morning

Morning delivery before 10:00

Noon

Morning delivery before 12:00

Sunday

Sunday delivery

Sameday

Sameday delivery (must be used in combination with Evening)

Afternoon

Afternoon delivery before 17:00  

MyTimeMyTime 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.

ReasonNoTimeframe codes
There are several reasons why there isn’t timeframe information available. Below you can find the codes and the specific reasons.

CodeDescription
Code 01Geen 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 05Geen avondbelevering mogelijk (no evening delivery possible at this address/date)

Error codes
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.

Timeframe_Error_Codes

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.

Swagger UI

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)