This ShipHawk TMS ERP Integration Guide is for ShipHawk partners and third-party developers building an integration between an ERP system and ShipHawk TMS.
| Info |
|---|
To learn more about ShipHawk’s features and capabilities, see the ShipHawk Guide. |
...
| Table of Contents | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
ShipHawk TMS Terminology
Term | Definition |
Source | The system you are integrating ShipHawk TMS with (typically an ERP system). |
App | The name of the solution that contains the code that enables integration and interaction between Source and ShipHawk TMS. “Connector” or “Plug-in” may be used interchangeably with App. |
Order | In ShipHawk TMS, an Order is the object in ShipHawk TMS that represents an order that is ready for shipment. |
Shipment | In ShipHawk TMS a Shipment is the object that represents a shipment. |
Proposed Shipment | A Proposed Shipment is an object in ShipHawk TMS that represents the intermediate state between an Order and a Shipment. |
Warehouse | In ShipHawk TMS, the object that represents the location used to fulfill an Order. |
Merchant | The business enterprise using ShipHawk TMS for its fulfillment process, such as an eCommerce company. |
Customer | The Merchant’s customer: a buyer, consumer, or recipient the items being shipped. |
Understanding Orders in ShipHawk TMS
In ShipHawk TMS, Orders in ShipHawk represent any kind of order (sales orders, purchase orders, transfer orders, and so on) that contains represent one or more items/SKUs that are ready to be fulfilled (ready to be shipped).
In some many ERPs, the concept of what’s been purchased is separate 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). In almost all cases, you will want to have ShipHawk 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.
| Note |
|---|
You should have ShipHawk TMS sync with the ERP object that represents what’s ready to be fulfilled to create the |
...
Order object in ShipHawk TMS, to ensure you only fulfill the specific items that are ready (and in inventory) to be shipped. |
...
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 integration steps.
...
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 will need to consider the following:
Installing/uninstalling the App that connects ShipHawk and the ERP/Source
Managing settings like authentication and syncing entities
Managing Order and Line Item field mappings
Creating Orders in ShipHawk
Updating the ERP/Source with shipment details from their ShipHawk
Log all interactions with ShipHawk APIs
...
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:
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, likesuch as:
Production: https://shiphawk.com/api/*
Sandbox: https://sandbox.shiphawk.com/api/*
...
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 (e.g. 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 Webhookwebhook, 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.
Use webhooks if possible. Otherwise Otherwise, scheduled jobs should minimize unnecessary usage and potential API charges. If going this route, the connector should be a good steward of the ShipHawk API, limiting the number of calls per min made to ShipHawk .
...
Alternatively, you can always set up a scheduled job to GET /orders that have not yet been closed in the Source system.
Example: The syncing entity or fulfillment record in the Source will usually need to be updated with the following information at a minimum:
"carrier": "USPS",
"service_name": "Priority Mail",
"total_price": 7.17, // the shipping cost to write back to [ERP/Source]
"tracking_number": "9405510200864427693834",
“shid”: 368765 // the related Shiphawk Shipment ID
When fetching shipment data, you can use GET /orders/:id to accomplish this. Shipment details are provided in the “shipments” node in the order response object.
...
TMS.
For more information on setting up webhooks, see Setting New Webhook in ShipHawk .