Documentation REST

Confirming webservice

Summary

  • Name: Confirming Webservice
  • Reason to Call: Create and send a confirmation of the parcels to the PostNL system.
  • Input: Information about the shipment.
  • Output: Confirm shipment information 

Note: When using the labelling service (GenerateLabel method), the Confirming service does no longer need to be integrated in your system, for it is included into this service.

Methods

The following method is defined within the Confirming WebService.

Method   JSON Action (POST)  
Confirming  Check and confirm shipment information of a parcel. Each request contains a single parcel. This parcel can be (part of) a single shipment or can be part of a multi-collo shipment.  

Call details

Interface Version1_10
Sandbox endpointhttps://api-sandbox.postnl.nl/shipment/v1_10/confirm
Sandbox Swaggerhttps://api-sandbox.postnl.nl/shipment/v1_10/confirm/swagger.json
Production endpointhttps://api.postnl.nl/shipment/v1_10/confirm
ProductionSwaggerhttps://api.postnl.nl/shipment/v1_10/confirm/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

Version

Release Date

Status

Release Notes

Schema Changes

1_10

Jun 01, 2017

Supported

The following fields have been added to the interface:
Shipment/Content, Shipment/CostCenter, Shipment/CustomerOrderNumber,  Shipment/Remark, Shipment/ReturnReference, Shipment/ReturnBarcode, Amount/BIC and Amount/IBAN. (1.3)
The field Amount/AccountNr have been removed from the interface (1.3)
To comply with SEPA regulation, the bank account details must be entered in IBAN format. The COD card has been changed to print the IBAN bank account number. (1.3)

Different namespaces (1.4)

The following fields have been added to the interface:
Shipment\ProductOption\Option, Shipment\ProductOption\Characteristic, Shipment\DeliveryDate and Shipment\DeliveryAddress (1.4)

Different namespace (1.5)

The fields Shipment.DownPartnerLocation and ConfirmingResponseShipment.Warnings have been added to the interface (1.6)
The following fields have been added to the interface:
Shipment.IDNumber,  Shipment.IDType, Shipment.IDExpiration, Shipment.ReceiverDateOfBirth (1.7)
The field StreetHouseNrExt is now usable for locations in NL, BE and DE. (1.7)

Shipment validation errors now include an error code in addition to the error message. (1.8)

Version 1_9 is a maintenance release and contains no functional changes. (1.9)

PostNL has implemented a commercial route to China. In order to do this, the following fields have been added to the interface:

- Shipment.Customs.Content.Content.EAN, Shipment Customs.Content.Content.ProductURL,
- The Shipment.Customs.Content element can occur up to 10 times instead of 5. (1.10)

- DeliveryTimestampStart and DeliveryTimestampEnd has been added to the interface to create MyTime labels (1.10)

Guidelines

Recommendation
Implementing the confirming functionality as early in your process as possible is highly suggestible. Our best practice is that you implement this service call directly after the generation of the shipping label. 

Error handling
We would like to stress the need for a suitable error handling implementation on your side. If somehow, an error is received at your end upon sending your confirmation, this means that we could not process the information correctly and the successful delivery of the parcel is in jeopardy. We strive to return the error message with as much detail as possible so you can take proper action in order to improve the information about the parcel and retry. 

Multiple shipment (Multicollo)
A parcel can be (part of) a single shipment or can be part of a multicollo shipment. At the Group type you can specify that a parcel is part of a multicollo shipment. 

For shipments within the Netherlands and Belgium, multicollo shipments can be created. Using the API, this can be done as follows: 

  • Connect the parcels by using the Group type in each request. Mention the amount of parcels in the shipment (GroupCount), the number of the specific Parcel (GroupSequence) and the main barcode of the shipment (MainBarcode) and specify Multicollo as the GroupType (GroupType 03)
  • In case of COD-products, only mention the COD amount in the main Collo. This amount is the sum of all COD amounts within the shipment. De requests of the other parcels must not contain the field Amount.
  • Multicollo is available for the following products:
    • Dutch domestic (with exception of Brievenbuspakje products) 
    • EPS specifically for shipments from the Netherlands to Belgium
    • Cargo products 

Return label
You can generate a return label to send directly with the parcels, this is called a 'Label in the box' return label. PostNL Parcels also offers the possibility of providing a single return label. You can find examples about how to confirm this return products at the Request examples.

It t is only possible to confirm (and generate) a return label with an business reply number (Antwoordnummer) as return address. You will also need a separate customer code specifcally for generating bardcodes for return shipments. Please contact your PostNL Pakketten account manager before you make use of the return label possibility.

Combilabel product codes
When separating labelling and confirming for combilabel product codes, there are some fields from the Labelling response that need to match with the Confirming request. These fields concern the network partner data. The following fields from the Labelling response need to be matched with the Confirming request:

  • Barcode " DownPartnerBarcode
  • DownPartnerID
  • ProductCodeDelivery

Pickup Basic and Plus
Pickup plus products consist of two Shipments, the collection order and the delivery order. Both orders must be placed in a separate Shipment in the request. This means that a request for a pickup plus product will contain two Shipment segments. The below structure is required:

Regular parcel Confirming structurePickup plus Confirming structurePickup basic Confirming structure
CustomerCustomer

Customer

  • AddressType 02
    • Antwoordnummer required
MessageMessageMessage

Shipments

  • AddressType 01
  • 3S barcode
  • ProductCode 3085

Shipments

  • AddressType 04
  • 2S barcode
  • CollectionTimeStampEnd
  • CollectionTimeStampBegin
  • ProductCode 3151

Shipments

  • AddressType04
    • Companyname required
  • 3S barcode
  • CollectionTimeStampEnd
  • CollectionTimeSTampBegin
  • ProductCode3160

Shipment

  • AddressType01
  • 3S barcode the same as 2S (but with 3S)
  • Grouptype 01
  • Mainbarcode 2S of first shipment
  • GroupCount
  • GroupSequence
  • ProductCode 3238


GlobalPack
The Customs type is mandatory for GlobalPack shipments and not allowed for any other shipment types.

Address type
PostNL internal applications validate the receiver address. In case the spelling of addresses should be different according to our PostNL information, the address details will be corrected. This can be noticed in Track & Trace. The element Address type is a code in the request. Possible values are:


CodeDescription
01Receiver
02Sender
03Alternative sender address
04Collection address
08Return address*
09Delivery address (for use with Pick up at PostNL location)

* When using the 'label in the box return label', it is mandatory to use an Antwoordnummer in AddressType 08. This cannot be a regular address.

Remarks:
Within the CustomerType, only AddressType 02 can be used. This Type can also be placed in the ShipmentType.

Within the ShipmentType, at least ShipmentType with 01 is required (and ShipmentType 02 if it's not entered within CustomerType).

The element StreetHouseNrExt is a combination of Street, HouseNr and HouseNrExt. This field has a dependency with the field Street. One of both fields must be filled mandatory; using both fields is also allowed (StreetHouseNrExt has priority over the individual fields if it is filled). This field can be used in case the values of Street, HouseNr and HouseNrExt can't be mapped separately before calling the webservice. 

This webservice will calculate a split of street name, house number and extension for you, and will afterwards use the split values. This might result in incorrect behavior for which PostNL can't be held liable. Content in this field must be in the described order or otherwise the

Shipment type
The element Shipment type is a code in the request. Possible values are:


CodeDescription
01Receiver
02Sender (if not in Customer/Address
03Alternative sender address
04Collection address
08Return address*
09Delivery address (for use with Pick up at PostNL location)

*When using the 'Label in the box' return label, it is mandatory to use a Antwoordnummer in AddressType 08. This cannot be a regular address.

The following rules apply: 

If there is no Address specified with AddressType = 02, the data from Customer/Address will be added to the list as AddressType 02. If there is no Customer/Address, the message will be rejected.

At least one other AddressType must be specified, other than AddressType 02. In most cases this will be AddressType 01, the receiver address.

Contact type
Contact type has the elements Email, SMSNr and TelNr. These fields have a dependency with each other. At least one of these three fields must be filled mandatory for certain products/ product codes (e.g. Evening/Sameday delivery, Pickup at PostNL location). Two or three can be filled as well.

CodeDescription
01Receiver
02Sender

Remark: Please add the e-mail address of the receiver to improve the PostNL experience of your customer. 

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 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)

Confirming

Confirms a shipment