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 Parcel events push notification.
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	see Parcel Event Log v1#Authentication
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:

NO - Norwegian
EN - English

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
events	list of events	List of events

Events

Name	Type	Example	Max Length	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
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.
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

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

List of APIkeys

apikey	Translation key	Description (not exact match with translation in event log API)	Final status
001	.import.edi.information.received	Parcel arrival notified
002	.shipment.received	Parcel has been received
003	.shipment.forwarded	Parcel is being loaded for transport
004	.shipment.under.transport	Parcel is in transit
005	.shipment.forwarded.to.servicepoint	Parcel is being transferred to a service point
006	.shipment.arrived.at.servicepoint	Parcel has arrived at local service point
007	.requested.consignee.addresscollect	Address Collector sent to recipient
008	.consignee.notification.response	The recipient has submitted the address collector form
009	.consignee.order.confirmation	An order confirmation has been sent to the recipient
010	.consignee.package.on.its.way	"Parcel on it's way" sent to recipient
011	.consignee.delivery.notification	"Parcel delivered" sent to the recipient
012	.consignee.transport.change.notification	"Parcel will be delivered by a partner carrier" sent to recipient
013	.shipment.delivered	Parcel delivered
015	.returned.to.sender	Parcel bound for return processing
016	.shipment.scanned.ok	Parcel has been scanned
017	.scanned.missing.package.data	No EDI-information received for this shipment
018	.scanned.wrong.station	Parcel scanned at wrong station. Please change station and scan again
019	.scanned.no.alias	Can not find alias for this parcel, verify correct transport setup or split load carrier
020	.scanned.unknown.station	The parcel has unknown destination and alias could not be assigned
021	.scanned.invalid.tracking.number	Tracking reference is invalid.
022	.scanned.wrong.location	Parcel sorted for wrong location.
023	.scanned.return.rescan	Scanned
024	.scanned.ok.return.scan	Return-scan ok
025	.scanned.ok.return.scan.destruction	Parcel is scanned for return and should be destructed
026	.shipment.exported	Parcel will be delivered by a partner carrier
027	.support.ticket.created	A support ticket was created for this parcel
028	.retry.delivery	New planned delivery scheduled
029	.retry.pickup	New pick-up try scheduled
030	.shipment.lost	Parcel lost
031	.unable.to.pickup	Parcel not picked up
032	.shipment.retrieved	Parcel picked-up
034	.return.not.found	Could not find parcel for pick-up
035	.returned.cannot.deliver	Parcel is returned to store/sender
036	.shipment.unknown.external.code	Unknown status notification from external transporter
038	.pickup.confirmation.consignee	"Parcel has been picked-up" sent to recipient
039	.pickup.confirmation.consignor	"Parcel has been picked-up" sent to the sender
040	.pickup.reject.consignor	"Parcel not picked-up" sent to sender
041	.pickup.reminder	"Reminder of scheduled pick-up" sent to sender
042	.pickup.not.found.consignor	"Parcel not found, with option to set new pick-up date" sent to sender
043	.import.ready.for.delivery	Parcel is ready to be delivered to the recipient
045	.registered.complaint.a	A complaint (type A) was registered for this shipment
046	.registered.complaint.k	A complaint (type K) was registered for this shipment
047	.registered.complaint.x	A complaint (type X) was registered for this shipment
048	.registered.complaint.y	A complaint (type Y) was registered for this shipment
056	.consignor.updated.pickup	The sender has changed pick-up date
057	.shipment.not.delivered	Parcel not delivered
060	.pickup.cancelled	Pick-up of parcel has been cancelled
061	.wanted	Enquired parcel. This parcel should not be delivered. Return to store/sender
062	.loaded	The shipment has been loaded for transport
063	.unloaded	Parcel has been unloaded from car
064	.registered.complaint.r	A complaint (type R) was registered for this shipment
065	.registered.complaint.ae	A complaint (type Æ) was registered for this shipment
066	.registered.complaint.l	A complaint (type L) was registered for this shipment
067	.registered.complaint.p	A complaint (type P) was registered for this shipment
068	.not.delivered	Parcel not delivered
069	.unacknowledged	Parcel not acknowledged
058	.consignee.notification.response.same.address	Recipient has confirmed that delivery address is correct
059	.consignee.notification.response.wrong.address	Recipient has submitted a new delivery address. If possible the parcel will be delivered by one of our partner carriers
070	.closed.complaint	Complaint closed
071	.consignor.delivery.notification	"Parcel delivered" sent to sender
072	.shipment.export.no.tracking.notification	Parcel will be delivered without tracking within 2-6 working days.
073	.admin.order.cancelled	Order has been cancelled
074	.consumer.order.cancelled	Order has been cancelled
075	.admin.changed.shipment.date	Store admin has changed shipment date
076	.consumer.changed.shipment.date	The customer has changed date for shipment
077	.delivery.deactivated	New activation in EDG has been cancelled as the parcel has received a final status
092	.shipment.under.customs.clearance	Parcel is under customs clearance
093	.shipment.incorrectly.sorted	Parcel has been sorted incorrectly and will unfortunately be slightly delayed
078	.consignee.refund.delivery.unsuccessful	"Delivery failed, amount is reimbursed" sent to recipient
079	.consignee.delivered.gift	"Gift delivered" sent to recipient
080	.consignor.delivered.gift	"Gift delivered" sent to sender
081	.consignor.not.delivered.gift	"Gift not delivered" sent to sender
082	.consignee.awaiting.processing	"Awaiting processing" sent to recipient
083	.consignor.processing.gift.order	"Gift order is being processed" sent to sender
084	.consignor.gift.order.final.status	"Gift order with final status" sent to sender
085	.consignee.gift.order.final.status	"Gift order with final status" sent to recipient
086	.consignee.order.partially.delivered	"Order partially delivered" sent to recipient
087	.consignee.order.final.status	"Order with final status" sent to recipient
088	.consignee.gift.order.partially.delivered	"Gift order partially delivered" sent to recipient
089	.consignee.paper.notification	A written notice has been sent to recipient
090	.consignee.sms.notification	A SMS has been sent to recipient
091	.consignee.mail.notification	A notification has been sent to the recipient by email
094	.generated.label	Label has been generated
096	.pickup.reject.consignor.new.pickup	"Parcel not picked-up, with option to set new pick-up date" sent to sender
097	.pickup.not.found.consignor.new.pickup	"Parcel not found, with option to set new pick-up date" sent to sender
095	.shipment.not.picked.up.returned.to.sender	"Parcel not picked up at service point and will be returned to sender"
100	.order.changed	The order has been changed
101	.delivery.ordered	Delivery to household is ordered for this parcel
102	.order.deviation	Unfortunately, the parcel may be delayed due to a deviation.
103	.order.notification.sent	Delivery notification sent to customer
098	.pickup.ready	Pick up parcel is ready to be picked up by distribution
099	.destination.change.re.labeled	Re-labeled after destination change
104	.delivered.at.service.point	Parcel delivered to service point
105	.parcel.delivered.to.shop	Parcel is delivered to a store
106	.load.carrier.scanned.ok	Load carrier has been scanned and closed
107	.load.carrier.received	Load carrier has been received and is beeing loaded for transport
108	.consignor.order.confirmation	"Order confirmation" sent to sender
109	.consignee.parcel.under.processing	"Parcel in process" sent to recipient
110	.shipment.forwarded.to.external.system	Parcel information sent to external system
111	.system.delivered	Delivered (system message)
112	.parcel.destination.changed	Destination has been changed
113	.delivery.activated	Parcel activated
114	.consignor.order.receipt	Receipt sent to sender
115	.scanned.wrong.mode	Parcel has been scanned in outgoing mode
116	.parcel.arrived.at.end.station	Parcel has arrived at end station
117	.package.arrived	"Parcel ready for pick-up" sent to recipient
118	.package.reminder	"Reminder parcel ready for pick-up" sent to recipient
119	.package.pickupextension	"Pick-up period extended" sent to recipient
120	.package.lastreminder	"Reminder for parcel ready for pick-up after extended period" sent to recipient
121	.package.returned	"Parcel returned" sent to sender
122	.parcel.delivered.for.return.servicepoint	Parcel delivered for return at servicepoint
123	.parcel.rerouted.to.servicepoint.notification	"Parcel rerouted to service point" sent to recipient
124	.image.of.delivery.taken	Additional information for delivery available
125	.unwanted	The parcel is no longer enquired. To be delivered to the recipient.
126	.shipment.received.external	Partner carrier has recieved the parcel
127	.shipment.not.delivered.second.attempt	"Parcel not delivered after second attempt" sent to recipient
128	.shipment.not.delivered.first.attempt	"Parcel not delivered after first attempt" sent to recipient
129	.return.package.reminder	"Reminder to return item" sent to recipient
131	.package.first.scan	"Parcel in value chain" sent to recipient
132	.shipment.rebooked	Parcel changed freightproduct from incoming scan
133	.deleted.complaint	Complaint deleted
134	.consignee.sms.fallback.notification	"Parcel will be delivered with fallback option" sent to consignee
135	.consignee.email.fallback.notification	"Parcel will be delivered with fallback option" sent to consignee
136	.order.clearance.ok	Parcel passed customs clearance
137	.order.clearance.not.ok	Parcel dit not pass customs clearance
138	.order.damaged	Parcel damaged
139	.order.not.complete.when.received	Parcel was received incomplete/incorrect
140	.address.not.complete	Given order address not complete
141	.registered.common.complaint	A complaint has been registered for this order
142	.not.possible.to.contact.party	Not possible to contact consignor/consignee
143	.missing.wrong.delivery.info	Missing or wrong delivery info
144	.consignee.identified.id	Consignee identified with ID
145	.missing.incomplete.edi	Missing or incomplete EDI
146	.ignore.previous.event.incorrect	Ignore previous event
147	.submission.code.received	Updated parcel details information from external carrier
148	.transport.booking.failed	Booking failed to be registreres with carrier/transporter
149	.add.parcel.to.customs.report	Parcel added to customs report in Flow
150	.alias.retrieved	Cargostream alias retrieved using APIs. Is not a scan.
151	.shipment.distribution.date.changed	The distribution date for the parcel has changed.
152	.communication.sent	Some form of communication has been sent. Use the eventData field to specify what
153	.communication.failed	Some form of communication has failed. Use the eventData field to specify what

List of additionalinfoAPIkeys

An additionalinfo APIkey must be considered in the context of main event. Below is a suggestion of the main event/trigger, but the additional information can be paired with all main events.

main event (trigger)	additionalinfoAPIkey	Translation key	Description
(057) Not delivered / (015) Return	001	.cannot.deliver.missing.deliverypoint	carrier can't find customer
(057) Not delivered / (015) Return	002	.cannot.deliver.missing.key	Key missing
(057) Not delivered / (015) Return	003	.cannot.deliver.parcel.damaged	shipment damaged
(057) Not delivered / (015) Return	004	.cannot.deliver.customer.changed.address	The recipient has changed address
(015) Return	005	.cannot.deliver.customer.absent	The recipient is absent, on vacation or does not collect the shipment
(030) Lost	006	.cannot.deliver.shipment.lost.internal	in our value chain
(030) Lost	007	.cannot.deliver.shipment.lost.external	before our value chain
Address collector form	008	.consignee.notification.response.updated	with new details
Address collector form	009	.consignee.notification.response.same.address	and confirmed existing delivery address
Address collector form	010	.consignee.notification.response.wrong.address	with a new delivery address
(013) Delivered	011	.shipment.delivered.door	on the doormat
(013) Delivered	012	.shipment.delivered.mailbox	in the mailbox
(013) Delivered	013	.shipment.delivered.bag	Mailbox (Bag and hook)
(057) Not delivered / (015) Return	014	.cannot.deliver.unfit.deliverypoint	Unsuited delivery point
(031) Unable to pick-up	015	.unable.to.pickup.not.found	The parcel was not found
(031) Unable to pick-up	016	.unable.to.pickup.not.marked	The parcel was not clearly marked
(031) Unable to pick-up	017	.unable.to.pickup.not.wrapped	Not packed according to instructions
(031) Unable to pick-up	018	.unable.to.pickup.too.big	The parcel was too heavy/big
(031) Unable to pick-up	019	.unable.to.pickup.no.customer.contact	Unable to reach costumer
(031) Unable to pick-up	020	.unable.to.pickup.missing.key	Key missing
(031) Unable to pick-up	021	.unable.to.pickup.return.lost	Return-parcel lost
(032) Picked-up	022	.shipment.retrieved.at.route.branch	Received at route branch
(032) Picked-up	023	.shipment.retrieved.not.at.rout.branch	Not received at route branch
(057) Not delivered	024	.cannot.deliver.not.received	carrier did not receive the shipment
(057) Not delivered	025	.cannot.deliver.missing.deliverypoint.mailbox	carrier can't find customer. Mailbox delivery
(057) Not delivered	026	.cannot.deliver.missing.deliverypoint.house.door	carrier can't find customer. Delivery at house
(057) Not delivered	027	.cannot.deliver.missing.deliverypoint.apartment.door	carrier can't find customer. Delivery in apartment
(057) Not delivered / (030) Lost	028	.cannot.deliver.shipment.lost.stolen	Stolen

Examples

Example response

{
    "events": [
        {
            "shipmentNumber": "70724760120000880",
            "trackingNumber": "370724760120000898",
            "eventTime": "2017-11-09 07:00:39",
            "lat": null,
            "lon": null,
            "locationContext": null,
            "eventType": {
                "apiKey": "011",
                "description": "Pakke levert sendt til mottaker"
            },
			"additionalInfo": null,
            "eventGroup": {
                "id": 3,
                "name": "Communication"
            },
            "comChannelType": "SMS",
            "changeUserId": null,
            "regSystem": null,
            "message": null
        },
        {
            "shipmentNumber": "70724760120000880",
            "trackingNumber": "370724760120000898",
            "eventTime": "2017-11-09 04:13:23",
            "lat": null,
            "lon": null,
            "locationContext": "OSLO",
            "eventType": {
                "apiKey": "013",
                "description": "Pakken er levert til mottaker"
            },
            "additionalInfo": null,
			"eventGroup": {
                "id": 4,
                "name": "Status"
            },
            "comChannelType": null,
            "changeUserId": null,
            "regSystem": null,
            "message": null
        },
		{
            "shipmentNumber": "70724760120000880",
            "trackingNumber": "370724760120000898",
            "eventTime": "2017-11-08 23:00:39",
            "lat": null,
            "lon": null,
            "locationContext": "OSLO",
            "eventType": {
                "apiKey": "057",
                "description": "Pakken er ikke levert"
            },
            "additionalInfo": {
                "apiKey": "001",
                "description": ". Finner ikke mottakers leveringspunkt"
            },
            "eventGroup": {
                "id": 4,
                "name": "event.type.group.status"
            },
            "comChannelType": null,
            "changeUserId": null,
            "regSystem": {
                "id": 2,
                "name": "eBudbok"
            },
            "message": null
        },
        {
            "shipmentNumber": "70724760120000880",
            "trackingNumber": "370724760120000898",
            "eventTime": "2017-11-08 15:00:39",
            "lat": null,
            "lon": null,
            "locationContext": "Nettbutikk AS",
            "eventType": {
                "apiKey": "001",
                "description": "Informasjon om forsendelsen er mottatt"
            },
			"additionalInfo": null,
            "eventGroup": {
                "id": 1,
                "name": "Import"
            },
            "comChannelType": null,
            "changeUserId": null,
            "regSystem": null,
            "message": 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
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
statusCode	The HTTP code associated with this error.
errorKey	A machine parseable error code.
errorMap	Additional details pertaining to the error.