Sign in

nShift Help Center

Constructing a Shipment Request for ShipmentServer API

Avatar
Simon Schrader Springer
Updated

This article outlines how to construct a SubmitShipment request for the ShipmentServer API.
This API allows you to programmatically book shipments and generate labels.

 

Endpoint and Method:

The request should be a POST request to the following endpoint:

  • Production - https://www.shipmentserver.com
  • Sandbox - https://demo.shipmentserver.com

 

Request Body (multipart/form-data):

The request body should be formatted as multipart/form-data with the following key-value pairs:

  • command: Always set to "SubmitShipment". This tells the API what action to perform.
  • actor: The Id of the actor. This is your username.
  • key: The key of the actor. This is your password.
  • data (JSON String): This field contains the core shipment information.
  • options (JSON String): This field allows you to specify additional options, such as the label format.


The data.json file contains the necessary details for booking a shipment, including unique identifiers, sender and receiver addresses, and package specifications such as dimensions and weight.

-- filename: data.json

{
  "ProdConceptID": 1782, // Your product concept ID
  "OrderNo": "Order123", // Your order number
  "Addresses": [
    {
      "Kind": 1, // 1 for Receiver, 2 for Sender
      "Name1": "Receiver Name",
      "Street1": "Receiver Street",
      "PostCode": "Receiver Postal Code",
      "City": "Receiver City",
      "CountryCode": "Receiver Country Code",
      "Phone": "Receiver Phone",
      "Email": "receiver@example.com",
      "Attention": "Receiver Attention" // Optional
    },
    {
      "Kind": 2, // 1 for Receiver, 2 for Sender
      "Name1": "Sender Name",
      "Street1": "Sender Street",
      "PostCode": "Sender Postal Code",
      "City": "Sender City",
      "CountryCode": "Sender Country Code",
      "Phone": "Sender Phone",
      "Email": "sender@example.com",
      "Attention": "Sender Attention" // Optional
    }
  ],
  "Lines": [
    {
      "Number": 1, // Line number
      "PkgWeight": 1000, // Package weight in grams
      "Height": 10, // Height in mm
      "Length": 20, // Length in mm
      "Width": 15, // Width in mm
      "References": [
        { "Kind": 23, "Value": "Reference 1" }
      ]
    }
  ]
}


The options.json file specifies the label format, indicating that the label should be generated in ZPL format for printing on Zebra printers.

-- filename: options.json

{
    "Labels": "ZPLGK"
}

 

Construction of the payload(data) object

While it's technically possible to construct the data JSON payload manually, it's highly recommended to initially create the shipment through the Ship UI and have it validated by the carrier before attempting to automate the process. This step ensures data accuracy and avoids potential issues caused by incorrect formatting or missing required fields.

 

To learn about the Developer Tool in Ship UI:
https://helpcenter.nshift.com/hc/en-us/articles/17147027547804

 

Example using curl. 

curl -X POST "https://demo.shipmentserver.com" \
 -F "command=SubmitShipment" \
 -F "actor=YOUR_ACTOR_ID" \
 -F "key=YOUR_ACTOR_KEY" \
 -F "data=@data.json" \
 -F "options=@options.json"

Related articles