Este documento describe el proceso de integración, que será el mismo tanto para el entorno de demo como para el de producción, con la única diferencia de las credenciales (que el equipo de IT proporcionará en cada caso) y las URLs.

El proceso se divide en dos fases:

Pruebas en entorno de demo: Se validará la integración utilizando credenciales temporales y vehículos de prueba (proporcionados por el equipo de IT).
Implementación en producción: Una vez completadas las pruebas con éxito, se proporcionarán las credenciales finales para el entorno de producción.

Cada fase se divide en tres pasos:

Obtención del token de autenticación (tiene una duración de 24h)
Actualización del posicionamiento de la unidad (cada 2min)
Actualización del listado de vehículos (mínimo cuando se incluyan nuevas unidades, idealmente cada 1h)

Obtener Token de Autenticación (login API)

Para ejecutar cualquiera de los endpoints, es necesario autenticarse a través de un Bearer token que se obtiene mediante la API de login.

La autenticación se lleva a cabo mediante la verificación de email y contraseña, que serán proporcionadas por el departamento de sistemas. A través de la autenticación el usuario obtendrá un token que será válido durante 24h. Se debe almacenar este token y sólo generar uno nuevo cuando se retorne un error de token expirado.

Request

Tipo de petición: POST
Parameter content type: application/json

Body attributes

  {
     "email": "string", //Obligatorio
     "force": true, //Obligatorio, valor constante por defecto a true
     "password": " string", //Obligatorio
     "role": "API_TRACKING" //Obligatorio, deberá tomar el valor “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"
      }
    ]
  }
}

Ejemplo

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
Credenciales: Proporcionadas por el equipo de IT

Webservice login PROD

API: https://my.fr8.app/v1/login
Credenciales: Se proporcionarán tras la validación en entorno de pruebas

Envío de Posicionamiento (tracking API)

Para la actualización de las posiciones de coordenadas bajo demanda en el sistema, será necesario utilizar un Bearer Token obtenido previamente por el método login.

Identificadores: En entorno de pruebas (QA), se deben utilizar los identificadores previamente acordados con IT para el tractor/trailer ID y tractor/trailer plates. Estos pueden modificarse, pero deben confirmarse con el equipo de IT para su correcta configuración.
Frecuencia recomendada: Cada 2 minutos. No debe exceder los 5 minutos.

Request

Tipo de petición: POST
Tipo de Authorization: Bearer Token
Parameter content type: application/json
Body attributes

{
 "equipment": [
   {
     "city": "string", //No Obligatorio
     "country": "string", //No Obligatorio, posibles valores MX, US, CA
     "date_time": "string", //No Obligatorio, último posicionamiento en UTC formato 2024-10-31 01:42:37
     "latitude": numeric, //Obligatorio
     "longitude": numeric, //Obligatorio
     "postal_code": "string", //No Obligatorio
     "speed": numeric, //No Obligatorio
     "state": "string", //No Obligatorio
     "tractor": "string", //"TR-1001"
     "tractor_plates": "string",//"ABC1234"
     "trailer": "string",// "TL-0900"
     "trailer_plates": "string"//"XYZ-098"
   }
 ]
}

⚠️ Con respecto a los parámetros “tractor”, “tractor_plates”, “trailer”, “trailer_plates” es obligatorio que al menos uno sea distinto de NULL.

Ejemplo

POST: https://qa.fr8.app/v1/tracking
Authorization: authorization - Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJmcjhodWJfd2ViIiwiZXhwIjoxNzI5NzI3OTc3LCJpYXQiOjE3MTUyMTI3NzcsImlzcyI6ImZyOGh1Yl93ZWIiLCJqdGkiOiI5NzYxZDc3Yy01NGIyLTRiNTUtOTFhNS1iMjlkFGFhY2YwY2QiLCJuYmYiOjE3MTUyMTI3NzYsInN1YiI6IjEwNCIsInR5cCI6ImFjY2VzcyJ9.m73ADrBaxu_b-1GsZLYhbSu_X3p_7ekHMZVarhmTLygVn7yIRsMGUGMQmFFRrq3Z22dZ35kJZ9P5CnFM_xVn0g
Payload del 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: Se debe incluir el token obtenido en el login.

Webservice tracking PROD

API: https://my.fr8.app/v1/tracking
Token: Se debe incluir el token obtenido en el login.

Actualización del Listado de Vehículos (tracking_vehicles API)

Para la actualización del listado de unidades disponibles en el sistema, será necesario utilizar un Bearer Token obtenido obtenido previamente por el método login y proporcionar todos los campos requeridos por el método.

Frecuencia recomendada: Puede ejecutarse bajo demanda cuando se actualicen las unidades o de manera periódica cada 1 hora (recomendado).

Request

Tipo de petición: POST
Tipo de Authorization: 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"
    }
  ]
}

⚠️ Para actualizar tractor o trailer, es obligatorio que al menos uno de los parámetros sea distinto de NULL (o name o plates).
⚠️ Sólo debe incluirse en el payload uno de los objetos (o trailer o tractor).

Ejemplo

POST: https://qa.fr8.app/v1/tracking_vehicles
Authorization: authorization - Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJmcjhodWJfd2ViIiwiZXhwIjoxNzI5NzI3OTc3LCJpYXQiOjE3MTUyMTI3NzcsImlzcyI6ImZyOGh1Yl93ZWIiLCJqdGkiOiI5NzYxZDc3Yy01NGIyLTRiNTUtOTFhNS1iMjlkFGFhY2YwY2QiLCJuYmYiOjE3MTUyMTI3NzYsInN1YiI6IjEwNCIsInR5cCI6ImFjY2VzcyJ9.m73ADrBaxu_b-1GsZLYhbSu_X3p_7ekHMZVarhmTLygVn7yIRsMGUGMQmFFRrq3Z22dZ35kJZ9P5CnFM_xVn0g
Payload del 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: Se debe incluir el token obtenido en el login.

Webservice tracking_vehicles PROD

API: https://my.fr8.app/v1/tracking_vehicles
Token: Se debe incluir el token obtenido en el login.

Consideraciones Finales

El equipo de IT proporcionará acompañamiento durante todo el proceso de integración, asegurando que cada paso funcione correctamente y brindando soporte en caso de ser necesario.
Una vez que la integración en el entorno de test haya sido validada con éxito, se podrán detener las pruebas en ese entorno y proceder con la activación en producción.
Es fundamental utilizar los identificadores acordados en el entorno de test para evitar errores en la configuración.
En caso de cualquier ajuste o problema durante la integración, contactar al equipo de IT.

Introducción

Obtener Token de Autenticación (login API)

Request

Response

Ejemplo

Webservice login QA

Webservice login PROD

Envío de Posicionamiento (tracking API)

Request

Ejemplo

Webservice tracking QA

Webservice tracking PROD

Actualización del Listado de Vehículos (tracking_vehicles API)

Request

Ejemplo

Webservice tracking_vehicles QA

Webservice tracking_vehicles PROD

Consideraciones Finales

Artículos relacionados