Menu

Shipping Labels API

Avatar

ShipWorks Content Team

Updated

Background

Post data to and get data from the ShipWorks application by utilizing the Shipping API.

Leverage the Shipping API to:

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

Accessing the Swagger Documentation

The Swagger documentation can be accessed locally on PCs running ShipWorks by navigating to http://localhost:8081/swagger in your web browser.

mceclip0.png

What can be leveraged using 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.

  2. Enter 1 as the version number.

  3. Click the Try It Now! button.

A healthcheck is performed and the results are displayed.

SW_STEPS_ShipAPI_Healthcheck_MRK.png
SW_STEPS_ShipAPI_HealthcheckResponse_MRK.png

Orders

GET: /shipworks/api/v{version}/orders/{orderNumber} - Returns 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.

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 for testing 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. Enter 1 into the Version field.

  4. Click the Try It Now! button.

GET orderNumber

SW_STEPS_ShipAPI_GetOrder_MRK.png
SW_STEPS_ShipAPI_GetOrderResponse_MRK.png

POST shipment

SW_STEPS_ShipAPI_POSTShipment_MRK.png
SW_STEPS_ShipAPI_POSTShipmentResponse_MRK.png

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.

    SW_STEPS_ShipAPI_StreamTech1_MRK.png

  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.

    SW_STEPS_ShipAPI_StreamTech2_MRK.png

  5. Enter 1 into the Version field.

  6. Click the TRY IT NOW! button.

    SW_STEPS_ShipAPI_StreamTech3_MRK.png
SW_STEPS_ShipAPI_StreamTechResponse_MRK.png

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

mceclip2.png

From the API screen:

  • View the status of the ShipWorks API.

  • Start or Stop the API.

    mceclip3.png
    mceclip4.png

  • See the URL.

    mceclip5.png

  • Access the ShipWorks API documentation.

    mceclip6.png

  • Specify to use HTTPS:

    mceclip7.png

    Note

    Windows 7 does not support the use of HTTPS:

  • Update the Port: that the ShipWorks API uses.

    mceclip8.png

Things to Know

  • If errors are encountered 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 toShipWorks 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