My Parcels API – nShift Help Center

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])"
}

nShift Help Center