Shipping Labels API
You can use the ShipWorks API to post data to and get data from the ShipWorks application by utilizing the Shipping Labels API.
Leverage the Shipping Labels API to:
-
Get limited order information from ShipWorks.
-
Post a request to ShipWorks to create and process a shipment. A response is then generated containing the shipment information and label image.
-
Automate StreamTech solutions - Post a request to process a shipping label, then return the shipment details and label image to be printed by a StreamTech device.
This article assumes the following:
-
You are running the latest version of the ShipWorks software. 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.
-
Launch ShipWorks and log in. ShipWorks must be running in order to reach the ShipWorks REST API V1 page.
-
Open your web browser and go to http://localhost:8081/swagger or the URL displayed on the API tab in the ShipWorks Settings menu.
Healthcheck
GET: /shipworks/api/v{version}/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.
TRY IT OUT
-
Click GET in the Healthcheck section to expand its drop-down.
-
Under Parameters, enter 1 as the version number.
-
Click the Try It Now! button.
A Healthcheck is performed and the results are displayed. The Response will give you the "status" and "instanceId" of the ShipWorks Labels API being used.
Orders
GET: /shipworks/api/v{version}/orders/{orderNumber} - Returns limited data of an order matching the number or order ID.
POST: /shipworks/api/v{version}/orders/{orderNumber}/shipments - Creates and processes a shipment in ShipWorks for a given order. Then, ShipWorks returns the shipment details and label image in its response.
Shipment POST Requests
Shipments created for the requested order are created by applying the Shipping Rules and Shipping Profiles configured in the ShipWorks software. In order for a shipment to be processed successfully, all required parameters (such as weight and dimensions) for the carrier must be met.
TRY IT OUT
Follow these instructions to test either GET orderNumber or POST shipments.
-
Click GET or POST in the Orders section.
-
Enter the order number of the ShipWorks order number into the orderNumber field.
-
Under Parameters, enter 1 into the Version field.
-
Click the Try It Now! button.
GET orderNumber
POST shipment
StreamTech
POST /shipworks/api/v{version}/partner/streamtech/{barcode} - Use with StreamTech dimensioners and devices to:
-
Pass the weight and dimensions for a specified order to ShipWorks
-
Request ShipWorks to create and process a shipment for the specified order
-
ShipWorks returns the shipment details and shipping label image
TRY IT OUT
-
Click POST in the StreamTech section.
-
Enter the ShipWorks order number into the barcode field.
-
Click the code in the Example Value field to auto-populate the streamTechRequest field with the example code.
-
Update the streamTechRequest with valid weight and dimension values.
-
Under Parameters, enter 1 as the version number.
-
Click the TRY IT NOW! button.
The Response Body will include some shipment data as well as Base64-encoded label data for printing.
Note
If the shipment encounters an error when processing, the response will have an "error_code" value of 99. You can use an online Base64 decoder to decode the data found in the "print_label" element to view the issue ShipWorks encountered during processing.
Access the Shipping API setting in the ShipWorks software to start and stop the API, change the port number and/or specify that you wish to connect using HTTPS.
-
Click on the Manage tab and then on the Settings button.
-
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 and Start or Stop the API.
-
See the URL used for connecting to the ShipWorks API.
-
Access the ShipWorks API documentation through the ShipWorks API Documentation hyperlink.
-
Specify to use HTTPS:
Note
Windows 7 does not support the use of HTTPS:
-
Update the Port: number that the ShipWorks API uses.
-
If you encounter errors when accessing ShipWorks data using the Shipments 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 Shipments 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 Shipments API, the labels are created using the shipping rules and profiles configured in the ShipWorks software.
Still Need Help?
Please feel free to reach out to one of our awesome Technical Support Representatives in St. Louis. We are happy to help.
Have a comment to share about this article? We'd love to hear from you. You must be logged in to your Support Portal account to leave a comment.
Comments
0 comments