Menu

Shipping Labels API

Avatar

ShipWorks Content Team

Updated

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.

First Things First

This article assumes the following:

The Process

Access the Swagger Documentation

  1. Launch ShipWorks and log in. ShipWorks must be running in order to reach the ShipWorks REST API V1 page.

  2. Open your web browser and go to http://localhost:8081/swagger or the URL displayed on the API tab in the ShipWorks Settings menu.

Swagger is open and the Rest API is shown in a browser window.

What can I do with the Shipping API?

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

  1. Click GET in the Healthcheck section to expand its drop-down.

  2. Under Parameters, enter 1 as the version number.

  3. 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.

The health check window is displayed with the Get button highlights. The parameters section shows parameters entered and the try it now button is selected.
The response is shown and indicating the status as OK.

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.

  1. Click GET or POST in the Orders section.

  2. Enter the order number of the ShipWorks order number into the orderNumber field.

  3. Under Parameters, enter 1 into the Version field.

  4. Click the Try It Now! button.

GET orderNumber

Click ​GET​ or ​POST​ in the ​Orders​​ section.​ ​Enter the order number of the ShipWorks order number into the ​orderNumber​​ field. Enter ​1​ into the ​Version​​ field. Click the ​Try It Now!​​ button.
The response body is shown with order information.

POST shipment

The post shipments window is open with post parameters entered and the try it out button selected.
The response body is displayed with labels information

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

  1. Click POST in the StreamTech section.

  2. Enter the ShipWorks order number into the barcode field.

    Streamtech is open and the Post button and barcode field are highlighted.

  3. Click the code in the Example Value field to auto-populate the streamTechRequest field with the example code.

  4. Update the streamTechRequest with valid weight and dimension values.

    Streamtech information with properly formatted weight and dimensions.

  5. Under Parameters, enter 1 as the version number.

  6. Click the TRY IT NOW! button.

    Enter version 1 and click try it out

The Response Body will include some shipment data as well as Base64-encoded label data for printing.

Response body is displayed with results.

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 API Setting in ShipWorks

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.

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

    click manage tab then settings button. manage > settings

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

    Select API from the ShipWorks Settings options

From the API screen you can:

  • View the status of the ShipWorks API and Start or Stop the API.

    Click Start
    Click Stop

  • See the URL used for connecting to the ShipWorks API.

    Status is running and the URL is shown.

  • Access the ShipWorks API documentation through the ShipWorks API Documentation hyperlink.

    The ShipWorks API Documentation link is highlighted.

  • Specify to use HTTPS:

    The HTTPS option is selected.

    Note

    Windows 7 does not support the use of HTTPS:

  • Update the Port: number that the ShipWorks API uses.

    A port number is entered and the save button is being clicked.

Things to Know

  • 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.

    Attachments

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