Parcel Event Log V2

Content

[ 1 Use of service ] [ 2 Setup ] [ 3 Environments / endpoints ] [ 4 Making a request ] [ 5 Response ] [ 6 Examples ] [ 7 Error handling ]

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

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 GET	`https://staging-ws.di.no/ws/json/parcel/tracking/v-2/fetch/{identifier}/{locale}/{onlyLastEvent}`
PRODUCTION GET	`https://ws.di.no/ws/json/parcel/tracking/v-2/fetch/{identifier}/{locale}/{onlyLastEvent}`

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, only latest status

Request header

key	value example	comment

key	value example	comment
Authorization	`Bearer $SECRET_WS_TOKEN`	see Setup
Content-Type	application/json

Path parameters

parameter	example	description

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

Curl request example

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

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.

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

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

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
Parcel Event Log v1#eventType	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
Parcel Event Log v1#regSystem	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

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 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

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

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

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

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

[
    {
        "shipmentNumber": "70724760120000880",
        "shopName": "Testbutikken",
        "shopId": 1,
        "consigneeReference": null,
        "consignorReference": null,
        "properties": {},
        "items": [
            {
                "trackingNumber": "370724760120000898",
                "returnCode": null,
                "freightProductId": 1,
                "freightProductName": "helthjem",
                "parcelStatus": null,
                "linkedParcelNumbers": [],
                "events": [
                    {
                        "eventTime": "2017-11-09 04:13:23",
                        "lat": null,
                        "lon": null,
                        "locationContext": "OSLO",
                        "locationContextId": null,
                        "eventType": {
                            "apiKey": "013",
                            "description": "Pakken er levert",
                            "i18nKey": "event.type.distr.shipment.delivered"
                        },
                        "additionalInfo": null,
                        "eventGroup": {
                            "id": 4,
                            "name": "event.type.group.status"
                        },
                        "comChannelType": null,
                        "changeUserId": null,
                        "regSystem": null,
                        "message": null
                    },
                    {
                        "eventTime": "2017-11-09 00:33:43",
                        "lat": null,
                        "lon": null,
                        "locationContext": "Beh.engangslev.",
                        "locationContextId": null,
                        "eventType": {
                            "apiKey": "013",
                            "description": "Pakken er levert",
                            "i18nKey": "event.type.distr.shipment.delivered"
                        },
                        "additionalInfo": null,
                        "eventGroup": {
                            "id": 4,
                            "name": "event.type.group.status"
                        },
                        "comChannelType": null,
                        "changeUserId": null,
                        "regSystem": null,
                        "message": null
                    },
                    {
                        "eventTime": "2017-11-08 05:20:28",
                        "lat": null,
                        "lon": null,
                        "locationContext": "OSLO",
                        "locationContextId": null,
                        "eventType": {
                            "apiKey": "013",
                            "description": "Pakken er levert",
                            "i18nKey": "event.type.distr.shipment.delivered"
                        },
                        "additionalInfo": null,
                        "eventGroup": {
                            "id": 4,
                            "name": "event.type.group.status"
                        },
                        "comChannelType": null,
                        "changeUserId": null,
                        "regSystem": null,
                        "message": null
                    },
                    {
                        "eventTime": "2017-11-07 05:45:03",
                        "lat": null,
                        "lon": null,
                        "locationContext": "OSLO",
                        "locationContextId": null,
                        "eventType": {
                            "apiKey": "013",
                            "description": "Pakken er levert",
                            "i18nKey": "event.type.distr.shipment.delivered"
                        },
                        "additionalInfo": null,
                        "eventGroup": {
                            "id": 4,
                            "name": "event.type.group.status"
                        },
                        "comChannelType": null,
                        "changeUserId": null,
                        "regSystem": null,
                        "message": null,
                        "eventData": null
                    }
                ]
            }
        ]
    }
]

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

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

{
    "statusCode": 401,
    "errorKey": "authentication.missing",
    "errorMap": {}
}

Field	Description

Field	Description
statusCode	The HTTP code associated with this error.
errorKey	A machine parseable error code.
errorMap	Additional details pertaining to the error.