Versions Compared

Old Version 19

changes.mady.by.user Ingrid Oliversen

Saved on

compared with

New Version 20

changes.mady.by.user Ingrid Oliversen

Saved on

Key

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


Content

Table of Contents
maxLevel3

...

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

Status
colourBlue
titleGET

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

PRODUCTION

Status
colourBlue
titleGET

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

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


Request header

key

value example

comment

Authorization

Code Block
Bearer $SECRET_WS_TOKEN

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:

  • 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

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

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)

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

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

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

...

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

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.