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 |
|---|---|---|
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 |
|---|---|---|
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 |
|---|---|---|---|---|---|
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. | |
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. 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. | |
desiredDeliveryTimePeriod | string | 1930-2130 |
| 9 | Time format HHmm-HHmm (desiredDeliveryTimeStart - desiredDeliveryTimeEnd) |
list of Parcel Booking API#party objects |
| n/a | List of parties involved in this shipment. | ||
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. |
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)