Sign in

nShift Help Center

My Parcels API

Avatar
Malene Tidemann
Updated

API overview

Call Description
POST /shipment-data/v2/shipments Create or update shipment

 

 

POST /shipment-data/v2/shipments

Parameters

Mandatory parameters

Parameter Mandatory? Type Description
externalSystemId Optional String Unique id to update/identify an existing shipment if shipment number or parcel number is not yet available (mandatory without shipmentNumber and parcel number)
shipmentNumber Optional String The id used to identify the shipment (mandatory without parcelNumber and externalSystemId)
transportServiceCode Mandatory String Your unique code identifying the transport service used
orderNumber Optional String Order number associated with the shipment
pickupPointId Optional String Id of the receiving service/pickup point the shipment will be delivered to
weight Optional number 

The weight of the shipment
sender Mandatory JSON

Address information
receiver Mandatory JSON

Address information
trackingIdentifiers Mandatory JSON Identifiers used to track this shipment 

 

 

Receiver parameters

Spec for receiver JSON.

Parameter Mandatory? Type Description
name Optional String  
addressLines Optional Array of Strings Address lines, max 3 lines
postCode Mandatory String  
city Optional String  
countryCode Mandatory String For instance "SE"

 

 

Sender parameters

Spec for sender JSON.

Parameter Mandatory? Type Description
name Mandatory String  
addressLines Optional Array of Strings Address lines, max 3 lines
postCode Optional String  
city Optional String  
countryCode Optional String For instance "SE"

 

 

trackingIdentifiers parameters

Spec for email and phone JSON.

Parameter Mandatory? Type Description
type Mandatory String [phone OR email] type of identifier
value Mandatory String Address lines, max 3 lines
role Optional String [sender OR receiver] role of the owner of the email/phone identifier

At least one trackingIdentifier of either email or phone is mandatory.

 

 

Parcel parameters

Spec for the parcel JSON.

Parameter Mandatory? Type Description
parcelNumber Mandatory* String  
weight Mandatory number Weight in kg.
measurements Optional JSON  

*Depending on carrier parcelNumber or shipmentNumber is used (one is mandatory).

 

 

Measurements parameters

Spec for the measurements JSON.

Parameter Mandatory? Type Description
length Optional number Length in metres
width Optional number Width in metres
height Optional number Height in metres
weight Optional number Weight in metres

At least one trackingIdentifier of either email or phone is mandatory.

 

One Shipment:

[
   {
      "externalSystemId": "137598-452345",
      "shipmentNumber": "12345678",
      "transportServiceCode": "P15",
      "pickupPointId": "665172",
      "orderNumber": "myOrder-1",
      "sender": {
         "name": "Kalle Anka",
         "postCode": "29874",
         "addressLines": [
            "Ankeborgsvägen 27",
            "C/O Pappa Anka"
         ],
         "countryCode": "SE",
         "city": "Ankeborg"
      },
      "receiver": {
         "name": "Kajsa Anka",
         "addressLines": [
            "Friluftsvägen 27",
            "C/O Farmor Anka"
         ],
         "city": "Sundbyberg",
         "postCode": "17240",
         "countryCode": "SE"
      },
      "trackingIdentifiers": [
         {
            "type": "email",
            "value": "kalle.anka@duckmail.com"
         },
         {
            "type": "phone",
            "value": "070123456"
         }
      ],
      "parcels": [
         {
            "parcelNumber": "456782929",
            "measurements": {
               "length": 1,
               "width": 2,
               "height": 3,
               "weight": 4.5
            }
         },
         {
            "parcelNumber": "456782930",
            "measurements": {
               "length": 0.2,
               "width": 0.1,
               "height": 0.2,
               "weight": 5
            }
         }
      ]
   }
]

 

Minimal JSON for one Shipment:

[
   {
      "transportServiceCode": "test-posten-pickup",
      "sender": {
         "name": "Company Stuff Ltd"
      },
      "receiver": {
         "postCode": "17240",
         "countryCode": "SE"
      },
      "trackingIdentifiers": [
         {
            "type": "phone",
            "value": "070123456"
         }
      ],
      "parcels": [
         {
            "parcelNumber": "373323996687321077"
         }
      ]
   }
]

 

Responses

Successful import HTTP response code 202

{
   "result": "SUCCESSFUL",
   "validationErrors": []
}

 

Failed import HTTP response code 422

{
   "result": "FAILED",
   "validationErrors": [
      {
         "externalSystemId": "137598-452345",
         "result": "FAILED",
         "errors": [
            {
               "field": "transportServiceCode",
               "message": "Missing"
            }
         ]
      }
   ]
}

 

Partial Successful batch request HTTP response code 202

{
   "result": "PARTIAL_SUCCESS",
   "validationErrors": [
      {
         "externalSystemId": "137598-452345",
         "result": "FAILED",
         "errors": [
            {
               "field": "receiver",
               "message": "Missing"
            }
         ]
      }
   ]
}

 

Error Responses

Invalid credentials HTTP response code 401

{
   "errorCode": "401",
   "userMessage": "Bad credentials"
}

 

Unauthorized access HTTP response code 403

{
   "errorCode": "403",
   "userMessage": "Forbidden"
}


Malformed json HTTP response code 400

{
   "errorCode": "400",
   "userMessage": "Unexpected end-of-input within/between Object entries at [Source: [  {\"externalSystemId\":\"137598-452345\",    \"sender\": {      \"name\": \"Company Stuff Ltd\"    }, ; line: 7, column: 102] at [Source: [  {   \"externalSystemId\":\"137598-452345\",    \"sender\": {      \"name\": \"Company Stuff Ltd\"    }, ; line: 6, column: 5] (through reference chain: Object[][0])"
}

 

 

Related articles