Version: 0.0.0
SFTP Export: In-house TMS Integration
This page contains information on how to integrate your In-house TMS with Chaine using a SFTP File export of loads.
For this integration, Chaine will provide you with an SFTP server credentials, server information and a folder path where you can upload your load files. The load files should be in CSV format and should contain all the fields that are required to create a load in Chaine (see below).
When to send a load in a CSV file
There are two strategies that can be utilized when sending loads in a CSV file:
- Send the entire load object with all the fields every time there is a change to the load: We recommend that you send the entire load object with all the fields below.
- Send all open loads and loads recently marked delivered every X minutes: If it is difficult to send a load whenever there is a change, you can send all the "active" loads (loads that have not delivered), and loads that have been marked delivered in the last 24 hours. This will ensure that all loads are up to date in Chaine. Chaine automatically handles the logic to update the load status based on the information in the CSV file. If a load hasn't changed, Chaine will not update the load.
| Note: If you find it hard to map to the exact field names, don't stress that too much. We can always do a custom field mapping for your file exports. You can just do a dump of all the files every X minutes, or if you have the ability to export a file whenever there is a change, that will work too. If needed, we'll map the fields to reduce the work from your end. If there is anything else we can do to make it easier on your end, just let us know and we'll handle it!
Load Object
Below is the load object and fields to send in a CSV fields. Not all fields are required, but the more fields you send, the more features you can utilize in Chaine.
If a load has multiple stop, you can send the other stops in the same CSV file as per the stopN example below. For us to process the other stops, it is required to send the totalStops. The best practice is to do the following:
- Origin and Destination are required always required. Origin will be sequence 1 and Destination will be stop sequence as "totalStops"
- If there are other stops, you can send them as stopN where N is the sequence number of the stop. For example, if there are 3 stops, you will have send the origin properties, destination properties, and stop2 properties.
- We will only process the other stops if you provide the totalStops field.
- When sending appointments, you can send either the fields suffixed with "Appointment" in the format "YYYY-MM-DDTHH:MM:SSZ" or the fields suffixed with "AppointmentDate" and "AppointmentTime" in the format "YYYY-MM-DD" and "HH:MM:SS" respectively.
- If the stop is an appointment, only send the "Appointment" (or "AppointmentDate" & "AppointmentTime") fields (i.e. originAppointment, destinationAppointment, stopNAppointment OR originAppointmentDate, originAppointmentTime, destinationAppointmentDate, destinationAppointmentTime, stopNAppointmentDate, stopNAppointmentTime).
- If the stop is FCFS, send the "LatestAppointment" fields along with the "Appointment" fields
For boolean values, you can send the following for true/false irrespective of the case:
- true: 1, t, true, yes, y
- false: 0, f, false, no, n
| Field | Description | Example Value | Required | For Chaine Product |
|---|---|---|---|---|
| shipmentID | Unique identifier for the shipment used in your TMS | 123456 | No | All |
| shipmentNumber | Shipment number | 123456 | Yes | All |
| shipmentStatus | Current status of the shipment | Carrier assigned | Yes | All |
| carrierCostTotal | Total cost for the carrier | 1000 | No | All |
| customerChargeTotal | Total charge for the customer | 1200 | No | Booking |
| carrierID | Unique identifier for the carrier | 1234 | No | All |
| carrierDOTNumber | Department of Transportation number for the carrier | 123456 | Yes | Tracking |
| carrierMCNumber | Motor Carrier number for the carrier | 123456 | Yes | Tracking |
| carrierSalesRepID | Sales representative ID for the carrier in your TMS. This is used when a carrier sales rep accepts a carrier offer, and we need to send the carrier sales rep's id back to your TMS for assignment. | 1234 | No | All |
| carrierSalesRepEmail | Email of the carrier's sales representative | carrierrep@123logistics.com | Yes (when available) | All |
| customerSalesRepEmail | Email of the customer's sales representative | customerrep@123logistics.com | Yes (when available) | All |
| customerSalesRepID | Sales representative ID for the customer | 1234 | No | All |
| commodity | Type of commodity being shipped | Commodity | Yes | Booking |
| customerID | Unique identifier for the customer | 123456 | No | All |
| customerName | Name of the customer | Customer Name | No | All |
| distance | Distance of the shipment | 100 | Yes | Booking |
| doNotPost | Flag indicating whether the load should be posted | false | Yes | Booking |
| dispatcherEmail | Email of the dispatcher (the carrier's dispatcher, not internal) | dispatch@yourcarrier.com | Yes | Tracking / Copilot |
| driverPhone | Phone number of the driver | 234567890 | Yes | Tracking / Copilot |
| equipmentLength | Length of the equipment in feet | 53 | Yes | Booking |
| equipmentType | Type of equipment | Van | Yes | Booking |
| isHazmat | Flag indicating if the load is hazardous material | false | Yes | Booking |
| isHotLoad | Flag indicating if the load is urgent | false | No | Booking |
| isOversized | Flag indicating if the load is oversized | false | No | Booking |
| isPartial | Flag indicating if the load is a partial load | false | No | Booking |
| isTempControlled | Flag indicating if the load is temperature controlled | false | No | Booking |
| loadPostDescription | Description of the load posting | This load requires tarps and must pickup no later than 8am | No | Booking |
| teamRequired | Flag indicating if a team is required | false | No | Booking |
| maxTemperature | Maximum temperature for the shipment | 20 | No | Booking |
| minTemperature | Minimum temperature for the shipment | 20 | No | Booking |
| mode | Mode of transportation | Truckload | No | All |
| proofOfDeliveryReceived | Flag indicating if proof of delivery has been received | false | No | Copilot |
| specialInstructions | Special instructions for the shipment | When you arrive at the destination, please call the customer at 123-456-7890 | No | Tracking |
| teamWorkspaceID | Unique identifier for that can be used for offices/teams/groups if you need to split the loads up into different chaine workspaces under your "enterprise" | 1234 | No | All |
| teamWorkspaceName | Name of the sub workspace. If you provide subWorkspaceID, this must be provided or else it will default to subWorkspaceID | Sub Workspace Name | No | All |
| maxCarrierRate | Maximum rate for the carrier | 1100 | No | Booking |
| targetCarrierRate | Target rate for the carrier | 1000 | No | Booking |
| totalStops | Total number of stops for the shipment | 3 | Yes | All |
| trailerNumber | Number of the trailer | 123456 | No | Tracking |
| truckNumber | Number of the truck | 123456 | No | Tracking |
| weight | Weight of the shipment in pounds | 40000 | Yes | Booking |
| originAddressLabel | Label for the origin address. Either this or the other Address fields is required. | 123 Main St, New York, NY 10001 | Yes | All |
| originAddressCity | City of the origin address | New York | Yes | All |
| originAddressPostalCode | Postal code of the origin address | 10001 | Yes | All |
| originAddressStateCode | State code of the origin address | NY | Yes | All |
| originAddressState | State of the origin address. Send the State or StateCode | New York | Yes | All |
| originAddressStreet | Street of the origin address | 123 Main St | Yes | All |
| originAddressLatitude | Latitude of the origin address (in decimal degress format) | 40.7128 | Yes | No |
| originAddressLongitude | Longitude of the origin address (in decimal degress format) | -74.0060 | Yes | No |
| originAppointment | Appointment time for the origin address. Either this or the other appointment fields are required when available. | 2022-01-01T00:00:00Z | Yes (if available) | All |
| originAppointmentDate | Appointment date for the origin address | 2022-01-01 | Yes (if available) | All |
| originAppointmentTime | Appointment time for the origin address | 00:00:00 | Yes (if available) | All |
| originLatestAppointment | Latest appointment time for the origin address (if the appointment is FCFS) | 2022-01-01T00:00:00Z | No | All |
| originLatestAppointmentDate | Latest appointment date for the origin address (if the appointment is FCFS) | 2022-01-01 | No | All |
| originLatestAppointmentTime | Latest appointment time for the origin address (if the appointment is FCFS) | 00:00:00 | No | All |
| originTimezone | Timezone of the latest appointment time for the origin address (if the appointment is FCFS) | America/New_York | No | All |
| originStopSequence | The sequence number for the origin stop | 1 | No | All |
| destinationAddressLabel | Label for the destination address. Either this or the other Address fields is required. | 123 Main St, New York, NY 10001 | Yes | All |
| destinationAddressCity | City of the destination address | New York | Yes | All |
| destinationAddressPostalCode | Postal code of the destination address | 10001 | Yes | All |
| destinationAddressState | State of the destination address. Send the State or StateCode | New York | Yes | All |
| destinationAddressStateCode | State code of the destination address | NY | Yes | All |
| destinationAddressStreet | Street of the destination address | 123 Main St | Yes | All |
| destinationAddressLatitude | Latitude of the destination address (in decimal degress format) | 40.7128 | Yes | All |
| destinationAddressLongitude | Longitude of the destination address (in decimal degress format) | -74.0060 | Yes | All |
| destinationAppointment | Appointment time for the destination address Either this or the other appointment fields are required when available. | 2022-01-01T00:00:00Z | Yes (if available) | All |
| destinationAppointmentDate | Appointment date for the destination address | 2022-01-01 | Yes (if available) | All |
| destinationAppointmentTime | Appointment time for the destination address | 00:00:00 | Yes (if available) | All |
| destinationLatestAppointment | Latest appointment time for the destination address (if the appointment is FCFS) | 2022-01-01T00:00:00Z | No | All |
| destinationLatestAppointmentDate | Latest appointment date for the destination address (if the appointment is FCFS) | 2022-01-01 | No | All |
| destinationLatestAppointmentTime | Latest appointment time for the destination address (if the appointment is FCFS) | 00:00:00 | No | All |
| destinationTimezone | Timezone of the latest appointment time for the destination address (if the appointment is FCFS) | America/New_York | No | All |
| destinationStopSequence | The sequence number for the destination stop | 3 | No | All |
| stopNSequence | The sequence number for the Nth stop | 2 | No | All |
| stopNAddressLabel | Label for the Nth stop address | 123 Main St, New York, NY 10001 | No | All |
| stopNAddressCity | City of the Nth stop address | New York | No | All |
| stopNAddressPostalCode | Postal code of the Nth stop address | 10001 | No | All |
| stopNAddressState | State of the Nth stop address. Send the State or StateCode | New York | No | All |
| stopNAddressStateCode | State code of the Nth stop address | NY | No | All |
| stopNAddressStreet | Street of the Nth stop address | 123 Main St | No | All |
| stopNAddressLatitude | Latitude of the Nth stop address (in decimal degress format) | 40.7128 | No | All |
| stopNAddressLongitude | Longitude of the Nth stop address (in decimal degress format) | -74.0060 | No | All |
| stopNAppointment | Appointment time for the Nth stop address | 2022-01-01T00:00:00Z | No | All |
| stopNAppointmentDate | Appointment date for the Nth stop address | 2022-01-01 | No | All |
| stopNAppointmentTime | Appointment time for the Nth stop address | 00:00:00 | No | All |
| stopNLatestAppointment | Latest appointment time for the Nth stop address (if the appointment is FCFS) | 2022-01-01T00:00:00Z | No | All |
| stopNLatestAppointmentDate | Latest appointment date for the Nth stop address (if the appointment is FCFS) | 2022-01-01 | No | All |
| stopNLatestAppointmentTime | Latest appointment time for the Nth stop address (if the appointment is FCFS) | 00:00:00 | No | All |
| stopNType | Type of the Nth stop (e.g., "Pick", "Drop", or "Both") | Pick | No | All |
| stopNTimezone | Timezone of the latest appointment time for the Nth stop address (if the appointment is FCFS) | America/New_York | No | All |
We make integrating with Your TMS's simple. Most TMS's have an export functionality where the entire load object can be exported as-is any time there is a change to the load. This is the preferred method of integration.
We recommend that you send the entire load object with all the fields to this end-point. Our workflow automation features can be created on any field in your TMS, and which will give your users an unlimited amount of possibilities when creating workflow rules. Chaine will map your entire load object with all the fields to our internal load object and update the load accordingly in our system. This functionality allows customers to utilize the complete suite of features.
The flow is:
- A load is created, updated or deleted in your TMS
- The entire load object with all the fields is exported to Chaine via a webhook you provide. For deleted, you can simply send the unique load ID and action type of delete.
- Events are then published back to a webhook you specify (depending on the functionality that is determined to be updated back in the TMS for the integration).