Background information

Authentication

The current CIF username / password combination will be replaced by an API key in the SOAP API calls. This API key should be added into the header of your API requests.

You can also fill in the API key in the former password field and send the same SOAP requests as you did before.

Deprecate support for TLS 1.0

TLS 1.0 is no longer considered strong cryptography and therefore cannot be used as a security control. For the PostNL API platform we will deprecate support for TLS 1.0 on September 6th 2018. After this change the clients that connect to the API proxies using TLS 1.0 or older (SSL) will not work anymore.
For more information see the News page. 

Version upgrades

The PostNL API’s are constantly being improved and enhanced with new products and functionalities. PostNL expects users to regularly upgrade their versions of the APIs, so they are always using a supported version of the integrated services. Some older versions have not been migrated to the new platform. Users of these APIs will therefore be obliged to update the outdated version(s).
In the API Manager you will find information of which APIs are currently linked to your API account. This is based on the use of the CIF web services. If an asterisk (*) is displayed next to the version of the API, then you are not using the most recent version. It is recommendable to  migrate to the latest version but this is not necessary. If you currently use a version/versions that will cease to be operational, the most recent version will be shown next to the API name.

Documentation and Versioning of the API’s can be found on the Documentation pages of the Parcels API’s. 

Note: An update will be required if you want to use the latest version of the APIs. This will entail programming a number of changes/new fields. See the versioning paragraphs.

Location API version 2.0 | 2.1

If you are currently use the CIF Location version 2.0, you will see the 2.1 in the API Manager. No changes have been made in the request interface in the updated version (2.0 to 2.1) So please upgrade to the 2.1 version. The only changes that has been made is:
The Location Type has been extended with partner Location Codes in the response Location Code.

Timeframe API version 2.0 | 2.1

If you are currently use the CIF Timeframe version 2.0, we advise you to upgrade to the 2.1 version. Only a few, optional field have been add to the interface. The only changes that have been made are:
-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 and Timeframe.TimeframeRange.End  (used to specify a specific range of timeframes to be returned for delivery on demand). 

Namespaces

In the new environment you can find all the namespaces at the top of the response instead of the spread namespaces in the CIF responses. This will not change the way in which responses are handled.  
The xml messages have now become more compact and manageable.

Error messages

Some of the error messages and warnings in the response may differ from the former CIF messages but the structure is still the same.  On the old platform, there was no consistency in error messages where the required field was either missing or empty (e.g. Field x cannot be null  or field x cannot be missing). In the new platform, the error message returned is now consistent with either a field missing from the request or the field being provided empty.
Furthermore, we altered error messages which were too generic to include the specific path to which field triggers the particular error.
For example, the error message in CIF can be Value 'GetDeliveryDate.CutOffTimes.CutOffTime.Time' is not in the correct format 'Time', whereas for the new platform we specify the exact field like this: Value 'GetDeliveryDate.CutOffTimes.2.CutOffTime.Time' is not in the correct format 'Time'.

REST/JSON

Due to the increasing need and demand for RESTful APIs, we also have REST variants with JSON format available now.
For example: When showing the delivery options in the webshop checkout, these new APIs can improve and facilitate interoperability and make it easier to implement the services.
You can find information and test these APIs on the REST Documentation pages.