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)
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 |
---|---|---|---|---|---|
type | string | recipient | n/a | consignee and consignor are required as part of the request. The type of party involved. Following alternatives are legal:
| |
id | string | 0123456789 | 17 | Identifier that can be used to identify the same party between different shipments. | |
name | string | Ola Nordmann |
| 105 | Name of party. |
countryCode | string | NO |
| 3 | Country code, according to ISO 3166-1. |
postalName | string | OSLO | 35 | Also known as city. | |
zipCode | string | 0155 |
| 9 | Also known as postal code. |
address | string | Storgaten 11A H0202 | 105 | Combined address information with the following format:
| |
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. |
string | 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 |
---|---|---|---|---|---|
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. |
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:
|
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. |
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 |
---|---|---|---|
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 |
---|---|---|---|---|
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 |
---|---|---|---|---|
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
Carrier specific requirements
Carrier | Requirements |
---|---|
Helthjem B2B | consignee.id is required |
Helthjem C2B and C2C | consignor.phone1 or consignor.email is required shipment.desiredDeliveryDate 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 | 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
Consignee.phone1 and consignor.phone1 are validated, including
|
Premo C2C | consignor.phone1 or consignor.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 | consignee.phone1 is required consignee.name and consignor.name only allow 50 characters
|
Postnord home delivery Sweden (via Dooris) | item.trackingReference must be in s10 format if specified consignee.name and consignor.name only allow 50 characters |
ODA | consignee.phone1, consignee.email, consignee.postalName, consignee.zipCode is required Extra phone validation added, only valid phone numbers allowed |
Zoopit | 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 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
|
Response
Name | Type | Example | Mandatory | 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 | |
list of party objects | Note that the API could make minor changes to the returned consignee address. | |||
list of item objects | See description with the same name in the request. | |||
map of properties | Map with additional properties. Various information (properties) are specified only for certain transport products. | |||
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 |
---|---|---|---|
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. |