Getting started with Shipment Server integration – nShift

To get started with Shipment Server, you need a Shipment Server subscription and an account. You may use our Developer Tools to do testing and get familiar with how to build the requests. This article will cover the basic information to get you started with the integration:

Accessing the Shipment Server API
- Data types
Developer Tools
- Activating the Developer Tools
- Using the Developer Tools
- Example of how to create a SubmitShipment request
Printing labels
Data storage of submitted shipments
Further reading

Accessing the Shipment Server API

The connection to the Shipment Server API is through HTTPS, 443.

Each customer using the Shipment Server needs at least a token and an actor_id.
The token and the actor_id must be passed in the payload/body of all the requests.

The web server is accessed using REST and uses POST for all methods.

The request body takes a multipart/form-data or application/x-www-form-urlencoded object with the following keys:
actor, key, command, data, options

actor - id of the actor
key - the access token for the actor
command - the method to run on the API
options - some commands can be controlled with additional settings
data - the payload for the command ( example could be a shipment object )

Data types:

Numeric - numeric fields with a value of 0 (zero) are not included in the JSON string exported by the web service, a value of 0 (zero) being the default.
String - Empty strings are not included in the JSON string exported by the web service.
DateTime - Dates and Timestamps are formatted using the ISO 8601 standard. An example of a date is 2019-06-27 and for a timestamp: 2019-06-27T10:25:00.
Important: Please note that we only support the extended notations and not the basic notations without hyphens, so e.g. 20190627 will not be accepted. Timezones will be removed from the request and milliseconds are ignored.
Enum - Some fields are sent as enums, meaning that they are sent as an integer value, but the value has a certain meaning. See the appendix with Objects and Fields for a complete list of the possible values for these fields.

Developer Tools

The Developer Tools enable you to test and build requests to the Shipment Server API. The Developer Tools are integrated into the user interface of New Bookings in Portal and show both the JSON request to the server and the JSON response from the server which can be used to inspect how the request is built.

Activating the Developer Tools

Log into nShift Portal.
Go to Ship > Configuration >Settings in the top menu.
Scroll down and check Show developer tools under the Production headline.
You will now have access to the Developer Tools at the bottom of all relevant pages under New Bookings.

Using the Developer Tools

The Developer Tools section has two drop-down menus where you can set the label type and the command. Notice that there are different commands available depending on which page you are on. If shipment data is needed in the request, the Developer Tools will use the data you have filled in on the current page. This way you can easily fill in relevant information and see what the request will look like.

The Data field shows the request. Some commands support additional options, which are added in the Options field.

Please see our list of methods here to see which options are available for each command. The Response field shows the response you receive after sending your request.

Example of how to create a SubmitShipment request

The SubmitShipment command creates a shipment and generates a response with a label.

Go to Ship > New and fill out all the fields related to the shipment, i.e. address fields, carrier, and goods information.
In the Developer Tools section, choose the SubmitShipment command. This will show the request in the Data field, using the shipment data that you have filled in. You can fill in data in reference fields, messages, etc., and immediately see how they are added to the request.
Click the Send button. If the request is successful, you will get a response back containing the label. If something is missing in the request, you will get an error message back in the response.
Click the View labels button to see the label(s) of a successful SubmitShipment request.
Use the Reformat data if you have edited it or copy-pasted a request into the data field and want the data in a reading-friendly format.

Tip: If you are building requests for Shipment Server, you can copy-paste your requests into the Data field and test them. If your request already contains all the necessary information, you don't have to fill in the fields on the page. The user interface just provides an easy way to find out how data is added to a request.

See all Commands and Options here.

Printing labels

Shipment Server does not handle the printing of labels of any kind on the client side. You have to implement a solution to fit your environment.

If you are printing from a web browser, using ActiveX control and/or JavaScript could be a solution.

To print from a Windows application you can use the Zebra label printers' own language EPL or ZPL. In this case, you need a Zebra printer or a printer that supports it. When storing the label type EPL / ZPL in a file or using it from a stream, you can send it to the printer by using "move" or "copy" file to a shared printer. Printing PNG and PDF in Windows can be done through a print dialog or automated with a process using Win32API or using unmanaged code with winspool.drv and Marshalling.

You also have the option to use nShift's Drop Zone application and Cloud Print. Cloud Print is a cloud-based solution that lets you print in multiple ways. Documents are stored in a queue in the cloud and Drop Zone installations are downloading the documents that belong to them. Read more about Cloud Print here.

If you are using thermal printers and are experiencing problems with printing, you may be able to find help on our Printers help pages. Issues with label print are often related to printer settings, calibration, missing fonts, etc.

Data storage of submitted shipments

Submitted shipments are kept in the database for 90 days. Shipments older than 90 days are deleted each night to keep the database as compact as possible and ensure high performance. However, your shipments will be available in nShift Portal for as long as you want. nShift Portal is where you can view shipment data and statistics and make reports.

Contact nShift to get a Portal user account.

Read more about Data storage in Portal here.

Ship Help