Comenzar

Autenticación

Vehículos

Alertas

Estaciones

Introducción

Bienvenido a la documentación de la API de Stelematic. Esta API permite interactuar con los servicios de la plataforma, principalmente para la gestión y monitoreo de vehículos, telemetría, alertas y geocercas (estaciones).

URL Base

Todas las rutas de la API descritas en esta documentación comienzan con la siguiente URL base:

https://s1.stelematic.com

Flujo de Autenticación

La API de Stelematic utiliza un sistema de autenticación basado en sesiones (cookies) para verificar las solicitudes.

Pasos para autenticarse:

  1. Realiza una solicitud POST al endpoint /api/auth/login con tu email y contraseña.
  2. Si las credenciales son correctas, el servidor responderá con un 200 OK.
  3. En la respuesta, el servidor incluirá una cabecera Set-Cookie (o varias) que establece la cookie de sesión (ej. session_id).
  4. Tu cliente HTTP (navegador o herramienta API) debe almacenar esta cookie y enviarla automáticamente en todas las solicitudes posteriores a la API.
  5. Para verificar que la sesión está activa, puedes llamar a GET /api/auth/.

Login de usuario

Autentica a un usuario en la plataforma y genera una sesión (cookie).

POST /api/auth/login

Cabeceras (Request Headers)

Cabecera Valor
Content-Type application/json

Cuerpo (Request Body)

Parámetro Tipo Descripción
email string Email del usuario.
password string Contraseña del usuario.
keepMeSigned boolean Indica si se debe mantener la sesión activa.

Ejemplo de Payload

{
                    "email": "jerobot@gmail.com",
                    "password": "PASSWORD_SECRETO",
                    "keepMeSigned": false
                   }

Respuesta Exitosa (200 OK)

La respuesta principal es la cookie de sesión establecida en las cabeceras. El cuerpo de la respuesta también puede contener información de la cuenta.

                    // Cabecera de Respuesta (Headers)
Set-Cookie: session_id=...; HttpOnly; Path=/;

// Cuerpo de Respuesta (Body)
{
  "account_id": "0059..."
}

Obtener sesión actual

Obtiene información de la sesión del usuario actualmente autenticado (requiere cookie de sesión).

GET /api/auth/

Cabeceras (Request Headers)

Esta solicitud debe incluir la cookie de sesión obtenida durante el login.

Cabecera Valor
Cookie session_id=...

Respuesta Exitosa (200 OK)

{
  "account_id": "0059..." // ID de la cuenta del usuario logueado
}

Datos del día (por ID)

Obtiene la telemetría (historial de ubicaciones, velocidad, etc.) del día actual para un vehículo específico.

GET /api/vehicle/vehicle-today/{id}

Parámetros de Ruta (Path Parameters)

Parámetro Tipo Descripción
{id} string ID único del vehículo. (Ej: 188)

Respuesta Exitosa (200 OK)

                    
{
    "vehicle": {
        "vehicle_id": 188,
        "custom_id": "AT-177",
        "module_imei": "862430053233371",
        "unlocked": 1,
        "refueled": 187,
        "fuel_lvl": 0,
        "locked_times": 0,
        "paired": 1,
        "paired_serial": null,
        "connected": "2025-11-08T18:49:03.000Z",
        "registered": "2024-02-07T07:53:43.899Z",
        "visited_competitor": 0,
        "tank_size": 120,
        "gas_usage": 100,
        "buffer": 1762627690,
        "buffer_records": 1,
        "phone_number": "4921342410",
        "reports": "0",
        "average_consumption": 3,
        "engine_type": "petrol",
        "consumption_difference": 15,
        "alternative_fuel_type": "lpg",
        "email_notifications": null,
        "compatible": 1,
        "ignition": 1,
        "controller_connected": 1,
        "igl": 0,
        "account_id": "005964a9-a8e4-4f56-8e0e-0ba271fa1423",
        "payment_date": "2099-11-30T00:00:00.000Z",
        "notifications": {
            "vehicle_locked": true,
            "vehicle_communication": "true",
            "vehicle_gas_percentage": false,
            "vehicle_payment_overdue": "false"
        },
        "data_frequency": "10",
        "module_version": "32.4.1",
        "paid": 1,
        "auto_lock": false,
        "ignore_payment": false,
        "data_usage": "7662",
        "group_id": "4e19c754-59c7-450a-a499-1dedf4c56e8e",
        "minimum_gas_usage": 0,
        "maint_plan": 0,
        "maint_prog": 0,
        "mainten": null,
        "refuel_sensitivity": 2,
        "gas_sensor_type": 255,
        "calendar_lock": false,
        "calendar_lock_date": null
    },
    "vehiclePosition": [
        {
            "ts": "1762627739",
            "id_mod": "862430053233371",
            "location_ts": "2025-11-08 18:48:59",
            "loc_lt": "22.951531",
            "loc_ln": "-102.705085",
            "loc_hd": "323",
            "loc_sp": "4.8",
            "hwi_ca": null,
            "reason": "t"
        }
    ]
}

Modelo de Datos (Objeto de Telemetría)

Campo Descripción
ts Timestamp (Unix) del reporte.
loc_lt Latitud (Localización).
loc_ln Longitud (Localización).
loc_hd Heading (Dirección o rumbo, en grados).
loc_sp Speed (Velocidad, probablemente en km/h).
hwi_ca Dato de hardware (valor `null` en los ejemplos).

Obtener vehículos bloqueados

Recupera una lista de vehículos que se encuentran en estado "bloqueado".

GET /api/vehicle/locked/

Parámetros de Consulta (Query Parameters)

Parámetro Tipo Descripción
limit number Número máximo de resultados. (Ej: 1000)
skip number Número de resultados a omitir (paginación). (Ej: 0)

Respuesta Exitosa (200 OK)

{
  "locked_vehicles": 5,
  "vehicles": [
    {
      "vehicle_id": 188,
      "custom_id": "AT-177",
      "module_imei": "862430053233371",
      "unlocked": 0,
      "locked_times": 3,
      "connected": "2025-11-08T18:49:03.000Z"
    },
    // ...más vehículos bloqueados
  ]
}

Contar vehículos

Devuelve el número total de vehículos asociados a la cuenta.

GET /api/vehicle/count/

Respuesta Exitosa (200 OK)

{
  "count": 150 // Número total de vehículos
}

Obtener posición del vehículo

Obtiene la posición actual y datos del vehículo específico.

GET /api/vehicle/position/{id}

Parámetros de Ruta (Path Parameters)

Parámetro Tipo Descripción
{id} string ID único del vehículo. (Ej: 188)

Parámetros de Consulta (Query Parameters)

Parámetro Tipo Descripción
limit number Número máximo de registros de posición a devolver. (Ej: 1)

Ejemplo de URL

https://s1.stelematic.com/api/vehicle/position/188?limit=1

Respuesta Exitosa (200 OK)

{
  "vehicle": {
    "vehicle_id": 188,
    "custom_id": "AT-177",
    "module_imei": "862430053233371",
    "unlocked": 1,
    "refueled": 187,
    "fuel_lvl": 0,
    "locked_times": 0,
    "paired": 1,
    "paired_serial": null,
    "connected": "2025-11-08T18:49:42.000Z",
    "registered": "2024-02-07T07:53:43.899Z",
    "visited_competitor": 0,
    "tank_size": 120,
    "gas_usage": 100,
    "buffer": 1762627750,
    "buffer_records": 1,
    "phone_number": "4921342410",
    "reports": "0",
    "average_consumption": 3,
    "engine_type": "petrol",
    "consumption_difference": 15,
    "alternative_fuel_type": "lpg",
    "email_notifications": null,
    "compatible": 1,
    "ignition": 1,
    "controller_connected": 1,
    "igl": 0,
    "account_id": "005964a9-a8e4-4f56-8e0e-0ba271fa1423",
    "payment_date": "2099-11-30T00:00:00.000Z",
    "notifications": {
      "vehicle_locked": true,
      "vehicle_communication": "true",
      "vehicle_gas_percentage": false,
      "vehicle_payment_overdue": "false"
    },
    "data_frequency": "10",
    "module_version": "32.4.1",
    "paid": 1,
    "auto_lock": false,
    "ignore_payment": false,
    "data_usage": "7662",
    "group_id": "4e19c754-59c7-450a-a499-1dedf4c56e8e",
    "minimum_gas_usage": 0,
    "maint_plan": 0,
    "maint_prog": 0,
    "mainten": null,
    "refuel_sensitivity": 2,
    "gas_sensor_type": 255,
    "calendar_lock": false,
    "calendar_lock_date": null
  },
  "vehiclePosition": [
    {
      "ts": "1762627779",
      "id_mod": "862430053233371",
      "location_ts": "2025-11-08 18:49:39",
      "loc_lt": "22.952223",
      "loc_ln": "-102.705785",
      "loc_hd": "322",
      "loc_sp": "9.1",
      "hwi_ca": null,
      "reason": "t"
    }
  ]
}

Actividad de flota

Obtiene la actividad de todos los vehículos de la flota para una fecha específica, incluyendo distancia recorrida y estadísticas.

GET /api/vehicle/fleet/activity/

Parámetros de Consulta (Query Parameters)

Parámetro Tipo Descripción
limit number Número máximo de vehículos a devolver. (Ej: 10)
skip number Número de vehículos a omitir (paginación). (Ej: 0)
date string Fecha para la consulta en formato YYYY-MM-DD. (Ej: 2025-11-09)
group_id string ID del grupo de vehículos. Usar all para todos los grupos.
param string Parámetro adicional para filtrar. (Ej: dist para distancia)
paramValue boolean Valor del parámetro adicional. (Ej: true)

Ejemplo de URL

https://s1.stelematic.com/api/vehicle/fleet/activity/?limit=10&skip=0&date=2025-11-09&group_id=all¶m=dist¶mValue=true

Respuesta Exitosa (200 OK)

{
  "vehiclesOnTheFlyCount": "7",
  "vehiclesOnTheFly": [
    {
      "vehicle_id": 372,
      "custom_id": "Toyota yaris",
      "module_imei_vh": "866897053002251",
      "connected": "2025-11-10T04:39:44.000Z",
      "account_id": "005964a9-a8e4-4f56-8e0e-0ba271fa1423",
      "group_id": "4e19c754-59c7-450a-a499-1dedf4c56e8e",
      "id_mod_loc_st": "866897053002251",
      "ts_st": "1762646401",
      "loc_ts_st": "2025-11-09 00:00:01",
      "rea_loc_st": "c",
      "id_mod_loc_sp": "866897053002251",
      "ts_sp": "1762731792",
      "loc_ts_sp": "2025-11-09 23:43:12",
      "rea_loc_sp": "s",
      "module_imei_rrd": "866897053002251",
      "rep_tp_diff": "12151",
      "rep_tg_diff": "5073",
      "rep_dp_diff": "58.42",
      "rep_dg_diff": "43.96",
      "dist": "102.38",
      "perc": "43"
    },
    {
      "vehicle_id": 191,
      "custom_id": "AT-189",
      "module_imei_vh": "862430053379240",
      "connected": "2025-06-04T22:07:18.000Z",
      "account_id": "005964a9-a8e4-4f56-8e0e-0ba271fa1423",
      "group_id": "4e19c754-59c7-450a-a499-1dedf4c56e8e",
      "id_mod_loc_st": null,
      "ts_st": null,
      "loc_ts_st": null,
      "rea_loc_st": null,
      "id_mod_loc_sp": null,
      "ts_sp": null,
      "loc_ts_sp": null,
      "rea_loc_sp": null,
      "module_imei_rrd": null,
      "rep_tp_diff": null,
      "rep_tg_diff": null,
      "rep_dp_diff": null,
      "rep_dg_diff": null,
      "dist": null,
      "perc": null
    },
    // ... más vehículos
  ]
}

Campos principales de respuesta

Campo Descripción
vehiclesOnTheFlyCount Número total de vehículos en la flota.
dist Distancia total recorrida por el vehículo (en km).
perc Porcentaje de actividad del vehículo.
rep_tp_diff Diferencia de tiempo de reporte de petróleo.
rep_tg_diff Diferencia de tiempo de reporte de gas.
rep_dp_diff Diferencia de distancia de reporte de petróleo.
rep_dg_diff Diferencia de distancia de reporte de gas.

Vehículos sin comunicación

Obtiene la lista de vehículos que no han reportado comunicación recientemente.

GET /api/vehicle/no-communication/

Parámetros de Consulta (Query Parameters)

Parámetro Tipo Descripción
limit number Número máximo de vehículos a devolver. (Ej: 12)
skip number Número de vehículos a omitir (paginación). (Ej: 0)
param string Campo por el cual ordenar los resultados. (Ej: custom_id)
paramValue boolean Indica si se debe ordenar ascendente (true) o descendente (false).

Ejemplo de URL

https://s1.stelematic.com/api/vehicle/no-communication/?limit=12&skip=0¶m=custom_id¶mValue=true

Respuesta Exitosa (200 OK)

{
                  "vehiclesNoCommunication": [
                    {
                      "vehicle_id": 194,
                      "custom_id": "AT-75",
                      "module_imei": "862430053385361",
                      "connected": "2025-10-28T20:16:27.000Z"
                    },
                    {
                      "vehicle_id": 191,
                      "custom_id": "AT-189",
                      "module_imei": "862430053379240",
                      "connected": "2025-06-04T22:07:18.000Z"
                    }
                  ],
                  "vehiclesNoCommunicationCount": "2"
                }

Campos de respuesta

Campo Descripción
vehiclesNoCommunicationCount Número total de vehículos sin comunicación.
vehicle_id ID único del vehículo.
custom_id Identificador personalizado del vehículo.
module_imei IMEI del módulo de comunicación del vehículo.
connected Última fecha y hora de conexión del vehículo.

Explotación de flota

Obtiene estadísticas de explotación y utilización de los vehículos de la flota para un mes específico.

GET /api/vehicle/fleet/exploitation/

Parámetros de Consulta (Query Parameters)

Parámetro Tipo Descripción
limit number Número máximo de vehículos a devolver. (Ej: 10)
skip number Número de vehículos a omitir (paginación). (Ej: 0)
month string Mes para la consulta en formato YYYY-MM. (Ej: 2025-11)
group_id string ID del grupo de vehículos. Usar all para todos los grupos.
param string Campo por el cual ordenar los resultados. (Ej: custom_id)
paramValue boolean Indica si se debe ordenar ascendente (true) o descendente (false).

Ejemplo de URL

https://s1.stelematic.com/api/vehicle/fleet/exploitation/?limit=10&skip=0&month=2025-11&group_id=all¶m=custom_id¶mValue=true

Respuesta Exitosa (200 OK)

{
  "vehiclesExploitationCount": "5",
  "vehiclesExploitation": [
    {
      "vehicle_id": 372,
      "custom_id": "Toyota yaris",
      "module_imei": "866897053002251",
      "group_title": "Main",
      "gas_usage": 88,
      "total_time_s": "52347",
      "exploitation_percentage": 6
    },
    {
      "vehicle_id": 217,
      "custom_id": "AT-683",
      "module_imei": "862430053233413",
      "group_title": "Main",
      "gas_usage": 100,
      "total_time_s": "214984",
      "exploitation_percentage": 25
    },
    {
      "vehicle_id": 192,
      "custom_id": "AT-32",
      "module_imei": "862430053366254",
      "group_title": "Main",
      "gas_usage": 100,
      "total_time_s": "86183",
      "exploitation_percentage": 10
    },
    {
      "vehicle_id": 190,
      "custom_id": "AT-188",
      "module_imei": "862430053217051",
      "group_title": "Main",
      "gas_usage": 100,
      "total_time_s": "168626",
      "exploitation_percentage": 20
    },
    {
      "vehicle_id": 188,
      "custom_id": "AT-177",
      "module_imei": "862430053233371",
      "group_title": "Main",
      "gas_usage": 100,
      "total_time_s": "151598",
      "exploitation_percentage": 18
    }
  ]
}

Campos de respuesta

Campo Descripción
vehiclesExploitationCount Número total de vehículos en explotación.
group_title Nombre del grupo al que pertenece el vehículo.
gas_usage Porcentaje de uso de combustible (0-100).
total_time_s Tiempo total de operación en segundos.
exploitation_percentage Porcentaje de explotación del vehículo.

Obtener nuevas alertas

Obtiene un listado o conteo de las nuevas alertas generadas para el usuario.

GET /api/alert/new

Respuesta Exitosa (200 OK)

{
  "new_alerts": 3,
  "alerts": [
    {
      "id": "alert_123",
      "vehicle_id": "188",
      "type": "SPEEDING",
      "timestamp": "1762608000"
    },
    // ...más alertas
  ]
}

Ecoscore de flota

Obtiene métricas de ahorro de CO2 y porcentaje de combustible alternativo para los vehículos de la flota.

GET /api/vehicle/fleet/ecoscore/

Parámetros de Consulta

Parámetro Tipo Descripción
limit number Número máximo de vehículos a devolver.
skip number Número de vehículos a omitir (paginación).
month string Mes para la consulta en formato YYYY-MM.
group_id string ID del grupo de vehículos.
param string Campo por el cual ordenar los resultados.
paramValue boolean Orden ascendente (true) o descendente (false).

Ejemplo de URL

https://s1.stelematic.com/api/vehicle/fleet/ecoscore/?limit=10&skip=0&month=2025-11&group_id=all¶m=custom_id¶mValue=true

Respuesta Exitosa (200 OK)

{
    "vehiclesEcoScore": [
        {
            "module_imei": "866897053002251",
            "total_savings_co2_kg": "59.231976136482886",
            "total_alternative_percent": "50.9538382875579350",
            "custom_id": "Toyota yaris",
            "vehicle_id": 372
        },
        {
            "module_imei": "862430053233413",
            "total_savings_co2_kg": "13.9339274223842394",
            "total_alternative_percent": "99.7238264022847429",
            "custom_id": "AT-683",
            "vehicle_id": 217
        },
        {
            "module_imei": "862430053366254",
            "total_savings_co2_kg": "6.8991384631733570",
            "total_alternative_percent": "99.9540738415040825",
            "custom_id": "AT-32",
            "vehicle_id": 192
        },
        {
            "module_imei": "862430053217051",
            "total_savings_co2_kg": "13.5933186355314400",
            "total_alternative_percent": "99.9434682872304729",
            "custom_id": "AT-188",
            "vehicle_id": 190
        },
        {
            "module_imei": "862430053233371",
            "total_savings_co2_kg": "6.0082515960016250",
            "total_alternative_percent": "99.8960234216374000",
            "custom_id": "AT-177",
            "vehicle_id": 188
        }
    ],
    "vehiclesEcoScoreCount": "5"
}

Obtener lista de estaciones

Obtiene la lista de estaciones (geocercas o puntos de interés) asociadas a la cuenta.

GET /api/station/

Parámetros de Consulta (Query Parameters)

Parámetro Tipo Descripción
limit number Número máximo de resultados. (Ej: 100)
skip number Número de resultados a omitir (paginación). (Ej: 0)

Respuesta Exitosa (200 OK)

[
  {
    "id": "station_001",
    "name": "Base Central",
    "latitude": "22.959000",
    "longitude": "-102.710000",
    "radius_meters": 500
  },
  // ...más estaciones
]