Accessing the ShipWorks REST API

Background

You now have more ways than ever to leverage the power of the ShipWorks software.  By utilizing the ShipWorks REST API, you can now programmatically interact with the ShipWorks application.  The API can be used for getting data into and out of ShipWorks via third party applications and services.  

First Things First

This article assumes the following:

• You are running ShipWorks version 7.8 or later.  If you are unsure of what version you are running or if you need to update to the latest version, please see this article.
• You are familiar with third party application development.
• You are familiar with the Swagger software framework.

The Process

What can be leveraged using the ShipWorks REST API?

Healthcheck

GET {healthcheck} -Returns a simple status indicating the health of the API and the ShipWorks instance ID. The instance ID is a GUID that represents that instance of ShipWorks. If there are multiple instances of ShipWorks installed, the instance ID can be used to determine which instance of ShipWorks is serving up this API.

Orders

GET {orderNumber} - Returns an order matching the number or order ID.

POST {orderNumber}/shipments - Create a shipment for a given order. 

StreamTech

POST {barcode} - Return an order matching the number or order ID.

Accessing the Swagger Documentation

The Swagger documentation can be accessed locally on any PC running ShipWorks version 7.8 or later by navigating to http://localhost:8081/swagger in your web browser.

Accessing API Setting in ShipWorks

It is possible to access API setting in the ShipWorks software.  From the API screen you can start and stop the API, change the port number and/or specify that you wish to connect using HTTPS.

To access the ShipWorks API settings:

1.  Click on the Manage tab and then on the Settings button.

2.  Select API from the list of options located on the left side of the ShipWorks Settings screen.

From the API screen you can:

• View the status of the ShipWorks API.
  
  
• Start or Stop the API.
  
  
  
  
• See the URL.
  
  
  
• Access the ShipWorks API documentation.
  
  
  
• Specify to use HTTPS:
  
  
  
  Note!
  
  Windows 7 does not support the use of HTTPS:

• Update the Port: that the ShipWorks API uses.
  

 Things to Know

• If errors are encountered when accessing ShipWorks data using the REST API, there is a good chance that the ShipWorks background service is not running.  Launch the ShipWorks software and look for a banner near the top of the application notifying you that the service is stopped.  If after starting the ShipWorks software and/or starting the service the errors persist, please reach out to ShipWorks Support.
• When generating shipments using the REST API the labels will not print unless the ShipWorks application is running.  Any labels generated while the application is not running will be queued and will print once the ShipWorks software is launched.
• When generating shipments using the REST API, the labels are created using the shipping rules and profiles configured in the ShipWorks software.