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
...
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. |
...
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. |
...
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. | ||||
proofOfDelivery | string | 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 |
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).
...
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. |
...
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. |
...
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 |
...
Field | Description |
---|---|
statusCode | The HTTP code associated with this error. |
errorKey | A machine parseable error code. |
errorMap | Additional details pertaining to the error. |
...