List events from the event log.
Content
| Table of Contents |
|---|
...
|
...
|
...
|
...
|
...
|
...
Example
...
Username (see Authentication section)
...
wsfoobar
...
Password (see Authentication section)
...
a-very-very-long-password
Contact you transport carrier partner to obtain this information.
...
| Info |
|---|
Notes
|
...
|
Use of service
Event log API v2 is an extensive API used to receive all events registered for a tracking reference or shipment number, in addition to meta data about the parcel (shop, delivery method ect.). If you only wish to see all registrered events use Parcel Event Log V1.
Events are static data points and do not contain personal or variable data points.
There are three access levels for the event log API. The level is configured per web service user, ask you contact person if you have questions about your access.
The different levels give access to different events, and may have different wording (description) for the same event to communicate
Public access
Web shop access
Distribution access
If you wish to track a batch of shipments and get live updates for all new tracking events use the push service Parcel events push notification.
We reserve the right to limit users who misuse this service.
Setup
Access to API | Example |
|---|---|
Username (see Authentication section) | wsfoobar |
Password (see Authentication section) | a-very-very-long-password |
The user is a web service user
The user has access to the web service for
Tracking
Environments / endpoints
TEST
|
| ||||||||
|---|---|---|---|---|---|---|---|---|---|
PRODUCTION
|
|
...
Making a request
...
key
...
value example
...
comment
...
Authorization
...
| Code Block |
|---|
Bearer $SECRET_WS_TOKEN |
...
see Setup
...
Content-Type
...
application/json
...
parameter
...
example
...
description
...
identifier
...
370724760010119754
...
Shipment number, tracking number or return code.
...
locale
...
NO
...
Language code. Event description will be translated to locale. Supported language codes are currently:
NO - Norwegian
EN - English
SE - Swedish
...
onlyLastEvent
...
false
...
If set to true only the last registered event is returned. Last registered is decided based on eventTime. If false, all available events are returned
...
The endpoint require authentication, as described here: LoginV2
...
List of shipments relevant for the request. Usually there will only be one shipment, but in cases where the way of delivery have been changed for one or more items, it may have been put on a different shipment.
In those cases the "linkedParcelNumber" under shipment items will link to the parcelnumber in the "new" shipment.
...
Name
...
Type
...
Example
...
Max length
...
Description
...
shipmentNumber
...
whole number
...
70724760120000880
...
35
...
Globally unique identifier for the shipment, typically a GINC code. Typically named MessageNumber, DocumentNumber or ConsignorsReference in EDI.
...
shopName
...
string
...
Testbutikken
...
50
...
Name of the shop/owner party of the shipment
...
shopId
...
whole number
...
1
...
5
...
ID of the of the shop/owner party of the shipment
...
consigneeReference
...
string
...
o123
...
35
...
Usually an orderId or some other reference chosen by the shop/owner party.
...
consignorReference
...
string
...
o123
...
35
...
Usually an orderId or some other reference chosen by the shop/owner party.
...
properties
...
properties object
...
-
...
n/a
...
Not in use
...
items
...
list of items
...
n/a
...
Name
...
Type
...
Example
...
Max length
...
Description
...
trackingNumber
...
whole number
...
370724760120000898
...
35
...
Unique identifier for an item/kolli in the shipment. This can be a SSCC code according to gs1, or a UPU S10 identifier.
Typically named TransporterInstructionMark in EDI.
...
returnCode
...
string
...
R-1234
...
10
...
Optional additional unique identifier, used for pick up parcels
...
freightProductId
...
whole number
...
1
...
10
...
The freight product describes a way of delivery, and is defined by a delivery method and the coverage of the given method.
...
freightProductName
...
string
...
ekspress levering hjem
...
50
...
The freight product describes a way of delivery, and is defined by a delivery method and the coverage of the given method.
...
parcelStatus
...
string
...
Levert
...
25
...
Tracking status for the item/kolli
...
linkedParcelNumbers
...
list of linkedParcelNumbers
...
n/a
...
List of trackingNumber(s) for the same physical object, used when several different ways of delivery have been used.
...
events
...
list of events
...
n/a
...
Name
...
Type
...
Example
...
Max Length
...
Description
...
eventTime
...
string
...
2017-08-22 13:55:13
...
19
...
Time of the event registered in originating system. Datetime format yyyy-MM-dd HH:mm:ss
...
lat
...
double
...
59.911096
...
9
...
Latitude for the location of the event
...
lon
...
double
...
10.752457
...
9
...
Longitude for the location of the event
...
locationContext
...
string
...
Osloveien 14, 0288 Oslo
...
255
...
Address or description of the location/ context of the event
...
locationContextId
...
string
...
34567
...
10
...
Unique identification of the locationContext
...
...
eventType
...
eventType object
...
n/a
...
Description of the event, will be translated to defined locale
...
Parcel Event Log v1#additionalInfo
...
additionalInfo
...
additionalInfo object
...
n/a
...
Additional description of the event, will be translated to defined locale
...
Parcel Event Log v1#eventGroup
...
eventGroup
...
eventGroup object
...
n/a
...
Groupage of event, e.g. transportation events, communication events etc.
...
communicationChannel
...
string
...
SMS
...
n/a
...
Communication channel only used for event types within event group "communication".
ComChannelTypes in use:
SMS
EMAIL
...
changeUserId
...
whole number
...
112233
...
n/a
...
Internal user identification responsible for the event taking place. Only returned for callees having the highest access level
...
...
regSystem
...
regSystem object
...
n/a
...
System that registered the event
...
message
...
string
...
255
...
Optional message from the system registering the event
eventType
...
Name
...
Type
...
Example
...
Max length
...
Description
...
apiKey
...
string
...
001
...
n/a
...
Identifier for the event group
...
description
...
string
...
Package received
...
n/a
...
| Info |
|---|
|
Request header
key | value example | comment | ||
|---|---|---|---|---|
Authorization |
| see Setup | ||
Content-Type | application/json |
Path parameters
parameter | example | description |
|---|---|---|
identifier | 370724760010119754 | Shipment number, tracking number or return code. |
locale | NO | Language code. Event description will be translated to locale. Supported language codes are currently:
|
onlyLastEvent | false | If set to true only the last registered event is returned. Last registered is decided based on eventTime. If false, all available events are returned |
Curl request example
| Code Block |
|---|
curl -X GET \
https://ws.di.no/ws/json/parcel/tracking/v-2/fetch/370724760120000898/NO/false \
-H 'Authorization: Bearer $SECRET_WS_TOKEN' \
-H 'Content-Type: application/json' \ |
Response
| Info |
|---|
|
The API will respond with a list of shipments relevant for the request. The response may contain events for one or several parcels. The respons will contain events for several parcels if the shipment number specified in the request contains several parcels/items or if one of the parcels has had a change of delivery method (freightproduct). If the same physical parcel/item changes delivery method it will receive a new tracking reference and shipment number, and the IDs will be linked with the original identifications.
In those cases the "linkedParcelNumber" under shipment items will link to the tracking reference in the "new" shipment.
Name | Type | Example | Description | |
shipmentNumber | whole number | 70724760120000880 | 35 | Globally unique identifier for the shipment, typically a GINC code. Typically named MessageNumber, DocumentNumber or ConsignorsReference in EDI. |
shopName | string | Testbutikken | 50 | Name of the shop/owner party of the shipment |
shopId | whole number | 1 | 5 | ID of the of the shop/owner party of the shipment |
consigneeReference | string | o123 | 35 | Usually an orderId or some other reference chosen by the shop/owner party. |
consignorReference | string | o123 | 35 | Usually an orderId or some other reference chosen by the shop/owner party. |
properties | properties object | - | n/a | Not in use |
items | list of items | n/a |
Items
Name | Type | Example | Max length | Description |
|---|---|---|---|---|
trackingNumber | whole number | 370724760120000898 | 35 | Unique identifier for an item/kolli in the shipment. This can be a SSCC code according to gs1, or a UPU S10 identifier. Typically named TransporterInstructionMark in EDI. |
returnCode | string | R-1234 | 10 | Optional additional unique identifier, used for pick up parcels |
freightProductId | whole number | 1 | 10 | The freight product describes a way of delivery, and is defined by a delivery method and the coverage of the given method. |
freightProductName | string | ekspress levering hjem | 50 | The freight product describes a way of delivery, and is defined by a delivery method and the coverage of the given method. |
parcelStatus | string | Levert | 25 | Tracking status for the item/kolli |
linkedParcelNumbers | list of linkedParcelNumbers | n/a | List of trackingNumber(s) for the same physical object, used when several different ways of delivery have been used. | |
events | list of events | n/a |
Events
Name | Type | Example | Max Length | Description |
|---|---|---|---|---|
eventTime | string | 2017-08-22 13:55:13 | 19 | Time of the event registered in originating system. Datetime format yyyy-MM-dd HH:mm:ss |
lat | double | 59.911096 | 9 | Latitude for the location of the event |
lon | double | 10.752457 | 9 | Longitude for the location of the event |
locationContext | string | Osloveien 14, 0288 Oslo | 255 | Address or description of the location/ context of the event |
locationContextId | string | 34567 | 10 | Unique identification of the locationContext |
eventType | eventType object | n/a | Description of the event, will be translated to defined locale |
i18nKey
string
additionalInfo | additionalInfo object | n/a |
Key which can be used to add your own translations
...
Name
Type
Example
Max length
Description
apiKey
string
Additional description of the event, will be translated to defined locale | ||||
eventGroup | eventGroup object | n/a | Groupage of event, e.g. transportation events, communication events etc. | |
communicationChannel | string | SMS | n/a |
Identifier for the additional info group
description
string
Communication channel only used for event types within event group "communication". ComChannelTypes in use:
| |||
changeUserId | whole number | 112233 | n/a |
Static description of the event, will be translated to defined locale. Can be concatenated with the Parcel Event Log v1#eventType description for a more detailed description. The formatting is already taken care of
i18nKey
string
event.type.pub.shipment.received
n/a
Key which can be used to add your own translations
...
Internal user identification responsible for the event taking place. Only returned for callees having the highest access level | ||||
regSystem | regSystem object | n/a | System that registered the event | |
message | string | 255 | Optional message from the system registering the event | |
eventData | string | notification_template | 255 | Optional data for the event |
eventType
Name | Type | Example | Max length | Description |
|---|
apiKey |
string |
001 | n/a |
Identifier for the event group |
description | string |
Package received | n/a |
Static description of the |
Group id
Description
1
Information on shipments received/imported in DI
2
Information on transportation
3
Information on communication
4
Information on status updates
5
Information on scanning of shipments
6
Information for shipments transported by others
7
Information from/relating to external systems
8
Information on internal processing
...
Name
...
Type
...
Example
...
Max length
...
Description
...
id
...
whole number
...
1
...
n/a
...
identifier for the originating system
...
name
...
string
...
Postnord
...
n/a
...
named classification of the originating system
...
Curl request
| Code Block | ||
|---|---|---|
| ||
curl -X GET \
https://ws.di.no/ws/json/parcel/tracking/v-2/fetch/370724760120000898/NO/false \
-H 'Authorization: Bearer $SECRET_WS_TOKEN' \
-H 'Content-Type: application/json' \ |
Response
...
| language | xml |
|---|
...
event, will be translated to defined locale | ||||
i18nKey | string | event.type.pub.shipment.received | n/a | Key which can be used to add your own translations |
additionalInfo
Name | Type | Example | Max length | Description |
|---|---|---|---|---|
apiKey | string | 001 | n/a | Identifier for the additional info group |
description | string | Package received | n/a | Static description of the event, will be translated to defined locale. Can be concatenated with the Parcel Event Log v1#eventType description for a more detailed description. The formatting is already taken care of |
i18nKey | string | event.type.pub.shipment.received | n/a | Key which can be used to add your own translations |
eventGroup
Name | Type | Example | Max length | Description |
|---|---|---|---|---|
id | whole number | 1 | n/a | identifier for the event group |
name | string | communcation | n/a | named classification of the group |
Group id | Description |
|---|---|
1 | Information on shipments received/imported in DI |
2 | Information on transportation |
3 | Information on communication |
4 | Information on status updates |
5 | Information on scanning of shipments |
6 | Information for shipments transported by others |
7 | Information from/relating to external systems |
8 | Information on internal processing |
regSystem
Name | Type | Example | Max length | Description |
|---|---|---|---|---|
id | whole number | 1 | n/a | identifier for the originating system |
name | string | Postnord | n/a | named classification of the originating system |
List of possible events
Check documentation Parcel Eventlog V1
Examples
| Expand | ||||
|---|---|---|---|---|
| ||||
|
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 |
|---|---|---|
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
| Code Block |
|---|
{ "statusCode": 401, } "errorKey": "authentication.missing", ] "errorMap": {} } } ] |
...
|
Field | Description |
|---|---|
statusCode | The HTTP code associated with this error. |
errorKey | A machine parseable error code. |
errorMap | Additional details pertaining to the error. |