How does the use of a pickup location work in the Post NL integration?

This document describes how pickup locations work in RetailVista in combination with a Post NL API integration. The use of pickup locations requires special processing because there are three addresses involved: a sender address, a customer address, and a pickup address. This is different from the usual two addresses. 

Post NL API

The parcel service integration in RetailVista is based on the Post NL API specifications. These specifications mention a Post NL pickup location called 'Pakje Gemak'.

The most recent Post NL API documentation can currently be found at

https://developer.postnl.nl/browse-apis/send-and-track/labelling-webservice/documentation/

Determination of delivery address in RetailVista

In a sales order, a different delivery relationship and/or a different delivery address can be specified. When one or both of these fields are filled in, RetailVista will determine a different delivery address based on these fields. If both fields or only the different delivery address field are filled, the different delivery address field will be used for addressing. If only the different delivery relationship field is filled, the delivery address field of that relationship will be used. If that relationship does not have a delivery address, a search will be performed in order for a postal address and then for a visit (default) address.

If no alternative delivery address can be found, or both fields are not specified, the delivery address of the relationship of the sales order will be used. The same applies here: if that relationship does not have a delivery address, a search will be made in order for a postal address and then for a visit (default) address.

Translation of found address to Post NL API

In the Post NL Address object (see the Post NL API documentation), there is a Type field. This field indicates the type of the address. If no alternative delivery address could be found in RetailVista in a sales order (via the two alternative relationship and address fields from the sales order), a destination address is always created with code '01' in which the found delivery address of the relationship itself is mentioned.

If an alternative delivery address is found, it is also checked whether a 'Pakje Gemak' product code has been used. This must be a code from the range 3531, 3532, 3533, 3534, 3535, 3536, 3543, 3544, 3545, 3546, 3553, 3543, 3544, 3545, 3546. It is also possible to specify the text '/pakjegemak' instead of these product codes in the advanced settings of the parcel service. By using one of the aforementioned product codes or the text /Pakjegemak, RetailVista knows that it is a Post NL Pickup location.

If it is now determined that a Post NL Pickup location is desired, 2 'destination' addresses are created. The first is an address object with type '01' in which the final delivery address of the customer itself is mentioned. In addition, a second address object with type '09' is created in which the alternative delivery address is mentioned. This should therefore be the chosen address of the Post NL pickup location!

This information is sent to the labeling service of Post NL, after which RetailVista will receive a correctly formatted address label.

In summary, in the webshop order message, a 'Delivery' address must be included, which is the address of the Post NL pickup location. With the above explanation, this functionality should work correctly.