PostNord

This page lists the results from the requirements analysis phase of the postnord booking integration as detailed in this GitHub issue.
Questions answered by the  can be found .
<MermaidChart
title="Overview"
chart={`
sequenceDiagram
autonumber
participant User as User
participant Auth as Auth API
participant Addr as Address Check API
participant DelOpt as "Delivery Options API"
participant Booking as "Booking API"
participant Label as "Label Creation API"
participant Addons as "Addons Processing"
participant Customs as "Customs/Tolls API"
User->>+Auth: Authenticate
Auth->>-User: Authentication Success

User->>+Addr: Check Address
Addr->>-User: Address Valid

User->>+DelOpt: Fetch Delivery Options
DelOpt->>-User: Delivery Options with bookingInstructions

User->>+Booking: Make Booking with deliveryOptionId
Booking->>-User: Booking Success and Labels

User->>Label: Create Label (if needed)

User->>Addons: Determine Necessary Addons
Addons->>Booking: Include Addons in Booking

User->>Customs: Fill in Customs Declaration (if needed)
Customs->>Booking: Include Customs Declaration in Booking

`}
/>
Authentication
Most or all the endpoints require a header which is an api key unique for each customer.
Transport methods endpoints:
Delivery Options
This API serves as the availability check and the "request lockers/pickup points" functionality at the same time. It returns a struct called bookingInstructions which contains the necessary fields and values for booking that particular delivery option.
The crucial field is the deliveryOptionId which directly identifies the desired delivery option to the booking api.
The documentation on the  is quite exhaustive!
After further inquiry, it turns out that the bookingInstructions information should be passed in to the shipment booking with the deliveryOptionId as a referenceNo with the corresponding referenceType = "ZDO".
Booking shipments:
The Book EDI Instruction & get Labels endpoint is called to book an order. It also returns the freight label ready to be printed. If no label is needed, one can simply call Book shipment based on the EDI instruction.
Do not confuse these with the Book Pickups endpoint, which is used for smaller retailers who don't have recurring scheduled pickups, and where from address is necessarily stated in each call.
Book Pickups is a separate  which requires slightly more information than the regular booking endpoint(s), most notably said from address.
For all booking API:s the best sequence is to first call the Delivery Options API and then directly use the returned bookingInstructions as inputs. This ensures availability and minimum required add-on features.
Shipment Information:
The shipmentInformation object in the call to the EDI instruction booking endpoint(s) contains information about the parcels (one shipment can contain multiple) and their dimensions, weights and quantities. All the magnitudes are accompanied by their respective units, which is convenient albeit somewhat clunky because of unit names such as MTQ (cubic metre) and CMT (centimetre). The id is the only mandatory field for each product.
Mandatory fields, flattened to omit non-mandatory intermediary types:

Message date: timestamptz
Update indicator: string (Z11=PostNord Denmark, Z13=PostNord Norway, Z14=PostNord Finland)
Shipment

Basic service code: string ("19" for MyPack Collect etc)


Parties

Consignor

Name: string (person or company)
Postal code: string
Country code: string (ISO 3166)
City: string




Items (items in the shipment)

ItemID: string (likely one individual parcel in the shipment)



Non-mandatory but important fields:

Consignee (for some reason not mandatory, but this is the "to" address. Possibly the to address can be entirely on the label)

Same fields as consignor -||-


References

Reference no: string (this is where deliveryOptionId goes)
Reference type: string (ZDO if DO has been used)


Additional service code: string (Appears to be one per shipment. Will inquire more about this! Additional service codes can come from the DO api but also need to be manual)

Handling unavailable destinations:
Not a problem if the Delivery Options API is called first, since it simply won't return anything in case of an unsupported address. However, Postnord claim complete coverage so it shouldn't ever happen. Additionally, the booking API will return error if the location is not supported.
Cancellations:
Postnord confirms there is no way to cancel bookings via their api.
Creating a label:
Note that label printing of size "Small" does NOT work for packages. The label size option "Ps1" is cryptic but means 10x15cm.
Addons
PostNord's documentation on additional services is quite substandard. Depending on where you look, different sets of services are available for their different freight products.
 and  talked to PostNord Kundintegration and got a list of the most common addons for the relevant products.
In addition to the list provided by PostNord Kundintegration, we have chosen to base our addons on the ones available to customers on their website and in their price lists.







, , , 

Here is the total list of addons we have included:
| Postnord addon | Type     | Description                         |Currently supported in integration
| -------------- | -------- | ----------------------------------- |----
| 16           | boolean |  Sunday drop-off                 |         ❌        |
| 17           | boolean |  Two deliveries if first fail            |    ❌    |
| 24           | boolean |  Extended identification             |      ❌      |
| 57           | boolean |  Advance notification         |           ❌        |
| 7            | boolean |  Retention time 30 days        |         ❌         |
| A1           | boolean |  Cash on delivery                     |      ❌     |
| A2           | boolean |  "eBrevsavisering". Current interpretation is a notification by an E-letter service (i.e. Kivra)". Current interpretation is a notification by an E-letter service (i.e. Kivra)      |  ✅  |
| A3           | boolean |  SMS notification                    |     ✅       |
| A4           | boolean |  Email notification                  |      ✅      |
| A5           | boolean |  Goods insurance                   |        ✅       |
| A6           | boolean |  No proof of delivery           |        ✅        |
| A7           | boolean |  Servicepoint by choice              |      ❌       |
| A8           | boolean |  Dangerous goods     |                     ❌        |
| B8           | boolean |  Notification by driver before delivery    |   ❌    |
| C1           | boolean |  Recipient freight                |       ❌       |
| C4           | boolean |  Identification by id            |         ✅        |
| C5           | boolean |  Delivery notification                |     ✅       |
| C6           | boolean |  Completion notification              |     ✅       |
| C7           | boolean |                         |  ❌   |
| D1           | boolean |  Immediate return                 |          ❌      |
| D2           | boolean |  Proof of delivery                     |       ✅    |
| D3           | boolean |  Advance notification                     |    ❌    |
| D4           | boolean |                        |  ❌   |
| D5           | boolean |  Private receiver                 |       ❌         |
| D6           | boolean |  Delivery before 09:00                        |  ❌  |
| D7           | boolean |  Delivery before 12:00                        |  ❌  |
| D8           | boolean |  Identification by minimum age                   | ✅ |
| D9           | boolean |  Climate compensation               |       ✅       |
| E1           | boolean |  Delivery of tyres                             |  ❌ |
| E4           | boolean |  Collect in store                 |       ❌         |
| E5           | boolean |  Collect in Store Label Only      |        ❌        |
| F1           | boolean |  Same day delivery                 |        ❌        |
| F6           | boolean |  Next day delivery                    |     ❌       |
| G3           | boolean |  Retention time 14 days         |           ❌       |
| G4           | boolean |  Retention time 7 days            |          ❌      |
| H1           | boolean |  Delivery to parcel locker                  |   ❌   |
| M5           | boolean |  No delivery to parcel locker             |   ❌    |
Varubrev Ekonomi
| Postnord addon | Skrym addon             | Type      | Description             |
| -------------- | ----------------------- | --------- | ----------------------- |
| A2           | letter-notification   | boolean | Notification by physical letter       |
| A3           | sms-notification        | boolean |  SMS notification        |
| A4           | email-notification      | boolean |  Email notification      |
| C5           | notify-before-delivery   | boolean |  Delivery notification    |
Varubrev 1:a Klass
| Postnord addon | Skrym addon             | Type      | Description              |
| -------------- | ----------------------- | --------- | ------------------------ |
| A2           | letter-notification   | boolean | Notification by physical letter        |
| A3           | sms-notification        | boolean |  SMS notification         |
MyPack Collect
| Postnord addon | Skrym addon                      | Type      | Description                          |
| -------------- | -------------------------------- | --------- | ------------------------------------ |
| A2           | letter-notification   | boolean | Notification by physical letter       |
| A3           | sms-notification        | boolean |  SMS notification         |
| A4           | email-notification      | boolean |  Email notification      |
| A5           | freight-insurance                           | boolean |  Goods insurance                    |
| C4           | identification-by-national-id      | boolean |  Identification by id              |
| D8       