Page Comparison

This ShipHawk TMS ERP Integration Guide is for ShipHawk partners and third-party developers building an integration between an ERP system and ShipHawk TMS.

The page introduces key concepts and information for building an integration:

ShipHawk TMS Terminology

Understanding Orders in ShipHawk TMS

In ShipHawk TMS, Orders represent one or more items/SKUs that are ready to be fulfilled (ready to be shipped).

In many ERPs, the concept of what’s been purchased is distinct from the concept of what’s ready to be fulfilled.  For example, NetSuite has Sales Orders (what’s been purchased), and then Item Fulfillments (what’s ready to be fulfilled).  While the Sales Order contains all of the items purchased, the Item Fulfillment contains only the particular items that are ready to be fulfilled at a particular time.  Similarly, the Acumatica ERP has Sales Orders (what’s been purchased), and then Shipments (what’s ready to be fulfilled). ERPs typically use the term “sales orders” for what has been purchased by a customer, but different ERPs can have varying terms for what’s ready to be fulfilled for a given sales order.

Integration Planning

The following is a high-level summary of topics you should consider when planning an ERP integration with ShipHawk TMS.

Create Your Integration Plan

For developers, a high-level checklist of all working parts required for an ERP integration with ShipHawk TMS includes the following:

• Sync’ing of the ERP objects for shipment (e.g., item fulfillment or shipment objects) to ShipHawk TMS Orders using an API request.

• Sync’ing of ShipHawk TMS shipments to the ERP shipment objects (e.g., item fulfillment or shipment objects) using webhooks or by pulling data from the ShipHawk TMS API.

• Rating of sales orders.

• Providing an integration configuration screen on the ERP user interface, including the API configuration settings, ERP to ShipHawk TMS field mappings, logging, and other settings as needed.

As you think about building your integration, you should consider how you want to install (and uninstall) the app that connects the ERP and ShipHawk TMS. You’ll need to consider how you will manage the connection settings, including authentication and synchronization configuration between the ERP and ShipHawk TMS. In addition, you should consider the mapping of the ERP’s order/shipment and line item fields to ShipHawk TMS so that the ShipHawk TMS orders can be created seamlessly. Likewise, you’ll need to consider how the integration will update the ERP with the shipment details from ShipHawk TMS. Finally, it’s important to plan how you will log all the integration’s interactions between the ERP and ShipHawk TMS.

To plan in more detail, see the following pages that define the integration requirements:

• Configuration and Administration Requirements

• Sending Information to ShipHawk Requirements

• Receiving Information from ShipHawk Requirements

Get Your ShipHawk TMS API Key

• Obtain your developer API Key in ShipHawk TMS.  In your ShipHawk TMS account, set this up through Settings > Settings > Developer API > Create API Key.  If you do not yet have a ShipHawk TMS license, schedule a call with a member of our team to learn more.

• Setup at least one Carrier Account in ShipHawk TMS. FedEx or UPS is recommended. In your ShipHawk TMS account, set this up through Settings > Carriers > Select Carrier. You will need this for testing later.

Review Settings and Field Mapping Requirements

Your application will need to store the ShipHawk TMS API Key and should consider supporting multiple environments, future API versions and enhancements, such as:

• Production: https://shiphawk.com/api/*

• Sandbox: https://sandbox.shiphawk.com/api/*

...

We recommend masking the API key for security purposes and allowing the user to specify the API URL so that future API changes or testing may be easily accomplished.  

You will also notice that the settings can allow for a syncing entity decision.  Be sure to sync with the shipment entity (Example: in Acumatica, the Shipment entity, in NetSuite, the Item Fulfillment entity).

Order and Order Line Item Mapping are critical when dealing with Source systems as many ERPs and order source systems provide a lot of flexibility for Merchants they support.  You will want to create Order and Order Line Item level mapping so that fields in your Source system can be assigned to standard fields or order- / line-level reference fields in ShipHawk TMS. 

Example: Here is an example of some basic field mapping in an Acumatica ERP integration with ShipHawk:

...

In addition to field mappings, you will want to code source_system as the “[ERP/Source Name]” and source_system_domain as a unique identifier for each [ERP/Source] account. This makes it easy to know which system is being interacted with and can display this information inside ShipHawk.

Plan Process for Syncing ERP to ShipHawk TMS

Create a process for sending the syncing entity object information as Orders to ShipHawk.  This is usually done by a scheduled job (for instance, every 5-15 minutes) for all transactions that have a certain status or value prior to being available to sync to and have not already been sent to ShipHawk TMS. 

Plan How To Update ERP with Shipment Data from ShipHawk TMS

The recommended method for writing shipment data back to the Source is to setup and subscribe to ShipHawk TMS Webhooks.  Instead of creating scheduled jobs, you can improve performance by setting up a webhook, subscribing to the shipment.create_from_order event and specifying a callback URL of your choice.    

For ShipHawk to ERP sync, we have two options:

• Use webhooks (recommended)

• Create a new endpoint for pulling status updates from ShipHawk TMS in batches. Existing endpoints can not be used for that because of inefficiency and potential issues with reaching ShipHawk TMS API Limits.

For more information on setting up webhooks, see Setting New Webhook in ShipHawk .