Parcel Event Log v1
Content
Use of service
Event log API v1 is used to receive all events registered for a tracking reference or shipment number. If you wish to get meta data about the parcel (shop, delivery method ect.) in addition to the events, use the more extensive version https://jira-di.atlassian.net/wiki/pages/resumedraft.action?draftId=1883144376.
Events are static data points and do not contain personal.
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 https://jira-di.atlassian.net/wiki/spaces/DIPUB/pages/968622088.
We reserve the right to limit users who misuse this service.
Setup
| 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
Parcel Tracking
Environments / endpoints
TEST GET | https://staging-ws.di.no/ws/json/parcel/tracking/v-1/fetch/{identifier}/{locale}/{onlyLastEvent} |
|---|---|
PRODUCTION GET | https://ws.di.no/ws/json/parcel/tracking/v-1/fetch/{identifier}/{locale}/{onlyLastEvent} |
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
Clients using this API should not fail if new fields are added to the response. If a new field is added to the response on a later stage, existing clients should handle this in a way such as they just ignore the field.
Fields not set in the response are not left out, that is fields in the response may have null values. E.g. "shipmentNumber": null. The client using the endpoint should handle this.
For shipments older than 6 months no events will be available.
Request header
key | value example | comment |
|---|---|---|
Authorization | Bearer $SECRET_WS_TOKEN | |
Content-Type | application/json |
Path parameters
parameter | example | description |
|---|---|---|
identifier | 370724760010119754 | Shipment or item identifier |
locale | NO | Language code. eventDescription will be translated to locale. Supported languagecodes 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
curl --request GET --url https://staging-ws.di.no/ws/json/parcel/tracking/v-1/fetch/370724760120000898/NO/false \
--header "Authorization: Bearer $SECRET_WS_TOKEN" \
--header 'Content-Type: application/json' \Response
New events and changes to existing events can be done at any time. Clients using this API should not fail if new API keys or IDs are added (events, event groups, additional info)
Duplicate events may occur on a rare occasion. The technology used to communicate events between different sources have an error margin below 0.001%, which may result in duplicates.
Events may be added at a later time than the timestamp indicates, the client should handle this
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.
Name | Type | Description |
|---|---|---|
list of events | List of events |
Events
Name | Type | Example | Max Length | Mandatory | Description |
|---|---|---|---|---|---|
shipmentNumber | string | (401)70712190172720651 | 35 |
| Globally unique identifier for the shipment. Typically a GINC code. |
trackingReference | string | (00)370724760010119754 | 35 |
| Tracking reference for the item, typically a SSCC gs1 code. |
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. Time zone: |
eventTimeUtc | string | 2025-06-12T08:08:23.456000Z | 27 |
| The UTC timestamp of when the event was registered in the originating system. Provides extra precision compared to If the originating system does not specify this field, it will be generated based on the |
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. This is defined/set by the users, and not by the system/default. |
eventType | eventType object | n/a |
| Description of the event, will be translated to defined locale | |
additionalInfo | additionalInfo object | n/a |
| 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 |
| Communication channel only used for event types within event group "communication". ComChannelTypes in use:
|
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 | Mandatory | Description |
|---|---|---|---|---|---|
apiKey | string | 001 | n/a |
| Identifier for the event group |
description | string | Package received | n/a |
| Static description of the 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 /tes |
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 | Mandatory | Description |
|---|---|---|---|---|---|
id | whole number | 1 | n/a |
| identifier for the event group |
name | string | communication | 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
Access level determines the first part of translation key (i18nKey). It can be either one of:
event.type.pub/event.type.ai.pub
event.type.shopadmin/event.type.ai.shopadmin
event.type.distr/event.type.ai.distr.
For example: apiKey 002 event.type.distr.shipment.received