Overview


This document mainly describes the System Architecture and Application Programming Interface (API) that Shiptheory uses to communicate with Microsoft Dynamics 365 Business Central. It also provides some sample code you may need to write in AL to recreate the API needed.


How to Integrate


To integrate with Shiptheory, a custom API provided by Microsoft Dynamics 365 Business Central is needed. Extension can be developed in AL, see Development in AL.


The development of Integration and the Integration process are summarized as follows:


Preparation


StepDetail
1

Create a new Application in Azure Portal for the Extension. After you have completed the step, you will have the following:

  • Tenant ID
  • Client ID (Application ID)
  • Client Secret

Please refer to this support page in Shiptheory for help.

2

Ensure the environment name and company identifier are noted for the specific company you would like Shiptheory to integrate with. For example, ‘Production’ and ‘LIVE-COMPANYNAME’.


It is highly recommended you create a Sandbox for testing and development purposes.

3
Read on System Architecture, API Guide, and AL Sample Code in this document


Development


You may do the following in a different environment other than your live environment to test


StepDetail
4
  • Implement the API endpoints in the API Guide
  • Create some testing shipment data in your Business Central
  • Use Postman to test all the APIs created thoroughly
5
  • When your API is ready, add a new Microsoft Dynamics 365 Business Central Channel in Shiptheory. See this connecting guide.
  • Upon successful connection, shipments will be automatically downloaded
  • Have a check to ensure the fields exposed by the API are correctly downloaded into Shiptheory.
6
  • Add your favorite carrier in Shiptheory. In the carrier Advance Setting page, enable Test Mode if it is available
  • Right-click those download shipments, and choose View. In the next dialogue, you can book a shipment with the newly added carrier
  • When a shipment is successfully booked, Shiptheory will update the shiptheoryStatus and shiptheoryPTR of all items in the shipment in Business Central
  • You can also play around with the Shipping Rule to have shipment automatically booked after shipment is downloaded from Business Central


Go Live


When you finish the development, deploy your code into the Production environment in Business Central.


In Shiptheory, locate the Microsoft Dynamics 365 Business Central setting page, and change the environment to your live environment.



System Architecture

Shiptheory supports two types of Warehouse Shipment:


Shipment TypeEndpoints
Warehouse Shipment
  • Shiptheory will search for shipment of “status = Released”
  • End Point: /shiptheoryWhseShipments
Posted Warehouse Shipment
  • Shiptheory will ignore the status 
  • End Point: /shiptheoryPostedWhseShipmentsQuery


Shiptheory will connect to Microsoft Dynamics 365 Business Central and search for new shipments on behalf of our customers periodically. For instance, Warehouse Shipment with status equal to Released and will be downloaded. 


In the example of a Warehouse Shipment


A Warehouse Shipment is considered to be ready for shipment when the status changes from Open to Released. Shiptheory will not download Open Warehouse Shipment and only download Released Warehouse Shipment.




In the example of a Posted Warehouse Shipment


Shiptheory will ignore the Status as all Posted Warehouse Shipments are considered ready to ship.


Shipment Status


Shiptheory will not change remote Shipment Status but it updates shiptheoryStatus for the integration to work. The following table summarizes the different statuses for a shipment.



Example Screenshot of Business Central showing shiptheoryStatus for an item inside a Warehouse Shipment:




Shipment ID and Order ID


By default, Shiptheory will set your Business Central Sales Order number as the Shipment ID and Warehouse Shipment number as the Order ID. This allows Shiptheory to offer the most functionality between Microsoft Dynamics 365 and itself.



If you would prefer your Warehouse Shipment number to be set as the Shipment ID and Sales Order number to be as the Order ID you can set it on its setting page.


If you select to set the Warehouse Shipment number as the Shipment ID, Shiptheory will only be able to download ONE order per Warehouse shipment. Please make sure your warehouse shipments only contain one order each.




API Guide


Business Central has to provide the following API for Shiptheory to download shipments and update shipment status.


  1. OAUTH Access Tokens
  2. Company Information via ODatav4
  3. Warehouse Location via ODatav4
  4. Warehouse Shipment via ODatav4
  5. Shipment Status Update via ODatav4


See the API Guide for more information.