Obtain Authentication Token (login API)
Positioning Shipment (tracking API)
Vehicle List Update (tracking_vehicles API)
Webservice tracking_vehicles QA
Webservice tracking_vehicles PROD
Introduction
The system offers a set of APIs (REST APIs) for updating the positioning of units on the platform.
This document describes the integration process, which will be the same for both the demo and production environments, with the only difference being the credentials (which the IT team will provide in each case) and the URLs.
The process is divided into two phases:
- Testing in the demo environment: The integration will be validated using temporary credentials and test vehicles (provided by the IT team).
- Production implementation: Once testing has been successfully completed, the final credentials for the production environment will be provided.
Each phase is divided into three steps:
- Obtaining the authentication token (valid for 24 hours)
- Updating the unit's position (every 2 minutes)
- Updating the vehicle list (at least when new units are included, ideally every hour)
Obtain Authentication Token (login API)
To execute any of the endpoints, you must authenticate yourself using a Bearer token obtained through the login API.
Authentication is carried out by verifying your email address and password, which will be provided by the IT department. Through authentication, the user will obtain a token that will be valid for 24 hours. This token must be stored and only a new one generated when an expired token error is returned.
Request
- Request type: POST
- Parameter content type: application/json
-
Body attributes
{ "email": "string", //Mandatory "force": true, //Mandatory, constant value true by default "password": " string", //Mandatory "role": "API_TRACKING" //Mandatory, must take the value “API_TRACKING” }
Response
{
"expire": 0,
"token": "string",
"user": {
"active": true,
"first_name": "string",
"id": 0,
"image_profile_url": "string",
"last_name": "string",
"mobile_number": "string",
"nick_name": "string",
"player_id": "string",
"roles": [
{
"description": "string",
"name": "string"
}
]
}
}Example
REQUEST
POST: https://qa.fr8.app/v1/login
Payload del Body (JSON):
{
"email": "fr8app@fr8app.com",
"force": true,
"password": "1601000#Fr8APP",
"role": "API_TRACKING"
}{
"exp": 1729727977,
"token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.JmcjhodWJfd2ViIiwiZXhwIjoxNzI5NzI3OTc3LCJpYXQiOjE3MTUyMTI3NzcsImlzcyI6ImZyOGh1Yl93ZWIiLCJqdGkiOiI5NzYxZDc3Yy01NGIyLTRiNTUtOTFhNS1iMjlkFGFhY2YwY2QiLCJuYmYiOjE3MTUyMTI3NzYsInN1YiI6IjEwNCIsInR5cCI6ImFjY2VzcyJ9.m73ADrBaxu_b-1GsZLYhbSu_X3p_7ekHMZVarhmTLygVn7yIRsMGUGMQmFFRrq3Z22dZ35kJZ9P5CnFM_xVn0g",
"user": {
"active": true,
"email": "fr8app@fr8app.com",
"first_name": "Ana",
"id": 110,
"image_profile_url": null,
"last_name": "test",
"mobile_number": "5200000000",
"nick_name": null,
"player_id": null,
"roles": [
{
"description": "Tracking update through API",
"name": "API_TRACKING" } ] }
} Webservice login QA
- API: https://qa.fr8.app/v1/login
- Credentials: Given by the IT team
Webservice login PROD
- API: https://my.fr8.app/v1/login
- Credentials: Provided after validation in a test environment.
Positioning Shipment (tracking API)
To update coordinate positions on demand in the system, it will be necessary to use a Bearer Token previously obtained by the login method.
- Identifiers: In the testing environment (QA), the identifiers previously agreed upon with IT must be used for the tractor/trailer ID and tractor/trailer plates. These can be modified, but must be confirmed with the IT team for correct configuration.
- Recommended frequency: Every 2 minutes. Must not exceed 5 minutes.
Request
- Request type: POST
- Authorization type: Beare Token
- Parameter content type: application/json
- Body attributes
{
"equipment": [
{
"city": "string", //Non Mandatory
"country": "string", //Non Mandatory, possible values MX, US, CA
"date_time": "string", //Non Mandatory, last position in UTC format
2024-10-31 01:42:37
"latitude": numeric, //Mandatory
"longitude": numeric, //Mandatory
"postal_code": "string", //Non Mandatory
"speed": numeric, //Non Mandatory
"state": "string", //Non Mandatory
"tractor": "string", //"TR-1001"
"tractor_plates": "string",//"ABC1234"
"Trailer": "string",// "TL-0900"
"trailer_plates": "string"//"XYZ-098"
}
]
} ⚠️ With regard to the parameters "tractor," "tractor_plates," "trailer," and "trailer_plates," at least one must be different from NULL.
Example
- POST: https://qa.fr8.app/v1/tracking
- Authorization: authorization - Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJmcjhodWJfd2ViIiwiZXhwIjoxNzI5NzI3OTc3LCJpYXQiOjE3MTUyMTI3NzcsImlzcyI6ImZyOGh1Yl93ZWIiLCJqdGkiOiI5NzYxZDc3Yy01NGIyLTRiNTUtOTFhNS1iMjlkFGFhY2YwY2QiLCJuYmYiOjE3MTUyMTI3NzYsInN1YiI6IjEwNCIsInR5cCI6ImFjY2VzcyJ9.m73ADrBaxu_b-1GsZLYhbSu_X3p_7ekHMZVarhmTLygVn7yIRsMGUGMQmFFRrq3Z22dZ35kJZ9P5CnFM_xVn0g
- Payload of the Body (JSON):
{
"equipment": [
{
"city": "Querétaro",
"country": "MX",
"date_time": "2025-01-16 14:47:30",
"latitude": 20.313585,
"longitude": -98.194573,
"postal_code": "",
"speed": 88,
"state": "México",
"tractor": "",
"tractor_plates": "",
"trailer": "B222",
"trailer_plates": ""
}
]
}Webservice tracking QA
- API: https://qa.fr8.app/v1/tracking
- Token: The token obtained must be included in the login.
Webservice tracking PROD
- API: https://my.fr8.app/v1/tracking
- Token: The token obtained must be included in the login.
Vehicle List Update (tracking_vehicles API)
To update the list of units available in the system, you will need to use a Bearer Token obtained previously by the login method and provide all the fields required by the method.
- Recommended frequency: It can be run on demand when units are updated or periodically every hour (recommended).
Request
- Request type: POST
- Authorization type: Bearer Token
- Parameter content type: application/json
- Body attributes
{
"tractor": [
{
"name": "string",
"plates": "string"
},
{
"name": "string",
"plates": "string"
}
],
"trailer": [
{
"name": "string",
"plates": "string"
},
{
"name": "string",
"plates": "string"
}
]
}⚠️ To update a tractor or trailer, at least one of the parameters must be different from NULL (either name or plates).
⚠️ Only one of the objects (either trailer or tractor) should be included in the payload.
Example
- POST: https://qa.fr8.app/v1/tracking_vehicles
- Authorization: authorization - Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJmcjhodWJfd2ViIiwiZXhwIjoxNzI5NzI3OTc3LCJpYXQiOjE3MTUyMTI3NzcsImlzcyI6ImZyOGh1Yl93ZWIiLCJqdGkiOiI5NzYxZDc3Yy01NGIyLTRiNTUtOTFhNS1iMjlkFGFhY2YwY2QiLCJuYmYiOjE3MTUyMTI3NzYsInN1YiI6IjEwNCIsInR5cCI6ImFjY2VzcyJ9.m73ADrBaxu_b-1GsZLYhbSu_X3p_7ekHMZVarhmTLygVn7yIRsMGUGMQmFFRrq3Z22dZ35kJZ9P5CnFM_xVn0g
- Payload of Body (JSON):
{
"tractor": [
{
"name": "TR-1001",
"plates": "ABC1234"
},
{
"name": "TR-1002",
"plates": "XYZ9876"
}
],
"trailer": [
{
"name": "TL-1001",
"plates": "QWE1234"
},
{
"name": "TL-1002",
"plates": "ASD9876"
}
]
} Webservice tracking_vehicles QA
- API: https://qa.fr8.app/v1/tracking_vehicles
- Token: The token obtained must be included in the login.
Webservice tracking_vehicles PROD
- API: https://my.fr8.app/v1/tracking_vehicles
- Token: The token obtained must be included in the login.
Final Considerations
- The IT team will provide support throughout the integration process, ensuring that each step works correctly and providing assistance if necessary.
- Once the integration in the test environment has been successfully validated, testing in that environment can be stopped and activation in production can proceed.
- It is essential to use the agreed identifiers in the test environment to avoid configuration errors.
- In case of any adjustments or problems during integration, contact the IT team.