Documentation
Timeframe webservice
Summary
- Name: Timeframe Webservice
- Reason to Call: To get a timeframe in which a parcel is estimated to be delivered.
- Input: Details of dates, delivery options and the address of the customer.
- Output: Timeframes and the possible reason no timeframe could be given.
Method
The following methods are defined within the Timeframe WebService:
Method | Description |
GetTimeframes | Returns the timeframe indication for the specified delivery options and address |
Method | SoapAction |
GetTimeframes | http://postnl.nl/cif/services/TimeframeWebService/ITimeframeWebService/GetTimeframes |
Call details
Interface version | 2_1 |
Sandbox endpoint | https://api-sandbox.postnl.nl/shipment/v2_1/calculate/timeframes |
Sandbox wsdl | https://api-sandbox.postnl.nl/shipment/v2_1/calculate/timeframes/soap.wsdl |
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 wsdl | https://api-sandbox.postnl.nl/shipment/v2_1/calculate/timeframes/soap.wsdl |
Production swagger | https://api-sandbox.postnl.nl/shipment/v2_1/calculate/timeframes/swagger.json |
Versioning
REST:
API
| Version | Release Date | Status | Release Notes | Schema Changes |
Timeframe | 2_1 | Jun 01, 2017 | Current version | N/A | |
SOAP:
API | Version | Release Date | Status | Release Notes | Schema Changes |
Timeframe | 1_0 | Oct 7, 2013 | Not supported |
|
|
1_1 | Aug 14, 2014 | Not supported | Different namespaces
| Yes | |
1_2 | Oct 8, 2014 | Supported | The following field has been added to the interface:
A number of changes have been made to the interface that will require creating a new webservice
| ||
2_0 | Aug 14, 2015 | Current Version | Added Option value ‘MyTime’ for delivery on demand - The following optional fields have been added to the interface (for the delivery on demand product): - Timeframe.Interval (used to filter certain timeframes which can be returned for delivery on demand) - Timeframe.TimeframeRange.Start (used to specify a specific range of timeframes to be returned for delivery on demand) - Timeframe.TimeframeRange.End | Yes | |
Guidelines
GetTimeframes
Using this web service allows you to predict a time frame for a maximum of 17 days.* During this period, you will receive time frames for all the delivery options you specify. This method is ideal if you want to show a calendar and/or frame where your customers can decide on the date and time of delivery for their order. It is also possible to offer your customer a couple of delivery time frames. For example, you can show the Evening and/or Morning delivery possibilities for the coming week.
* Posting a time frame for longer than two weeks is not recommended. This is because a time frame is dynamic data and so it cannot be guaranteed that it will be the same for a given postal code two weeks later.
Be aware that you need to hold on to a customer’s parcel until the date they have requested. Entrusting it to PostNL too early will result in it being delivered too soon. You can use the ‘Deliverydate webservice’ to determine the exact ‘sentdate’ for handing the parcel over to PostNL to ensure your customer receives it exactly on time - neither too early nor too late.
Evening and Sameday 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 call.
We also have the option to ship parcels on the same day. To know if Sameday delivery is available, you must select both the “Sameday” and the “Evening” option in the GetTimeframes call.
If you want to offer Evening and Sameday delivery, realize that you will also have to adjust your shipping requests (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 option “Sunday” in the request to receive the timeframe for Sunday. Not all the products can be used for Sunday delivery. For a list of available products, see the Products page at How to Use of the labelling and confirming webservices.
Response
The response is divided into two parts, ReasonNoTimeframe and 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 the 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 |
MyTime | MyTime delivery (Delivery on demand) |
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, Sameday and Sunday. For specific costs and the activation of this delivery options, it is recommended to consult your PostNL Pakketten account manager. For Sunday delivery it is even mandatory to consult your 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.
Code | Description |
Code 01 | Geen routeplan tijdvak (no timeframe available for this address in combination with this particular delivery option) |
Code 02 | Geen commercieel tijdvak (not a commercial timeframe, reliability is too low) |
Code 03 | Dag uitgesloten van tijdvak (no timeframe available at this day for this particular delivery option) |
Code 04 | Uitgesloten adres (excluded address for timeframe indication) |
Code 05 | Geen avondbelevering mogelijk (no evening delivery possible at this address/date) |
Best practice
Integrate all three PostNL frontend webservices into your checkout and empower your customers to choose the delivery option that suits them best.
First use the Deliverydate webservice (Get deliverydate method) to determine the available and possible delivery date(s), based on your shipping date. Use the received date from this service as a starting point in the Timeframe webservice to show customers the possible day and time of arrival. In this way you avoid showing not possible deliverydates. The postal code that customers enter by placing their order, determine the timeframes that apply to their address.
Use the Location webservice to show the nearest pickup point(s) based on the postal code or coordinates of the customers. The location(s) can be shown in a map if you want to make it visually more appealing.
The Visual Assets can be useful to create a delivery options frame in your checkout.
Error codes
Error codes have been specified in the below PDF file. Errors from the backend services will be caught and returned as standard API errors according to the generic error handling procedures in the API.
Request GetTimeframes
Message type
Attribute | Mandatory | Format | Description | Example |
MessageID | M | String [1-12] | ID of the message. | 1 |
MessageTimeStamp | M | Datetime [19] | Date/time of sending the message. Format: dd-mm-yyyy hh:mm:ss | 29-06-2016 12:00:00 |
City | O | String [0-35] | City of the address | Hoofddorp |
Countrycode | M | String [2] | The ISO2 country codes | NL |
EndDate | M | Date [10] | Date of the end of the timeframe. Format: dd-mmyyyy.
Enddate may not be before StartDate. | 02-07-2016 |
HouseNr | M | String [0-35] | The house number of the delivery address | 42 |
HouseNrExt | O | String [0-35] | House number extension | A |
Interval | O | Integer [2] | Interval used Mytime timeframes
Possible values: 30 and 60. Use 60 if you only want full two-hour timeframes returned. | 60 |
Options | M | Array | The delivery options for which timeframes should be returned. At least one delivery option must be specified. See Guidelines for possible values. | Evening |
PostalCode | M | String [4-10] | Zipcode of the address | 2132WT |
StartDate | M | Date [10] | Date of the beginning of the timeframe. Format:dd-mm-yyy | 30-06-2016 |
Street | O | String [0-95] | The street name of the delivery address | Siriusdreef |
SundaySorting | M | Boolean [true/false] | Whether or not the requesting party allows for Sunday sorting (which leads to delivery on Monday). | true |
TimeframeRange.End | O | String [5-8] | Range used for MyTime timeframes
Timeframes with an end time later than this value will be excluded from the response. | 12:00:00 |
TimeframeRange.Start | String [5-8] | Range used for MyTime timeframes
Timeframes with a start time earlier than this value will be excluded from the response. | 08:00:00 |
Example
POST https://api-sandbox.postnl.nl/shipment/v2_1/calculate/timeframes HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "http://postnl.nl/cif/services/TimeframeWebService/ITimeframeWebService/GetTimeframes"
apikey: **********
Content-Length: 1526
Connection: Keep-Alive
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tim="http://postnl.nl/cif/services/TimeframeWebService/" xmlns:tpp="http://postnl.nl/cif/domain/TimeframeWebService/" xmlns:arr="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<soapenv:Body>
<tim:GetTimeframes>
<tpp:Message>
<tpp:MessageID>1</tpp:MessageID>
<tpp:MessageTimeStamp>29-06-2016 12:00:00</tpp:MessageTimeStamp>
</tpp:Message>
<tpp:Timeframe>
<tpp:City>Hoofddorp</tpp:City>
<tpp:CountryCode>NL</tpp:CountryCode>
<tpp:EndDate>02-07-2016</tpp:EndDate>
<tpp:HouseNr>42</tpp:HouseNr>
<tpp:HouseNrExt>A</tpp:HouseNrExt>
<tpp:Options>
<arr:string>Evening</arr:string>
</tpp:Options>
<tpp:PostalCode>2132WT</tpp:PostalCode>
<tpp:StartDate>30-06-2016</tpp:StartDate>
<tpp:Street>Siriusdreef</tpp:Street>
<tpp:SundaySorting>true</tpp:SundaySorting>
</tpp:Timeframe>
</tim:GetTimeframes>
</soapenv:Body>
</soapenv:Envelope>
Response GetTimeframes
ReasonNoTimeframes type
Attribute | Description | Example | ||
Code | The code of the reason | 05 | ||
Date | Format dd-mm-yyyy | 02-07-2016 | ||
Description | The description of the reason. | Geen avondbelevering mogelijk
(Delivery in the evening is not possible) | ||
Options | The delivery options applicable to the timeframe information. | Evening | ||
Date | Format dd-mm-yyyy | 01-07-2016 | ||
From | Format hh:mm:ss | 18:00:00 | ||
Options | The delivery options applicable to the timeframe information. See Guidelines for possible values. | Evening | ||
To | Format hh:mm:ss | 21:30:00 |
Timeframe type
Attribute | Description | Example | ||
Code | The code of the reason | 05 | ||
Date | Format dd-mm-yyyy | 02-07-2016 | ||
Description | The description of the reason. | Geen avondbelevering mogelijk
(Delivery in the evening is not possible) | ||
Options | The delivery options applicable to the timeframe information. | Evening | ||
Date | Format dd-mm-yyyy | 01-07-2016 | ||
From | Format hh:mm:ss | 18:00:00 | ||
Options | The delivery options applicable to the timeframe information. See Guidelines for possible values. | Evening | ||
To | Format hh:mm:ss | 21:30:00 |
Example
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<ResponseTimeframes xmlns="http://postnl.nl/cif/services/TimeframeWebService/"
xmlns:a="http://postnl.nl/cif/domain/TimeframeWebService/"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<a:ReasonNoTimeframes>
<a:ReasonNoTimeframe>
<a:Code>05</a:Code>
<a:Date>30-06-2016</a:Date>
<a:Description>Geen avondbelevering mogelijk</a:Description>
<a:Options xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<b:string>Evening</b:string>
</a:Options>
</a:ReasonNoTimeframe>
<a:ReasonNoTimeframe>
<a:Code>05</a:Code>
<a:Date>01-07-2016</a:Date>
<a:Description>Geen avondbelevering mogelijk</a:Description>
<a:Options xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<b:string>Evening</b:string>
</a:Options>
</a:ReasonNoTimeframe>
<a:ReasonNoTimeframe>
<a:Code>05</a:Code>
<a:Date>02-07-2016</a:Date>
<a:Description>Geen avondbelevering mogelijk</a:Description>
<a:Options xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<b:string>Evening</b:string>
</a:Options>
</a:ReasonNoTimeframe>
</a:ReasonNoTimeframes>
<a:Timeframes i:nil="true"/>
</ResponseTimeframes>
</s:Body>
</s:Envelope>