Parcel Booking API

The purpose of this API is to register a parcel shipment. Given the data in the request, this API will perform the booking and return the corresponding transport information

Contents

[ 1 Setup ] [ 2 Environments / endpoints ] [ 3 Authentication ] [ 4 Making a request ] [ 5 Response ] [ 6 Examples ] [ 7 Error handling ]

Setup

Make sure you have the following information at hand before proceeding. Your carrier provider will generate/provide these values for you

	Example	Description

	Example	Description
Username (see Authentication section)	wsfoobar	A valid username.
Password (see Authentication section)	a-very-very-long-password	A password matching given username.
shopId	12345	All bookings are made with respect to a given shop.
transportSolutionId	55	An identifier for a valid transport solution. The transport solution determines how the booked package will be distributed.

The user is a web service user
The user has access to the web service for booking
The user has access to the shop where registering the parcel
The shop has access to the specified transport solution

Environments / endpoints

Please use the TEST-endpoint while developing your system. By doing this you ensure that your test-data will not pollute any potential external systems or production.

TEST	POST	`https://staging-ws.di.no/ws/json/parcel/booking/v-1/book`
PRODUCTION	POST	`https://ws.di.no/ws/json/parcel/booking/v-1/book`

Authentication

This endpoint requires the user to be authenticated. Refer to the documentation here for more information on how to obtain a valid token to use in your request.

Making a request

Notes

The booking endpoint is called once per order.
Clients using this API should not fail if new optional fields are added to the API. If a new field is added to the request or response on a later stage, existing clients should handle this in a way such as they just ignore the field.
Some carriers may have more specific validation or input requirement than the general API, this is documented at the end of this section. Marked in request section

Request-Headers

key	value example	comment

key

value example

comment

Authorization

Bearer "SECRET_WS_TOKEN"

See authentication on how to obtain a token

Content-Type

application/json

Idempotency-Key

"defined by client"

Optional, up to 40 characters. This header can be set by the client in order to make sure that no booking happens twice. The length of the text part of the header can be up to 40 characters. A request set with a unique client specified Idempotency-Key is only saved once on success, i.e. the risk of sending a duplicate order can be handled by the client by specifying a client side unique identifier for the order. The API will return the same response every time after a successful request with the same Idempotency-Key header set.

For active pick-up parcels (C2X) in DI Last mile distribution duplicate bookings will have the field "trackingReference" populated with actual tracking reference, not return code as default in first booking response.

Request body

Name	Type	Example	Mandatory	Max Length	Description

Name	Type	Example	Max Length	Description
shopId	whole number	95123	n/a	The shop this booking is made for.
shopDisplayName	string	My Company Ltd	30	A user presentable name of the shopId. This will typically be used if another name than the normal name of the shop should be used in communication with the customer. Maximum 30 characters.
transportSolutionId	whole number	1	n/a	A transport solution is a construct that contains multiple freight products. Its purpose is to group what freight products a customer has access to. See further explanation in transport solutions section.
shipmentId	string	(401)70712190172720651	35	ShipmentId is identificator for the entire order. If not specified as a part of the request this will be generated and returned in the response with gs1 format as default. This should be a globally unique identifier. Typically named MessageNumber, DocumentNumber or ConsignorsReference in EDI. If you wish to define your own shipmenId use the GS1 international standard GINC (official documentation). If you are using other identification numbers contact your sales company to make sure the series is supported/configured correctly.
desiredDeliveryDate	string	20160120	8	Date format yyyyMMdd. This date should be defined as distribution date. For deliveries (B2C) it is date of delivery, for pick up (C2B/C2C) this field will be used as date of pick up by carrier. Optional field that can be specified if the parcel should be delivered/picked up on a specific date. If the specified date is not supported, then the freight product is not be supported. This means that the field is mandatory for for example labelless pick-up freight products.
desiredDeliveryTimePeriod	string	1930-2130	9	Time format HHmm-HHmm (desiredDeliveryTimeStart - desiredDeliveryTimeEnd) Default value '2000-2200' will be used as delivery time interval if it is not given.
parties	list of Parcel Booking API#party objects		n/a	List of parties involved in this shipment.
items	list of item objects		n/a	List of all the items in this shipment. At least one item is required.
messageToCarrier	string		350	Typically delivery instructions. This information can be placed on some shipping labels in the information field.
messageToConsignee	string		350	This information can be placed on some shipping labels in the information field.
additionalServices	list of additionalService objects			Additional services that should be applied to the shipment. Must be configured for the shop before use.

Transport Solutions

A transport solution is composed of one or more freight products. A freight product describes a way of delivery, and is defined by a delivery method and the coverage of the method. The freight products included in a transport solution are ordered by priority (defined by the carrier company).

An example to illustrate the relation between a transport solution and its freight products: There is the transport solution "CarrierCompany home delivery w/ServicePoint fallback" (e.g. transportSolutionId = 1). The transport solution consist of the following freight products:

"CarrierCompany express home delivery" (freightProductId = 1)
"CarrierCompany standard home delivery" (freightProductId = 2)
"CarrierCompany ServicePoint" (freightProductId = 3)

When a booking request is made with transportSolutionId = 1, the booking API first checks if the request address and item measures is covered by the "CarrierCompany express home delivery", followed by "CarrierCompany standard home delivery" and finally "CarrierCompany ServicePoint". The highest priority freight product that is available for the specifications in the booking request determines the freight product (delivery method). The freightProductId will be present in the Booking API response. If no freight product covers the specifications in the booking request, the API will return an error response.

Remark that access to transport solutions are given per shop. Contact you carrier provider to determine which shopID(s) and transport solution ID(s) to use. It is not possible to registrer a booking directly to a freight product ID, but your carrier can provide a transportsolution with only the desired freight product as available response.

Party

Name	Type	Example	Mandatory	Max Value	Description

Name	Type	Example	Max Value	Description
type	string	recipient	n/a	consignee and consignor are required as part of the request. The type of party involved. Following alternatives are legal: consignee (Party to which the shipment are delivered to, normally the buyer of the goods) consignor (Party sending/delivering the shipment. For B2C, this is typically a store or a warehouse) returnAddress (Used if other than consignor party) servicePoint (Can be specified in the request if the client wants to suggest a service point for a freight product. If specified in the request, the same service point is returned in the response if the resulting freight product has a servicePoint. If no service point was specified in the request and the resulting freight product deliver through servicePoint the closest ServicePoint is returned as part of the response) pickupAddress (Can be specified in the request if the client wants to suggest a second service point for a freight product. Only relevant for a limited number of freight products. If specified in the request, the same service point is returned in the response if the resulting freight product has a pickupAddress. If no service point was specified in the request and the resulting freight product pick up through service point the closest service point is returned as part of the response)
id	string	0123456789	17	Identifier that can be used to identify the same party between different shipments. Must not be used if you have duplicate IDs for different customers or know if the shipment actually is for the same consumer. Then all shipments will be linked to the same consumer
name	string	Ola Nordmann	105	Name of party. Mandatory for consignee and consignor.
countryCode	string	NO	3	Country code, according to ISO 3166-1. Mandatory for consignee and consignor.
postalName	string	OSLO	35	Also known as city.
zipCode	string	0155	9	Also known as postal code. Mandatory for consignee and consignor.
address	string	Storgaten 11A H0202	105	Combined address information with the following format: Street name Street number (with leading space) Entrance Floor type (only relevant for countryCode=NO) H (main floor) U (basement) L (attic) K (cellar) Floor number Flat number
coaddress	string	Kari Nordmann	255	Care of address
phone1	string	+47 402 10 000	100	This is used for delivery confirmation and other automated SMS notification.
phone2	string	+47 402 20 000	100	This can be used for other automated SMS notification.
email	string	ola@nordmann.no	100	This can be used for automated email notification.
reference	string	012345	35	This can be an orderId or some other reference. consignee and consignor reference can be placed on some shipping labels.
contact	string	Customer service contact name	35	Contact information for the party. Consignee contact can be printed on some shipping labels.

Item

An item represents a physical parcel, with trackingReference as identifier. Structure your request with the same number of items as you want to have labels/physical parcels in your order.

Name	Type	Example	Mandatory	Max Length	Description

Name	Type	Example	Max Length	Description
itemNumber	whole number	1	n/a	Item/package number of the shipment. If there are 3 items in a shipment these items should have itemNumber 1,2 and 3. Each item/package will result in one unique trackingReference and label.
trackingReference	string	(00)370724760010119754	35	If not specified as a part of the request this will be generated and returned in the response. If you wish to define your own trackingReference use the gs1 international standard SCC (official documentation). If you are using other identification numbers contact your sales company to make sure the series is supported. Typically named TransporterInstructionMark in EDI.
returnCode	string	XX-12345	10	Must be between 8 and 10 characters. If the code is to be used in any other DI APIs, there are some additional requirements: Start with one or more letters Then a dash - End with up to 8 letters or numbers, totalling maximally 10 characters
weight	whole number	600	n/a	Measuring unit is gram.
volume	decimal number	4	n/a	Measuring unit is cubic decimeter.
length	decimal number	120	n/a	Measuring unit is centimeter.
height	decimal number	5	n/a	Measuring unit is centimeter.
width	decimal number	12	n/a	Measuring unit is centimeter.
externalSupplierId	String	5415	n/a	ExternalSupplierId is the id of the supplier to the shop. It can be used for access control or filtering. Must be configured for the shop before use. If service supplier specified in file is not configured (or does not exist) booking will be accepted and only linked to shop Service supplier is connected to shop, no validation for coverage or other attributes
contentValue	decimal number	580	n/a	Currency is according to the location of the shopId.
contents	string	Brown shirt	100	Description of the contents. This can be placed on some shipping labels.
properties	map of item properties		n/a	Map with additional properties. Various information (properties) are specified only for certain transport products.
articles	list of Parcel Booking API#article objects			List of articles included in the item.

Item properties

Name	Type	Example	Description

Name	Type	Example	Description
shortItemIdentifier	string	...0255	This can be placed on some shipping labels.
productType	string	Bread	Optional additional description of item.

Article

An article describes the content of your item/parcel. Mainly relevant if used for integrations with warehouse management systems.

Name	Type	Example	Mandatory	Description

Name	Type	Example	Description
articleNumber	string	"ART-1"	An identifier for the article.
quantity	whole number	1	The quantity of the article.
articleName	string	Brown shirt	Name/description for the article.

Additional Services

Name	Type	Example	Mandatory	Description

Name	Type	Example	Mandatory	Description
key	string	ASA		The key for the service. Note that the service must be configured for the shop before use.
value	string	null		Some services require an additional value to be included in the request. The value is ignored if the value is not required for the service.

Available Additional Services

Key	Example value	Description

Key	Example value	Description
ASA	null	A service for sending labels by mail to consumers. A use case is when a consumer is to send a package that requires a label, and does not have access to a printer.
ASB	"MYWMS"	A service for integration with an external packaging system, WMS. Additional service value is required, and the service must be preconfigured for the shop.
A1	"199:NOK:9876543210"	Specifies that the recipient is to pay for the parcel on delivery (Cash on Delivery). Format: "<amount>:<currency>:<sellers reference>". Colon is used as separator. Both amount and currency is required, while sellers reference (KID number) is optional.
RNL	true	A service to specify if the end-user is requires to show identification in order to pick up parcel
ASC	"https://di.no\|Description"	A service where the party registrering the order can specify a custom URL and description for each order. This is only used to add specific information to labels fetched from the Parcel Label API, and the specific labels have to pre-designed with a layout for this input/QR code Pipe symbol \| is used as separator. Only qrCodeUrl is required, while qrCodeDescription is optional.
ASD	"41412756\|Hei dette er en gave!"	A service to specify that this booking is a gift. The service shows the gift senders phone number and the message from the gift sender to the gift receiver.
ASE	null	Orders marked with this are registered as label-less, and have an additional id/code to identify the parcel instead of the regular label. The parcel still has a shipmentId and tracking reference, but the shorter (more consumer friendly ID) is an additional identification. This is frequently used for C2C and C2B parcels
POD	SIMPLE_CONFIRMATION	Planned Proof Of Delivery (POD) set for the parcel, applied to all items in the shipment. Possible values: NO_CONFIRMATION, SIMPLE_CONFIRMATION, SCAN, SCAN_AND_PICTURE, PICTURE

Carrier specific requirements

Carrier	Requirements

Carrier	Requirements
Helthjem B2B	consignee.id is required
Helthjem C2B and C2C	consignor.phone1 or consignor.email is required consignee.phone1 or consignee.email is required shipment.desiredDeliveryDate If specified this day represents the date where the carrier should pickup the package and should be earliest tomorrow. The consignor / sender will be instructed to lay out the package the day before pickup. Use of the field will result in an active pick-up order shipment.item - Only one item allowed for return solutions. item.trackingReference - This field should never be set by the callee. Tracking reference for pick-up packages is generated by the system and returned in the response. Callee should support all types and formats as identifier/code for pick-up parcels.
Helthjem B2C	Do not use consignee.id
Early Bird	Do not use consignee.id
Postnord C2C Norway (via helthjem)	consignee.name and consignor.name only allow 50 characters Consignee.address and consignor.address only allow 50 characters consignee.postalName and consignor.postalName is required Weight is required Consignee.email and consignor.email is validated by standard e-mail verification, including does not contain invalid symbols (letters, numbers and symbol: @ , . allowed) has a valid structure (xx@xx.xx) use a valid domain Consignee.phone1 and consignor.phone1 are validated, including Deliveries in Norway: + or 00 [country code starting with 3 or 4]. Norwegian local number starting with 4 or 9. Deliveries in Sweden: + or 00 [country code starting with 3 or 4]. Swedish local number starting with 07. Deliveries in Finland: + or 00 [country code starting with 3 or 4]. Finnish local number starting with 04 or 050. Deliveries in Denmark: + or 00[country code starting with 45] Danish local number starting with 5.
Premo C2C	consignor.phone1 or consignor.email is required consignee.phone1 or consignee.email is required shipment.desiredDeliveryDate - If specified this day represents the date where the carrier should pickup the package and should be earliest tomorrow. The consignor / sender will be instructed to lay out the package the day before pickup.Use of the field will result in an active pick-up order shipment.item - Only one item allowed for return solutions. item.trackingReference - This field should never be set by the callee. Tracking reference for pick-up packages is generated by the system and returned in the response. Callee should support all types and formats as identifier/code for pick-up parcels.
Postnord ServicePoint Sweden (via Dooris)	consignee.phone1 is required consignor.address is required consignee.name and consignor.name only allow 50 characters consignee.address and consignor.address only allow 50 characters consignee.coaddress and consignor.coaddress only allow 50 characters consignee.postalName and consignor.postalName only allow 50 characters consignee.email and consignor.email only allow 70 characters Consignee.phone1 and consignor.phone1 are validated, including Deliveries in Norway: + or 00 [country code starting with 3 or 4]. Norwegian local number starting with 4 or 9. Deliveries in Sweden: + or 00 [country code starting with 3 or 4]. Swedish local number starting with 07. Deliveries in Finland: + or 00 [country code starting with 3 or 4]. Finnish local number starting with 04 or 050. Deliveries in Denmark: + or 00[country code starting with 45] Danish local number starting with 5
Postnord home delivery Sweden (via Dooris)	item.trackingReference must be in s10 format if specified shipmentId can be included in booking, but is not used by Postnord and not searchable at Postnord sites. consignee.name and consignor.name only allow 50 characters consignee.address and consignor.address only allow 50 characters consignee.coaddress and consignor.coaddress only allow 50 characters consignee.postalName and consignor.postalName only allow 50 characters consignee.email and consignor.email only allow 70 characters
ODA (via helthjem)	consignee.phone1, consignee.email, consignee.postalName, consignee.zipCode is required Extra phone validation added, only valid phone numbers allowed
Zoopit (via helthjem)	shipment.desiredDeliveryTimePeriod is used to specify the delivery time interval
Morgenlevering (company)	item.externalSupplierId is required
Amedia B2C	item.trackingReference is required, and can be in format gs1, s10 or DPD shipmentId is required, and can be in format gs1, s10 or DPD If item.trackingReference or shipmentId is not specified general gs1 format will be used and returned in the response. For DPD format the AI identifier `%` is required in order to extract the shipment number / tracking reference. Valid DPD strings: `(%)0004326136193011084461015786` `%0004326136193011084461015786`

Response

Name	Type	Example	Mandatory	Description

Name	Type	Example	Description
shipmentId	string	(401)70712190172720651	See description with the same name in the request.
freightProductId	whole number	2	The selected freight product for this shipment. See example freight products ablow
parties	list of party objects		Note that the API could make minor changes to the returned consignee address.
items	list of item objects		See description with the same name in the request.
properties	map of properties		Map with additional properties. Various information (properties) are specified only for certain transport products.
additionalServices	list of additionalService objects		See description with the same name in the request.
proofOfDelivery	string	NO_CONFIRMATION	See description with the same name in the request.

Freight Products

The freight product describes a way of delivery, and is defined by a delivery method and the coverage of the given method. Contact you carrier provider to determine which freight product ID(s) you'll have access to and can expect in the response.

Properties

Name	Type	Example	Description

Name	Type	Example	Description
productCode	string	72	This can be placed on some shipping labels.
productName	string	Home delivery express	This can be placed on some shipping labels.
routingCode	String	OSL	This can be placed on some shipping labels.
issuerNumber	String	1	This can be placed on some shipping labels.
customerNumber	String	1234567	This can be placed on some shipping labels.
missionCode	String	2341-75213437173(90)1300034123456772-GH	This can be placed on some shipping labels.
routing	String	1234-01/4321-02-dropp x4321x12345	This can be placed on some shipping labels. The format depends on last mile carrier setup, and not all information points are required and the length of each information point may also vary. The general definition is describes below "XXXX-yyy/ZZZZ-www-DropCode xRRRRRxSSSSS" where XXXX = pre transport main car number (if exists) ZZZZ = local transport main car number yy and ww = drop number for specified car DropCode = description of drop point RRRR = last mile route SSSSS = drop number on last mile route
routeName	String	56789	This can be placed on some shipping labels.
routeAddress	String	My address 12	This can be placed on some shipping labels.
routeDescription	String		This can be placed on some shipping labels.
routingDescription	String		This can ble placed on some shipping labels.

Examples

Example 1: Specifying a standard B2C order

Curl request standard B2C

curl --request POST --url https://staging-ws.di.no/ws/json/parcel/booking/v-1/book \
     --header "Authorization: Bearer $SECRET_WS_TOKEN" \
     --header 'Content-Type: application/json' \
     --data "{ \
               \"shopId\": 100, \
               \"transportSolutionId\": 1, \ 
               \"parties\": [{\"type\": \"consignee\", \"name\": \"Ola Norman\", \"countryCode\": \"NO\", \"postalName\": \"OSLO\", \"zipCode\": \"1234\", \
                              \"address\": \"MyAddress 182\", \"phone1\": \"95990099\", \"email\": \"ola.norrman@example.com\"}, \
                             {\"type\": \"consignor\", \"name\": \"shopName\", \"countryCode\": \"NO\", \"zipCode\": \"1234\"} ], \
               \"items\": [{\"itemNumber\": 1, \"weight\": 400, \"contents\": \"Shoes\", \"properties\": {\"ProductType\": \"Shoes\"}}] \
             }"

Response example Json standard B2C

Example 2: Specifying a standard B2C with servicePoint

Comment: Notice that servicePoint is added to the response. Servicepoint can also be specified in the request.

Curl request standard B2C with servicePoint

Response example Json standard B2C with servicePoint

Example 3: Specifying a standard B2B order

Special attributes:

Request must specify "id" for the consignee (must be pre-registered)
Response includes "retailerId" that should be placed on the label.

Curl request B2B

Response example Json B2B

Example 4: Specifying a standard C2C order

Comment: notice that the format of the trackingReference in the response is different for return solutions.

Curl request C2C

Response example Json C2C

Example 5: Specifying Additional Service ASB with Item Articles

Note that the additional service must be activated for the shop, and that the value of the additionalService object must be preconfigured. The additional service, ASB, requires at least one article per item.

Curl request Additional Service with Item Articles

Response example Additional Service with Item Articles

Error handling

API requests that result in errors will return an appropriate HTTP status code to help you identify the type of error. You can use the table below to understand what each code means, og search online with the HTTP status code. The HTTP error keys used are based on the standard, and therefore available online (Tips to search “HTTP code XXX”)

In addition to HTTP status there may be more details in the errorKey field. Error Keys can be added at a later stage, clients should handle this as well as an empty value for errorKey.

HTTP Status code	Text	Description

HTTP Status code	Text	Description
400	Client or Validation Error	The request body/query string is not in the correct format.
401	Authentication Failure	Indicates that the Authorization header is either missing or incorrect. You can learn more about the Authorization header here.
403	Access denied	This indicates that the agent whose credentials were used in making this request was not authorized to perform this API call. It could be that you do not have access to the shop or transportsolution you provided in your request. If you believe this is a mistake, please reach out to your contact so it can be rectified.
405	Method not allowed	This API request used the wrong HTTP verb/method. For example a PUT request will result in this error.
4xx	Client error	Generally receiving an error code that starts with 4 indicates that the client needs to change something.
500	Unexpected Server Error	Oops! This may indicates an error on our side. Please try again, if the error continues notify your contact person

Error response

In addition to the HTTP status code, most errors will also return a response body that contains more information to help you debug the error. A sample error response is shown below. The format of the error response body is explained after the example.

Sample error

Field	Description

Field	Description
statusCode	The HTTP code associated with this error.
errorKey	A machine parseable error code.
errorMap	Additional details pertaining to the error.

Error Keys

Other notes

DI receive Norwegian postal numbers and coordinates from GEODATA ( LINK) - based on this our algorithm calculates closest ServicePoint