Versions Compared

Old Version 58

changes.mady.by.user Ingrid Oliversen

Saved on

compared with

New Version Current

changes.mady.by.user Katarzyna Antonsen

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Content

Table of Contents
maxLevel32
minLevel1
typeflat

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.

...

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

Status
colourBlue
titleGET

Code Block
https://staging-ws.di.no/ws/json/parcel/tracking/v-1/fetch/{identifier}/{locale}/{onlyLastEvent}

PRODUCTION

Status
colourBlue
titleGET

Code Block
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. 

...

Info

  • 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

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

Code Block
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' \

...

Info

  • 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

Mandatory

Description

shipmentNumber

string

(401)70712190172720651

35

Globally unique identifier for the shipment. Typically a GINC code.

trackingReference

string

(00)370724760010119754

35

(tick)

Tracking reference for the item, typically a SSCC gs1 code.

eventTime

string

2017-08-22 13:55:13

19

(tick)

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

(tick)

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

(tick)

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

(tick)

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

(tick)

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

(tick)

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:

...

For example: apiKey 002 event.type.distr.shipment.received

An additionalinfo APIkey must always be considered in the context of a main event.

...

Expand
titleList of APIkeys

apikey

i18nkey - translation

Translation key

Description

Final status

(not exact match with translation in event log API)

Event data

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

{"pickupCode": "XXXXX"}

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

(tick)

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

The parcel has not been assigned a route (no alias). Notify the manager of this station

Can not find alias for this parcel, verify correct transport setup or split load carrier

020

.scanned.unknown.station

Parcel (address) is connected to Posten. Connect parcel to a route or scan at return-station

The parcel has unknown destination and alias could not be assigned

021

.scanned.invalid.tracking.number

Tracking reference is invalid.

Notify the manager of this station

022

022

.scanned.wrong.location

Parcel sorted for wrong location.

Please scan this parcel on a return-station

023

.scanned.return.rescan

Scanned

, sort this parcel again

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

(tick)

027

.support.ticket.created

A support ticket was created for this parcel

028

.retry.delivery

New

activation in the electronic delivery guide

planned delivery scheduled

029

.retry.pickup

New

activation for the electronic delivery guide

pick-up try scheduled

030

.shipment.lost

Parcel lost

(tick)

031

.unable.to.pickup

Parcel not picked up

032

.shipment.retrieved

Parcel picked-up

(tick)

034

.return.not.found

Could not find parcel for pick-up

035

.returned.cannot.deliver

Parcel is returned to store/sender

(tick)

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

(tick)

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

{"distributionDate": "YYYY-MM-DD"}"

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

...

titleList of additionalinfoAPIkeys

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

154

.shipment.fallback.solution.triggered

The shipment will be delivered using the fallback solution

155

.pickup.deadline.extended

The pickup deadline was extended

{"deadline": "YYYY-MM-DD"}"

156

.parcel.picked.up.at.servicepoint

Parcel picked up by a driver

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

i18nkey - translation

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

Expand
titleExample response
Code Block
{
    "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

...

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.

...

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.