AddTrip API
Clients call this API to add a trip for a given source and destination, vehicle and tracking information.
API Endpoint:
https://integration.freighttiger.com/saas/trip/add - Integration/Sandbox Environment
https://www.freighttiger.com/saas/trip/add - Production Environment
Request Parameters:
Name | Type | Location | Description | Example |
|---|---|---|---|---|
Authorization | string | headers | JWT token required to authenticate API call. | Authorization: Bearer eyJhbGciOiJIUzI1Ni |
Request Body:
Example value:
{
"is_round_trip": false,
"trip_scheduled_at": "2023-10-11 07:48:00",
"lrnumber": "LR123",
"portableTrackerUniqueId":"PRT123",
"loading": {
"uniqueId": "MUM",
"lat": 19.0759837,
"lng": 72.87765590000004,
"address": "Mumbai, Maharashtra, India",
"area": "Mumbai, Maharashtra, India",
"pincode": "400069"
},
"unloading": {
"uniqueId": "MAHMUM",
"lat": 17.9307285,
"lng": 73.64773420000006,
"address": "Mahabaleshwar, Maharashtra 412806, India",
"area": "Mahabaleshwar, Maharashtra, India",
"pincode": "412806"
},
"waypoints": [
{
"uniqueId": "123456",
"address": "Pune Maharashtra",
"area": "Nana Peth",
"lat": 18.5204,
"lng": 73.8567,
"pincode": "411002"
}
],
"vehicleNumber": "MH05AS1212",
"locationSource": "sim",
"driverName": "Raju",
"driverNumbers": [
"1234567890"
],
"feedUniqueId": "F1212121-dd-98375",
"consignee": {
"uniqueId": "CODE1",
"name": "Consignee 1",
"number": [
"1111111111",
"1111111111"
]
},
"share_trip": 1,
"tripType": "inbound",
"customValues": {
"ewayBillNo": "EWB1234",
"invoiceNumber": "INV123"
},
"lr_reference_number": "INV-4453",
"primary_attributes": {
"gate_in": "1679563271000",
"gate_out": "1679563671010",
"shipment_numbers": [
"SHP1",
"SHP2"
],
"container_number": "CN1",
"tare_weight": 100,
"net_weight": 100,
"gross_weight": 100,
"movement_subtype": "M",
"movement_channel": "In",
"billing_type": "To Pay",
"yard_entry_number": "Y12",
"expected_transit_time": 200,
"erp_transit_distance": 80,
"vehicle_type_ref_code": "4Wheeler",
"freight_value": 25.5,
"freight_value_currency": "INR",
"master_trip_grouping_parameter":"MST123",
"unloading_gate_in": "2024-02-02 11:34",
"unloading_gate_out": "2024-02-03 12:34"
},
"invoice": {
"currency": "INR",
"invoice_details": [
{
"from": {
"name": "XYX Pvt Ltd",
"gstin": "SADSDFG132435DV",
"shipping_address": "HSR",
"billing_address": "HSR",
"contact_phone": [
"9123404017",
"98121231234"
],
"contact_email": [
"abc@gmail.com"
]
},
"to": {
"name": "ABC Pvt Ltd",
"gstin": "ASDSFD1234FDS",
"shipping_address": "Agra",
"billing_address": "Agra",
"contact_phone": [
"9123404017",
"98121231234"
],
"contact_email": [
"def@gmail.com"
]
},
"so_number": "343424",
"so_quantity": 12,
"so_date": "1679563271000",
"so_release_date": "1679563271000",
"po_number": "45642",
"do_number": "9675752",
"do_quantity": 12,
"do_date": "1679563371000",
"do_publish_date": "1679563281000",
"invoice_number": "INV2345",
"invoice_date": "1679564271000",
"eway_bill_no": "1516859638",
"eway_bill_expiry_date": "1679563891000",
"description": "Invoice For Cement Bags",
"total_invoice_value": 2222,
"price": {
"net_price": 10000,
"total_price": 12000,
"total_tax": 2000
},
"tax": {
"cgst_rate": 10,
"cgst": 1000,
"sgst": 10,
"sgst_rate": 100,
"igst": 10,
"igst_rate": 100,
"other_tax": 0,
"other_tax_rate": 0
},
"custom_fields": {
"doStoNo": "DO-232",
"gstvalue": "477531.32"
},
"item_details": [
{
"sku_code": "DA-123",
"material_code": "21324",
"hsn_code": "8803",
"quantity": 11,
"quantity_unit": "BAG",
"gross_weight": 22.34,
"net_weight": 21.34,
"weight_unit": "TON",
"product_name": "Concrete Cement Bag",
"description": "Concrete Cement Bag",
"custom_fields": {
"cement_type": "Concrete cement",
"cement_grade": "A Grade"
},
"price": {
"net_price": 10000,
"total_price": 12000,
"total_tax": 2000
},
"tax": {
"cgst_rate": 10,
"cgst": 10,
"sgst": 10,
"sgst_rate": 100,
"igst": 10,
"igst_rate": 100,
"other_tax": 0,
"other_tax_rate": 0
}
}
]
}
]
}
}Schema
loading/unloading objects
These objects expect to carry the information of source and destination place and intend to resolve the required information of the place i.e., lat, lng and address of the place for the Trip. The required information is either passed directly or indirectly with a unique place reference of the company. Hence,
Below is the order in which the FT system tries to resolve the loading/unloading objects.
(lat, long) has the highest preference of all the fields. If these are sent, the system will ignore other fields and directly map the location of the trip using the (lat, long)
If (lat, long) is not sent in the payload, the FT system checks for the uniqueId field
If uniqueId is sent and is onboarded, the system will pick the lat, and long from the database and maps the location of the trip
If uniqueId is sent and is not onboarded
If the address is sent - then the FT system will resolve the address using Google APIs and automatically onboard the location with the provided uniqueId
If the address is not sent - then the system doesn’t have any way to resolve the address, and an error will be thrown
If only the address is sent, without uniqueId and (lat, long), the FT system will resolve the address using Google APIs and maps the location of the trip, but will not onboard the location.
Any other unsupported fields like city etc., sent in the payload will be ignored. Please check the schema below for supported fields
Primary Attributes Object
Primary Attributes are considered important values that come together with the trip and are well-supported analytics and reporting
Search capabilities on FT UI are supported for primary attributes like shipment numbers, feed_unique_id
Analytics dashboards and reports use primary attributes like gate_in, gate_out, expected_transit_time, movement channels etc.
indent_fteid can be used for linking your FT Indent with your trip
If any invalid values are sent in primary attributes, trip creation will fail
Invoice Object
Invoice details are not mandatory for trip creation. But these are required for other features like ePOD, and eLR and could be useful for reporting purposes as well
invoice -> invoice_detailsis an array which can accommodate multiple invoices for the same tripThe only mandatory field for the
invoice_detailssection isinvoice_numberAny other invoice details like
from,to,so_number,so_dateetc., are all optional. If these optional fields are sent, they should be in proper format as mentioned below schema
Date fields
All date fields like gate_in, gate_out, invoice_date, eway_bill_expiry_date etc., are all expected in below format
Our system will show the dates appropriately on FT UI according to the user timezone(IST) for most of the cases for now
Scheduling Trips for Future Creation:
To schedule a trip for a future date, you can do so by providing the desired date in the trip_scheduled_at field within the request body. The trip_scheduled_at field follows the date format conventions used in other date fields. This feature allows you to plan and create trips at a later time.
Schema:
{
"datatype": "object",
"required": [
"vehicleNumber",
"locationSource",
"loading",
"unloading"
],
"properties": {
"is_round_trip": {
"datatype": "boolean",
"description": "If set to true, auto-creation of return trip when forward leg is closed"
},
"trip_scheduled_at": {
"description": "To schedule a trip for a future date. trip_scheduled_at will be in 'YYYY-MM-DD hh:mm:ss' in 24hrs format in UTC or epoch in milliseconds",
"datatype": "string",
"example": "2023-10-11 07:48:00",
},
"vehicleNumber": {
"description": "vehicle number",
"validation": "no special characters",
"datatype": "string",
"example": "AP26BC1234"
},
"portableTrackerUniqueId": {
"datatype": "string",
"example": "AP26BC1234"
},
"driverName": {
"description": "driver name",
"datatype": "string",
"example": "Raju",
"default": "Unknown driver"
},
"driverNumbers": {
"description": "driver mobile numbers",
"validation": "10-digit valid phone number",
"datatype": "array",
"example": [
"9090909090",
"9090912090"
],
"default": [
1234567890
]
},
"locationSource": {
"description": "Type of Device to track the location.",
"datatype": "string",
"example": "sim",
"default": "sim",
"options": [
"sim",
"gps",
"smartPhone"
]
},
"plantCode": {
"description": "reference code of a Branch for access/visibility, Master data onboarding required.",
"datatype": "string",
"example": "BK01",
"validation": "Trip Creation will fail if incorrect data provided"
},
"loading": {
"description": "either object {uniqueId, area, address} where uniqueId field is mandatory OR object {lat, lng, area, address} where lat, lng fields are mandatory fields.",
"datatype": "object",
"properties": {
"lat": {
"datatype": "number",
"format": "double",
"example": 21.65478381
},
"lng": {
"datatype": "number",
"format": "double",
"example": 75.67845632
},
"address": {
"datatype": "string",
"example": "Mumbai, Maharashtra, India"
},
"area": {
"datatype": "string",
"example": "Mumbai, Maharashtra, India"
},
"pincode": {
"datatype": "string",
"example": "524002"
},
"uniqueId": {
"datatype": "string",
"example": "MH01"
}
},
"required": [
"lat",
"lng",
"uniqueId"
]
},
"unloading": {
"description": "either object {uniqueId, area, address} where uniqueId field is mandatory OR object {lat, lng, area, address} where lat, lng fields are mandatory fields.",
"datatype": "object",
"properties": {
"lat": {
"datatype": "number",
"format": "double",
"example": 21.65478381
},
"lng": {
"datatype": "number",
"format": "double",
"example": 75.67845632
},
"address": {
"datatype": "string",
"example": "Mumbai, Maharashtra, India"
},
"area": {
"datatype": "string",
"example": "Mumbai, Maharashtra, India"
},
"pincode": {
"datatype": "string",
"example": "524002"
},
"uniqueId": {
"datatype": "string",
"example": "MH01"
}
},
"required": [
"lat",
"lng",
"uniqueId"
]
},
"waypoints": {
"description": "{uniqueId,lat,lng} combination or {uniqueId, address} combination, or just {uniqueId} (Incase pre-onboarded waypoints) can be passed in the object.",
"datatype": "array",
"items": {
"datatype": "object",
"properties": {
"lat": {
"datatype": "number",
"format": "double",
"example": 21.65478381
},
"lng": {
"datatype": "number",
"format": "double",
"example": 75.67845632
},
"address": {
"datatype": "string",
"example": "Mumbai, Maharashtra, India"
},
"area": {
"datatype": "string",
"example": "Mumbai, Maharashtra, India"
},
"pincode": {
"datatype": "string",
"example": "524002"
},
"uniqueId": {
"datatype": "string",
"example": "MH01"
}
},
"required": [
"lat",
"lng",
"uniqueId"
]
}
},
"route": {
"description": "code is required to resolve places from onboarded routes",
"datatype": "object",
"properties": {
"code": {
"description": "short of the onboarded route",
"datatype": "string",
"example": "Mum-Delhi"
}
}
},
"consignee": {
"description": "{uniqueId, name, ...} uniqueId is mandatory",
"datatype": "object",
"properties": {
"uniqueId": {
"datatype": "string"
},
"name": {
"datatype": "string"
},
"email": {
"datatype": "array",
"items": {
"datatype": "string"
}
},
"number": {
"datatype": "array",
"items": {
"datatype": "number"
}
}
},
"required": [
"uniqueId"
]
},
"transporter": {
"description": "{uniqueId, name, ...} uniqueId is mandatory",
"datatype": "object",
"properties": {
"uniqueId": {
"datatype": "string"
},
"name": {
"datatype": "string"
},
"required": [
"uniqueId"
]
}
},
"consignor": {
"description": "{uniqueId, name, ...} uniqueId is mandatory.",
"datatype": "object",
"properties": {
"uniqueId": {
"datatype": "string"
},
"name": {
"datatype": "string"
}
},
"required": [
"uniqueId"
]
},
"share_trip": {
"description": "can trip be shared with consignee contacts",
"datatype": "boolean",
"example": true
},
"is_round_trip": {
"description": "If set to true, auto-creation of return trip when forward leg is closed",
"datatype": "boolean",
"example": true
},
"lrnumber": {
"description": "lr number",
"datatype": "string",
"example": "AF1153421"
},
"feedUniqueId": {
"description": "Unique Id to be given to a Trip in order to Track it. default is auto set by system at the time of trip creation.",
"datatype": "string",
"example": "101123452"
},
"originSTD": {
"description": "Defined Trip Standard Time of Departure in 24hrs format in UTC",
"datatype": "string",
"default": null,
"example": "2020-01-01 12:30:00"
},
"destinationSTA": {
"description": "Defined Trip Standard Time of Arrival in 24hrs format in UTC",
"datatype": "string",
"default": null,
"example": "2020-01-01 12:30:00"
},
"customValues": {
"datatype": "object",
"additionalProperties": {
"datatype": "string"
},
"properties": {
"invoiceNumber": {
"datatype": "string",
"description": "Any Custom property to be associated to a Trip. Can be Invoice Number, Shipment Number, etc"
}
},
"example": {
"invoiceNumber": "INV123",
"ewayBillExpiryDate": "2020-01-01",
"shipmentNumber": "SHI123",
"property1": "value"
}
},
"primary_attributes": {
"description": "These are some important attributes identified and are used for analytics",
"datatype": "object",
"properties": {
"shipment_numbers": {
"datatype": "array",
"items": {
"datatype": "string"
},
"example": [
"SHP34567",
"SH45578"
]
},
"container_number": {
"datatype": "string"
},
"movement_subtype": {
"datatype": "string"
},
"movement_channel": {
"datatype": "string"
},
"billing_type": {
"datatype": "string",
"example": "To Pay/To Bill"
},
"yard_entry_number": {
"datatype": "string"
},
"expected_transit_time": {
"description": "Expected Transit Time in minutes",
"datatype": "number"
},
"erp_transit_distance": {
"description": "Transit Distance in KM",
"datatype": "number"
},
"gross_weight": {
"description": "Gross Weight in Tons",
"datatype": "number"
},
"tare_weight": {
"description": "Tare Weight in Tons",
"datatype": "number"
},
"net_weight": {
"description": "Net Weight in Tons",
"datatype": "number"
},
"vehicle_type_ref_code": {
"datatype": "string"
},
"gate_in": {
"description": "Gate In Time. Should be a valid date time stamp in 24hrs format in UTC",
"datatype": "string",
"example": "2021-03-16 10:22:22"
},
"gate_out": {
"description": "Gate Out Time. Should be a valid date time stamp in 24hrs format in UTC",
"datatype": "string",
"example": "2021-03-16 10:22:22"
},
"sales_rep_id": {
"datatype": "string"
},
"freight_value": {
"datatype": "number"
},
"freight_value_currency": {
"datatype": "string"
},
"freight_rate_unit": {
"description": "Allowed values - (PER_TON, PER_KM, PER_TON_PER_KM, PER_DAY_PER_TRIP, PER_TRIP, FIXED_RATE)",
"datatype": "string"
},
"freight_rate": {
"datatype": "number"
},
"indent_fteid": {
"datatype": "string"
},
"master_trip_grouping_parameter": {
"type": "string"
},
"unloading_gate_in": {
"type": "string",
"description": "Gate In Time. Should be a valid date time stamp format",
"example": "2021-03-16 10:22:22"
},
"unloading_gate_out": {
"type": "string",
"description": "Gate Out Time. Should be a valid date time stamp format",
"example": "2021-03-16 10:22:22"
}
}
},
"invoice": {
"description": "Invoice Details. MANDATORY for generating Digital LR",
"datatype": "object",
"properties": {
"currency": {
"datatype": "string"
},
"invoice_details": {
"description": "Invoice details are used for creating invoices and digital LR. MANDATORY for Digital ELR",
"datatype": "array",
"items": {
"datatype": "object",
"required": [
"invoice_number"
],
"properties": {
"from": {
"description": "MANDATORY for Digital ELR",
"datatype": "object",
"required": [
"name",
"gstin",
"shipping_address"
],
"properties": {
"name": {
"datatype": "string",
"description": "Sender name"
},
"gstin": {
"datatype": "string",
"description": "Sender GSTIN"
},
"shipping_address": {
"datatype": "string"
},
"billing_address": {
"datatype": "string"
},
"contact_phone": {
"description": "Phone numbers in an array",
"datatype": "array",
"items": {
"datatype": "string"
}
},
"contact_email": {
"description": "Email-Ids in an array",
"datatype": "array",
"items": {
"datatype": "string"
}
}
}
},
"to": {
"datatype": "object",
"description": "MANDATORY for Digital ELR",
"required": [
"name",
"gstin",
"shipping_address",
"contact_phone"
],
"properties": {
"name": {
"datatype": "string",
"description": "Receiver name"
},
"gstin": {
"datatype": "string",
"description": "Sender GSTIN"
},
"shipping_address": {
"datatype": "string"
},
"billing_address": {
"datatype": "string"
},
"contact_phone": {
"description": "Phone numbers in an array",
"datatype": "array",
"items": {
"datatype": "string"
}
},
"contact_email": {
"description": "Email-Ids in an array",
"datatype": "array",
"items": {
"datatype": "string"
}
}
}
},
"so_number": {
"datatype": "string"
},
"so_quantity": {
"datatype": "number"
},
"so_date": {
"description": "so_date will be in 'YYYY-MM-DD hh:mm:ss' in 24hrs format in UTC or epoch in milliseconds",
"datatype": "string"
},
"so_release_date": {
"description": "so_release_date will be in 'YYYY-MM-DD hh:mm:ss' in 24hrs format in UTC or epoch in milliseconds",
"datatype": "string"
},
"po_number": {
"datatype": "string"
},
"do_number": {
"datatype": "string"
},
"do_quantity": {
"datatype": "number"
},
"do_date": {
"description": "do_date will be in 'YYYY-MM-DD hh:mm:ss' in 24hrs format in UTC or epoch in milliseconds",
"datatype": "string"
},
"do_publish_date": {
"description": "do_publish_date will be in 'YYYY-MM-DD hh:mm:ss' in 24hrs format in UTC or epoch in milliseconds",
"datatype": "string"
},
"invoice_number": {
"datatype": "string"
},
"invoice_date": {
"description": "invoice_date will be in 'YYYY-MM-DD hh:mm:ss' in 24hrs format in UTC or epoch in milliseconds",
"datatype": "string"
},
"eway_bill_no": {
"datatype": "string"
},
"eway_bill_expiry_date": {
"description": "eway_bill_expiry_date will be in 'YYYY-MM-DD hh:mm:ss' in 24hrs format in UTC or epoch in milliseconds or yyyy-MM-dd'T'HH:mm:ssZ (ISO offset date time format)",
"datatype": "string"
},
"total_invoice_value": {
"datatype": "number"
},
"description": {
"description": "Invoice Description",
"datatype": "string"
},
"price": {
"description": "Price object",
"datatype": "object",
"properties": {
"net_price": {
"datatype": "number"
},
"total_price": {
"datatype": "number"
},
"total_tax": {
"datatype": "number"
}
}
},
"tax": {
"description": "Tax object",
"datatype": "object",
"properties": {
"cgst_rate": {
"datatype": "number",
"description": "% rate for CGST"
},
"sgst_rate": {
"datatype": "number",
"description": "% rate for SGST"
},
"igst_rate": {
"datatype": "number",
"description": "% rate for IGST"
},
"other_tax_rate": {
"datatype": "number",
"description": "% other tax rate"
},
"cgst": {
"datatype": "number",
"description": "CGST Amount"
},
"sgst": {
"datatype": "number",
"description": "SGST Amount"
},
"igst": {
"datatype": "number",
"description": "IGST Amount"
},
"other_tax": {
"datatype": "number",
"description": "Other tax Amount"
}
}
},
"custom_fields": {
"description": "Any additional params for invoice",
"datatype": "object"
},
"item_details": {
"datatype": "array",
"items": {
"datatype": "object",
"required": [
"product_name"
],
"properties": {
"sku_code": {
"datatype": "string"
},
"material_code": {
"datatype": "string"
},
"hsn_code": {
"datatype": "string"
},
"quantity": {
"datatype": "number"
},
"quantity_unit": {
"datatype": "string"
},
"gross_weight": {
"datatype": "number"
},
"net_weight": {
"datatype": "number"
},
"weight_unit": {
"datatype": "string"
},
"product_name": {
"datatype": "string"
},
"description": {
"datatype": "string"
},
"custom_fields": {
"datatype": "object",
"description": "Any additional params for invoice item details"
},
"price": {
"datatype": "object",
"description": "Price object",
"properties": {
"net_price": {
"datatype": "number"
},
"total_price": {
"datatype": "number"
},
"total_tax": {
"datatype": "number"
}
}
},
"tax": {
"datatype": "object",
"description": "Tax object",
"properties": {
"cgst_rate": {
"datatype": "number",
"description": "% rate for CGST"
},
"sgst_rate": {
"datatype": "number",
"description": "% rate for SGST"
},
"igst_rate": {
"datatype": "number",
"description": "% rate for IGST"
},
"other_tax_rate": {
"datatype": "number",
"description": "% other tax rate"
},
"cgst": {
"datatype": "number",
"description": "CGST Amount"
},
"sgst": {
"datatype": "number",
"description": "SGST Amount"
},
"igst": {
"datatype": "number",
"description": "IGST Amount"
},
"other_tax": {
"datatype": "number",
"description": "Other tax Amount"
}
}
}
}
}
}
}
}
}
}
}
}
}Responses:
{
"status": true,
"result": {
"id": 484290,
"shareUrl": "https://integration.freighttiger.com/v5/shareTrip?shareKey=TRP-cc12b0f8d-3cd4-4f92-a77a-ec9bf6376e0c&_view=true",
"lr_number": "1234",
"feed_unique_id": "DEL-BKR-568"
},
"message": "Trip Created Successfully"
}Post your questions in the comment box to get answers from the experts who watch this page.
For engineering support: visit FT Support