Parcel Booking API

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

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

Mandatory

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:

  1. "CarrierCompany express home delivery" (freightProductId = 1)

  2. "CarrierCompany standard home delivery" (freightProductId = 2)

  3. "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

Mandatory

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

CO address

detailedAddress

DetailedAddress object

 

 

 

Can be used to specify parts of the 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.

DetailedAddress

Can be used in conjunction with the regular address field, by adding more specific information in each field, which will then be used when linking to specific addresses in Main.

If both streetName and streetNumber is supplied, this will also used instead of the regular address field for coverage checks.

Name

Type

Example

Mandatory

Max length

Description

Name

Type

Example

Mandatory

Max length

Description

streetName

String

Karl Johans gate

Required if the regular address field is not specified

40

Name of the street

streetNumber

String

25

Required if the regular address field is not specified

5

 

floorType

String

H

 

1

  • H (main floor)

  • U (basement)

  • L (attic)

  • K (cellar)

floorNumber

String

2

 

5

 

flatNumber

String

1, H0101

 

5

 

entrance

String

A

 

5

 

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

Mandatory

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

Mandatory

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.