Tai Software - Broker TMS Customer REST API Web Service Interface
Service Overview
These are the primary functions available for use in the REST API for Shipping
| Service Name | Short Description |
| bookDomesticShipment | This service will book the order based on the information provided. It is not necessary to provide a quote or carrier name before booking an order |
| getShipmentDetails/{shipmentId} | This service will provide all details associated with the specified shipment. |
| alerts/add | This service is to add specific alerts to an existing shipment |
| updateShipmentReferenceNumbers | This service is to update or add reference numbers to an existing shipment |
| alerts/resolve | This service is to resolve alerts that were added to a shipment |
| trackingUpdate | This service is to update a shipment's status which allows you to add various information such as add the POD Date Time and other various tracking info. |
| trackingUpdateByReferenceNumber | This service is to update a shipment's status based on the reference number provided. |
TMS Setup
This integration requires that the internal price and customer accounts have been set up in the TMS before usage of the WEB-Services.
Base Service URL
The base service can be tested using our test servers. Sample requests and responses can be provided upon request.
Test Service URL:
TEST URL - https://www.taibeta.net/PublicAPI/swagger/index#!/Shipping/
Production Service URL:
http://[your TMS Url]/PublicAPI/swagger/index#!/Shipping/
Important: Make sure to include your TMS URL when implementing your client to production. Using the generic taicloud URL in our documentation will work, but may cause timeout issues. To find your TMS URL, go to LSP > Onboarding Guide. You'll find the Site code within the Site Organization Information section.
Example: 
In this example, the service URL should be the following:
http://JAM.taicloud.net/PublicAPI/swagger/index#!/Shipping/
Security
Most methods require an Authentication Key to be sent. Please refer to our Public API Key to generate a key. The Authentication Key will be included in the header "x-api-key: [Insert API Key here]".
Each Authentication Key is assigned to a specific customer or Broker, which will require a customerReferenceNumber to associate it to the correct Customer. If you need to request quotes or book orders for different accounts you will need to use different authentication keys. Please contact Support for further information.
Implementation
This implementation information is intended to provide a high-level guide to implementing this service. There are sample JSON requests that can be used to verify and test whether the service is working correctly
To work with this service, you will need to create a client and use it to call the service.
bookDomesticShipment - Additional Information on certain fields
- customerReferenceNumber this is optional to include depending on your API Key. If you are using a Broker API Key then the customerReferenceNumber is required if the customerID is also not specified. Otherwise it's not required.
- tariffDescription this is option to include. If included this is stating you want the rate to be based on the Tariff Name included. (Ex: tariffDescription: "BL - Tai Test Org - SAIA" )
- isBooked this is an optional boolean. If set to True this will default to the Customer Default Shipment Status. If none is specified this will by be set to Ready by default. If set to False it will be left in Quoted Status
- rateShipment this is an optional boolean. If set to True this will attempt to rate the shipment based on the Tariff Description or carrierSCAC. If none are included, it will provide the least cost rate for any Carrier. If set to false no Rate will be added to the shipment.
- carrierSCAC this is optional. When included this will specify the Carrier you want on the shipment. If a rateShipment is set to true, we will attempt to locate a rate based on the carrierSCAC. If no rate is available, the carrier will be added to the shipment with no price.
- customerId this is optional to include depending on your API Key. If you are using a Broker API Key then the customerID is required if the customerReferenceNumber is also not specified. Otherwise it's not required.
Error Handling
The service is built to return Bad Request http messages if there are any validation issues with the incoming request. If an error is not returned, then the HTTP Ok response will contain the return object relative to the request.
Workflow
Initially, it is best to test the initial calls on our Test Service URL. This is to ensure proper communication with the service.
bookDomesticShipment would be used to create a shipment. This will provide the lowest cost rate that is provided to the Customer associated with the shipment based on the information provided (Zip Codes and Commodities). If no rates are available, this will still generate a shipment which will be made available.
getShipmentDetails would be used to get details regarding the shipment. This can be triggered at anytime to see the most updated status or information regarding the shipment.
alerts/add would be used to include any specific alerts that need to be added to the shipment. This could be Shipment Delays, or simply missed pickup notifications.
updateShipmentReferenceNumbers would be used to include any specific reference numbers that may need to be included on the shipment. This can include pickup numbers, load release numbers etc.
alerts/resolve would be used to resolve any alert that may have been added to the shipment. To check what alerts may be on a shipment, we recommend the getShipmentDetails call. This would be helpful in resolving Pickup Date Passed alerts, if the shipment is currently moving.
trackingUpdate would be used to provide any updates you may have received outside of the TMS. This may be unnecessary if you are using any Tracking Integrations where the Tracking would be handled by the system.
trackingUpdateByReferenceNumber would be used to provide any updates based on a Reference Number such as the Customer PO Number or any other reference number available.
Accounting Software API Workflow - Miro diagram for best practices and workflows
Note: for more updates to proactively fill in certain gaps within the workflow, we recommend using our Public Webhooks
API Call Limitations:
- Rating - 45 / min
- Accounting - 200 / min
- General - 150 / min