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: 

MethodDescription
GetTimeframesReturns the timeframe indication for the specified delivery options and address
MethodSoapAction
GetTimeframeshttp://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

Production endpoint

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

Production WSDL

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

* PostNL has launched a new API platform since 24 August 2017. The former webservices have been migrated to this platform, so that we can keep providing good service. It is recommended to use the above endpoints.

If you already use the former API’s (endpoint: https://service.postnl.com/CIF/) and/or you want to make use of the new endpoints, 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

Release Notes

Schema Changes

Timeframe

1_0

Oct 11, 2013

Supported

 

 

1_1

Aug 14, 2014

Supported

Different namespaces

Yes

1_2

Oct 8, 2014

Supported

The following field has been added to the interface:
Timeframe.SundaySorting
This field is optional for all request which are send to all the Timeframe operations.

Yes

2_0

Aug 14, 2015

Current Version

A number of changes have been made to the interface that will require creating a new webservice
  • Methods and TijdvakType replaced by options
    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.

    You can specify the following options to get the same results as the old methods:
    Old method                               Equivalent deliveryoption
    GetDeliveryTimeframes            Daytime, Evening
    GetDaytimeTimeframes            Daytime
    GetEveningTimeframes             Evening
    GetMorningTimeframes            Morning, Noon
  • The new options Sunday and Sameday are also available in the new GetTimeframes method. The field TijdvakType which indicated which delivery option was applicable to the returned Timeframe and ReasonNoTimeframe elements has been replaced by an Options field. This field uses the same values as the new Options field in the request.
  • 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.

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.

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 02Geen commercieel tijdvak (not a commercial timeframe, reliability is too low)
Code 03Dag uitgesloten van tijdvak (no timeframe available at this day for this particular delivery option)
Code 04Uitgesloten adres (excluded address for timeframe indication)
Code 05Geen 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.

Timeframe_Error_Codes

Request GetTimeframes

Message type

AttributeMandatoryFormatDescriptionExample
MessageIDMString [1-12] ID of the message.1
MessageTimeStampMDatetime [19] Date/time of sending the message. Format: dd-mm-yyyy hh:mm:ss 29-06-2016 12:00:00
CityOString [0-35] City of the address  Hoofddorp
CountrycodeMString [2] The ISO2 country codes NL 
EndDateMDate [10] Date of the end of the timeframe. Format: dd-mmyyyy.
Enddate may not be before StartDate. 
02-07-2016
HouseNrMString [0-35] The house number of the delivery address42
HouseNrExtOString [0-35] House number extension A
IntervalOInteger [2] Interval used Mytime timeframes
Possible values: 30 and 60. Use 60 if you only want full two-hour timeframes returned.
60
OptionsMArrayThe delivery options for which timeframes should be returned. At least one delivery option must be specified. See Guidelines for possible values.Evening
PostalCodeMString [4-10] Zipcode of the address2132WT
StartDateMDate [10] Date of the beginning of the timeframe. Format:dd-mm-yyy 30-06-2016
StreetOString [0-95] The street name of the delivery address Siriusdreef
SundaySortingMBoolean [true/false]Whether or not the requesting party allows for Sunday sorting (which leads to delivery on Monday).true
TimeframeRange.EndOString  [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  DescriptionExample
Code  The code of the reason05
Date   Format dd-mm-yyyy02-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-yyyy01-07-2016
From   Format hh:mm:ss18:00:00
Options  The delivery options applicable to the timeframe information. See Guidelines for possible values.Evening
To   Format hh:mm:ss21:30:00

Timeframe type

Attribute  DescriptionExample
Code  The code of the reason05
Date   Format dd-mm-yyyy02-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-yyyy01-07-2016
From   Format hh:mm:ss18: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>