FourKites

We have two integrations available with FourKites. One is used to push tracking location data to FourKites for a specific customer. The other uses the FourKites integration to pull data down from FourKites into the TMS. 

FourKites PULL

This is a RESTful API integration that will work with Tai TMS’s existing Shipment Location History functionality. Four Kites will be listed as an available Shipment Tracker. Tai TMS will be able to Create, Update, and Delete loads within Four Kites application. Callbacks will pull back relevant information for display in the Shipment Location History modal.

API AUTHENTICATION
We will use basic authentication for both POSTS and callbacks.

Supported Methods

CREATE LOAD - POST
This API is called to request the carrier to accepted the tender for the load. This is triggered by the Start Tracking UI.
The response from this post is a FourKites loadid. This loadid must be saved and used for other calls.

We send in our shipmentID and create a stop reference id that we will use for tracking. The stop reference ID is similar to the way we create stop reference numbers for the Tai mobile integration.

UPDATE LOAD
This allows authorized users to update a load. This should be used when the carrier is changed.

DELETE LOAD
Allows authorized users to delete loads already created in FourKites. This should be used when a shipment has been terminated.

CALLBACKS
Tai Software will register a callback URL to which FourKites will send notifications (via HTTPS POST method) related to the loads they have created for tracking.

Callback workflow is triggered after a create load is posted to Fourkites
1. Create load - POST
- gets back loadid (4kites reference number)
2. Load Create Notification
- includes URL to open public tracking page. We should make this available to the users
3. tracking Info Assignment
- driver name / phone / truck number / trailer number is returned
4. New Location Update
5. Stop ETA Update – pickup
- stopreferenceid is our key to identify each stop
- this call should be used to add exceptions for potential late / missed pickups
6. Stop ETA Update - delivery
- ETA update is only sent when the ETA is changed by more than 15 minutes
7. New location Update
- this contains GPS locations
8. Stop Arrival – Pickup location
- Triggered when the driver enters geo-fence
- Use this to trigger actual pickup/delivery date/time
9. Stop departure – Pickup Location
- Triggered when the driver leaves the geo-fence
- We should log this as the actual stop departure time
10. New Location Update
- This will happen multiple times
11. Stop ETA update
- Only called when the ETA is changed
12. Stop Arrival – delivery
13. Stop Departure - delivery
14. Stop File Upload
- images come back - we download the images

Webhooks

https://www.taicloud.net/publicapi/fourkites/notification
- includes URL to open public tracking page

https://www.taicloud.net/publicapi/fourkites/etaupdate
- used to add exceptions for potential late/missed pickups
- sent when ETA is changed by more than 15 mins

https://www.taicloud.net/publicapi/fourkites/arrival
- triggered when the driver enters the geofence

https://www.taicloud.net/publicapi/fourkites/departure
- triggered when the driver leaves the geofence

https://www.taicloud.net/publicapi/fourkites/fileupload
- potential to pull back POD and ReturnReceipt

https://www.taicloud.net/publicapi/fourkites/locationupdate
- location updates w/ geolocation

https://www.taicloud.net/publicapi/fourkites/trackingInfoAssignment
- the following is returned: driver name, phone number, trucker number, and trailer number

FourKites PUSH

The Fourkites integration will transmit location information to the Fourkites platform via API Integration. 

To set this up: 

  1. Obtain credentials from Fourkites. Username/Password are required.
  2. Go to Rates --> Integration Sources
  3. Click Add New Integration Source
  4. Enter a name for the integration
  5. Source Group = Other / Source Type = FourKites
  6. Enter Username/Password and click Save
  7. Click Edit and in the Source Settings section add a new setting
  8. Name = "CustomerId" (without the quotes)
  9. Value = The customer's id which can be viewed in the customer profile

When setting up the integration, Fourkites may provide a clientID and clientSecret that are in encoded format. If so, ask them to provide the username/password. The TMS will encode the credentials when the payload is transmitted. 

The endpoint that we transmit LAT/LONG to is:

https://tracking-api.fourkites.com/api/v1/tracking/locations

After the integration source is saved, any active (In Transit or Delivered) shipments for this customer will transmit data to Fourkites. The shipment data requires a Secondary BOL Number which would be the corresponding ID in Fourkites and also requires LAT/LONG data which is saved in the TMS.

**Note: the LAT/LONG data will only be pull from one of our tracking integration or by the Request driver location feature**