Dispositivos

Administra las unidades de rastreo GPS de tu flota — lista, inspecciona, obtené la posición en tiempo real o actualiza la configuración.

Requisitos previos

Todos los endpoints requieren un token JWT válido, una clave de API y el encabezado tenant. Consultá Autenticación.

Listar dispositivos

Obtiene una lista paginada de dispositivos con soporte de filtrado.

GET/apidev/v1/fleet/devices

PermisoAPICLI_FLEET_DEVICES_READ

Límite de solicitudes30 solicitudes/min (ventana deslizante)

Caché60s

Parámetros de consulta

Parámetro	Tipo	Requerido	Por defecto	Descripción
`limit`	integer	No	`25`	Registros por página. Mín: `1`, Máx: `100`
`offset`	integer	No	`0`	Registros a omitir
`status`	string	No	—	`A` (activo) o `I` (inactivo)
`name`	string	No	—	Coincidencia parcial sobre el nombre o alias del dispositivo. Longitud máxima 80
`imei`	string	No	—	Coincidencia parcial sobre el IMEI (primario o secundario). Longitud máxima 50
`license_plate`	string	No	—	Coincidencia parcial sobre la patente. Longitud máxima 30
`device_group`	string	No	—	Coincidencia parcial sobre el nombre del grupo de dispositivos. Longitud máxima 80

Campos de la respuesta

Campo	Tipo	Descripción
`id`	string	Identificador único del dispositivo (BigInt como string)
`name`	string \| null	Nombre para mostrar del dispositivo
`alias`	string \| null	Alias corto
`license_plate`	string \| null	Patente del vehículo
`imei_app`	string \| null	Número IMEI primario
`imei_gps`	string \| null	Número IMEI secundario
`external_id`	string \| null	Identificador en un sistema externo
`active`	boolean	Si el dispositivo está activo actualmente
`status`	string	`"A"` (activo) o `"I"` (inactivo)
`device_group`	string \| null	Nombre del grupo o categoría
`last_position`	object \| null	Última posición GPS conocida (ver Campos de posición)

Ejemplo de código

cURL
JavaScript
Python

curl -s "https://$TENANT/apidev/v1/fleet/devices?limit=10&status=A" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

const response = await fetch(
  `https://${TENANT}/apidev/v1/fleet/devices?limit=10&status=A`,
  {
    headers: {
      "Authorization": `Bearer ${token}`,
      "X-API-Key": API_KEY,
      "tenant": TENANT,
    },
  }
);

const { data, meta } = await response.json();
console.log(`Fetched ${data.length} of ${meta.total} devices`);

response = requests.get(
    f"https://{TENANT}/apidev/v1/fleet/devices",
    headers=headers,
    params={"limit": 10, "status": "A"},
)

result = response.json()
for device in result["data"]:
    print(f"{device['id']}: {device['name']} ({device['status']})")

Respuesta de ejemplo

{
  "success": true,
  "data": [
    {
      "id": "104820579301",
      "name": "Movil 10",
      "alias": "M10",
      "license_plate": "ABC123",
      "imei_app": "352093081234567",
      "imei_gps": "352093089876543",
      "external_id": null,
      "active": true,
      "status": "A",
      "device_group": "Trucks",
      "last_position": {
        "latitude": "-34.9011",
        "longitude": "-56.1645",
        "speed": "45.2",
        "heading": 180,
        "datetime": "2026-04-04T14:32:00",
        "last_signal_at": "2026-04-04T14:32:00",
        "ignition_on_at": "2026-04-04T07:15:00",
        "ignition_off_at": null,
        "address": "Av. 18 de Julio 1234, Montevideo",
        "odometer": "84523.7",
        "horometer": "3210.5"
      }
    },
    {
      "id": "104820579315",
      "name": "Movil 15",
      "alias": null,
      "license_plate": "XYZ789",
      "imei_app": "352093089876543",
      "imei_gps": null,
      "external_id": "EXT-0015",
      "active": true,
      "status": "A",
      "device_group": "Vans",
      "last_position": null
    }
  ],
  "meta": {
    "total": 42,
    "limit": 10,
    "offset": 0
  }
}

info

last_position es null cuando el dispositivo nunca reportó datos GPS. El endpoint de listado no incluye satellites, battery_voltage ni external_power; usá el endpoint de Posición para obtener la telemetría completa.

Detalle del dispositivo

Perfil completo de un único dispositivo, incluyendo metadatos del vehículo, conductor asignado y última posición conocida con telemetría extendida.

GET/apidev/v1/fleet/devices/{id}

PermisoAPICLI_FLEET_DEVICES_READ

Límite de solicitudes30 solicitudes/min (ventana deslizante)

Caché30s

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
`id`	string	Sí	Identificador único del dispositivo

Campos de la respuesta

Todos los campos de Listar dispositivos, más:

Campo	Tipo	Descripción
`image_url`	string \| null	URL de la imagen del dispositivo/vehículo
`brand`	string \| null	Marca del vehículo (p. ej., Toyota, Ford)
`model`	string \| null	Modelo del vehículo
`year`	integer \| null	Año del modelo del vehículo
`notes`	string \| null	Notas de texto libre
`driver`	object \| null	Conductor asignado: `{ id, name }`
`last_position`	object \| null	Posición extendida con `satellites`, `battery_voltage`, `external_power` (ver Campos de posición)

Ejemplo de código

cURL
JavaScript
Python

curl -s "https://$TENANT/apidev/v1/fleet/devices/104820579301" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

const response = await fetch(
  `https://${TENANT}/apidev/v1/fleet/devices/104820579301`,
  { headers }
);
const { data } = await response.json();
console.log(`${data.name} — ${data.driver?.name ?? 'No driver'}`);

response = requests.get(
    f"https://{TENANT}/apidev/v1/fleet/devices/104820579301",
    headers=headers,
)
device = response.json()["data"]
print(f"{device['name']} — {device['brand']} {device['model']}")

Respuesta de ejemplo

{
  "success": true,
  "data": {
    "id": "104820579301",
    "name": "Movil 10",
    "alias": "M10",
    "license_plate": "ABC123",
    "imei_app": "352093081234567",
    "imei_gps": "352093089876543",
    "external_id": "EXT-0042",
    "active": true,
    "status": "A",
    "device_group": "Trucks",
    "image_url": null,
    "brand": "Toyota",
    "model": "Hilux",
    "year": 2022,
    "notes": "Assigned to the northern delivery route",
    "driver": {
      "id": "104820579455",
      "name": "Carlos Martinez"
    },
    "last_position": {
      "latitude": "-34.9011",
      "longitude": "-56.1645",
      "speed": "45.2",
      "heading": 180,
      "datetime": "2026-04-04T14:32:00",
      "last_signal_at": "2026-04-04T14:32:00",
      "ignition_on_at": "2026-04-04T07:15:00",
      "ignition_off_at": null,
      "address": "Av. 18 de Julio 1234, Montevideo",
      "odometer": "84523.7",
      "horometer": "3210.5",
      "satellites": "12",
      "battery_voltage": "12.6",
      "external_power": 1
    }
  },
  "meta": {}
}

Posición del dispositivo

Última posición GPS conocida con telemetría completa — coordenadas, velocidad, ignición, sensores y datos de señal.

GET/apidev/v1/fleet/devices/{id}/position

PermisoAPICLI_FLEET_DEVICES_READ

Límite de solicitudes30 solicitudes/min (ventana deslizante)

Caché30s

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
`id`	string	Sí	Identificador único del dispositivo

Campos de la respuesta

Campo	Tipo	Descripción
`device_id`	string	Identificador del dispositivo
`device_name`	string \| null	Nombre para mostrar del dispositivo
`latitude`	string \| null	Coordenada de latitud
`longitude`	string \| null	Coordenada de longitud
`speed`	string \| null	Velocidad en km/h
`heading`	integer \| null	Rumbo en grados (0–360). Viaja como número JSON, no como texto.
`datetime`	string \| null	Marca de tiempo del reporte de posición
`last_signal_at`	string \| null	Marca de tiempo de la última señal recibida
`ignition_on_at`	string \| null	Marca de tiempo de la última vez que se encendió la ignición
`ignition_off_at`	string \| null	Marca de tiempo de la última vez que se apagó la ignición
`address`	string \| null	Dirección por geocodificación inversa
`odometer`	string \| null	Lectura del odómetro (km)
`horometer`	string \| null	Lectura del horómetro (horas)
`satellites`	string \| null	Satélites GPS a la vista
`battery_voltage`	string \| null	Lectura de la batería interna, tal cual la informa el equipo. Algunos modelos envían el voltaje (`"12.6"`) y otros una etiqueta de nivel de carga (`"Batería media"`, `"Sin alimentación (shutdown)"`). Tratalo siempre como texto: no asumas que se puede convertir a número.
`external_power`	string \| null	Estado de la alimentación externa

Estructura plana

A diferencia del Detalle del dispositivo, que anida los datos GPS bajo last_position, este endpoint devuelve los campos de posición en el nivel raíz junto a device_id y device_name.

Ejemplo de código

cURL
JavaScript
Python

curl -s "https://$TENANT/apidev/v1/fleet/devices/104820579301/position" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

const response = await fetch(
  `https://${TENANT}/apidev/v1/fleet/devices/104820579301/position`,
  { headers }
);
const { data } = await response.json();
console.log(`${data.device_name}: ${data.latitude}, ${data.longitude} @ ${data.speed} km/h`);

response = requests.get(
    f"https://{TENANT}/apidev/v1/fleet/devices/104820579301/position",
    headers=headers,
)
pos = response.json()["data"]
print(f"{pos['device_name']}: {pos['latitude']}, {pos['longitude']} @ {pos['speed']} km/h")

Respuesta de ejemplo

{
  "success": true,
  "data": {
    "device_id": "104820579301",
    "device_name": "Movil 10",
    "latitude": "-34.9011",
    "longitude": "-56.1645",
    "speed": "62.5",
    "heading": 270,
    "datetime": "2026-04-04T14:45:12",
    "last_signal_at": "2026-04-04T14:45:12",
    "ignition_on_at": "2026-04-04T07:15:00",
    "ignition_off_at": null,
    "address": "Ruta 1 km 23, San Jose",
    "odometer": "84523.7",
    "horometer": "3210.5",
    "satellites": "12",
    "battery_voltage": "12.6",
    "external_power": 1
  },
  "meta": {}
}

Campos de posición

Referencia de los campos de posición/telemetría usados en el Detalle del dispositivo (objeto last_position) y en la Posición del dispositivo (nivel raíz):

Campo	Tipo	En lista	En detalle	En posición	Descripción
`latitude`	string \| null	✓	✓	✓	Coordenada de latitud
`longitude`	string \| null	✓	✓	✓	Coordenada de longitud
`speed`	string \| null	✓	✓	✓	Velocidad en km/h
`heading`	integer \| null	✓	✓	✓	Rumbo 0–360°, como número JSON
`datetime`	string \| null	✓	✓	✓	Marca de tiempo de la posición
`last_signal_at`	string \| null	✓	✓	✓	Marca de tiempo de la última señal
`ignition_on_at`	string \| null	✓	✓	✓	Marca de tiempo de ignición encendida
`ignition_off_at`	string \| null	✓	✓	✓	Marca de tiempo de ignición apagada
`address`	string \| null	✓	✓	✓	Dirección por geocodificación inversa
`odometer`	string \| null	✓	✓	✓	Odómetro (km)
`horometer`	string \| null	✓	✓	✓	Horómetro (horas)
`satellites`	string \| null	—	✓	✓	Satélites GPS
`battery_voltage`	string \| null	—	✓	✓	Lectura de la batería interna: voltaje o etiqueta de nivel de carga según el equipo (siempre texto)
`external_power`	string \| null	—	✓	✓	Alimentación externa
`device_id`	string	—	—	✓	ID del dispositivo (solo en posición)
`device_name`	string \| null	—	—	✓	Nombre del dispositivo (solo en posición)

Marcas de tiempo

Todas las marcas de tiempo se devuelven sin zona horaria (p. ej., "2026-04-04T14:32:00"). El valor representa la zona horaria configurada de la compañía. No agregues Z ni apliques conversión a UTC; mostralo tal cual.

Actualizar dispositivo

Actualiza la configuración de un dispositivo. Enviá solo los campos que quieras cambiar; los campos omitidos conservan su valor actual. Enviá null para limpiar un campo que admita nulos.

PUT/apidev/v1/fleet/devices/{id}

PermisoAPICLI_FLEET_DEVICES_WRITE

Límite de solicitudes30 solicitudes/min (ventana deslizante)

CachéNinguna

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
`id`	string	Sí	Identificador único del dispositivo

Cuerpo de la solicitud

Todos los campos son opcionales; incluí solo los que quieras modificar. Consultá Actualizaciones parciales para el patrón general.

Campo	Tipo	Longitud máxima	Descripción
`name`	string	200	Nombre para mostrar del dispositivo
`alias`	string	200	Alias corto
`status`	string	10	Estado del dispositivo (p. ej., `"A"`, `"I"`)
`license_plate`	string	20	Patente del vehículo
`brand`	string	100	Marca del vehículo
`model`	string	100	Modelo del vehículo
`year`	integer	—	Año del modelo del vehículo
`max_speed`	number	—	Límite de velocidad máxima (km/h)
`tank_capacity`	number	—	Capacidad del tanque de combustible en litros
`device_type_id`	string	40	Identificador del tipo de dispositivo
`provider_id`	string	40	Identificador del proveedor
`country_id`	string	40	Identificador del país
`department_id`	string	40	Identificador del departamento
`gmt_offset`	number	—	Desfase de zona horaria GMT
`imei`	string	50	Número IMEI primario
`imei2`	string	50	Número IMEI secundario
`external_id`	string	100	Identificador del sistema externo
`phone`	string	50	Número de teléfono de la SIM
`image_url`	string	500	URL de la imagen del dispositivo/vehículo
`notes`	string	2000	Notas de texto libre
`temp_low`	number	—	Umbral de alarma de temperatura baja
`temp_high`	number	—	Umbral de alarma de temperatura alta
`temp_sensor_1`	boolean	—	Habilitar el sensor de temperatura 1
`temp_sensor_2`	boolean	—	Habilitar el sensor de temperatura 2
`cut_oil`	boolean	—	Función de corte de combustible habilitada
`virtual_odometer`	boolean	—	Odómetro virtual habilitado

Ejemplo de código

cURL
JavaScript
Python

curl -s -X PUT "https://$TENANT/apidev/v1/fleet/devices/104820579301" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "license_plate": "ABC999",
    "max_speed": 120,
    "notes": "Updated route assignment"
  }'

const response = await fetch(
  `https://${TENANT}/apidev/v1/fleet/devices/104820579301`,
  {
    method: "PUT",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({
      license_plate: "ABC999",
      max_speed: 120,
      notes: "Updated route assignment",
    }),
  }
);

const { data } = await response.json();
console.log(`Updated fields: ${data.updated_fields.join(", ")}`);

response = requests.put(
    f"https://{TENANT}/apidev/v1/fleet/devices/104820579301",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "license_plate": "ABC999",
        "max_speed": 120,
        "notes": "Updated route assignment",
    },
)
print(response.json()["data"]["updated_fields"])

Respuesta de ejemplo

{
  "success": true,
  "data": {
    "id": "104820579301",
    "updated_fields": ["license_plate", "max_speed", "notes"]
  },
  "meta": {}
}

Errores

Todos los endpoints de esta página pueden devolver estos errores. Consultá Manejo de errores para la referencia completa.

Código	HTTP	Aplica a	Descripción
`VALIDATION_ERROR`	400	Listar, Actualizar	Parámetros de consulta o campos del cuerpo inválidos (p. ej., `limit` > 100, `max_speed` negativo)
`UNAUTHORIZED`	401	Todos	tenant / Authorization / X-API-Key ausente, inválido o expirado
`FORBIDDEN`	403	Todos	El usuario no tiene `APICLI_FLEET_DEVICES_READ` o `APICLI_FLEET_DEVICES_WRITE`
`NOT_FOUND`	404	Detalle, Posición, Actualizar	El ID del dispositivo no existe o no pertenece a tu tenant
`RATE_LIMITED`	429	Todos	Se superaron 30 solicitudes/min

API de Conductores — Administra los conductores asignados a los dispositivos
Telemetría — Ingesta posiciones GPS desde los dispositivos
Paginación — Parámetros estándar de paginación
Actualizaciones parciales — Cómo funcionan los endpoints PUT

Listar dispositivos​

Parámetros de consulta​

Campos de la respuesta​

Ejemplo de código​

Respuesta de ejemplo​

Detalle del dispositivo​

Parámetros de ruta​

Campos de la respuesta​

Ejemplo de código​

Respuesta de ejemplo​

Posición del dispositivo​

Parámetros de ruta​

Campos de la respuesta​

Ejemplo de código​

Respuesta de ejemplo​

Campos de posición​

Actualizar dispositivo​

Parámetros de ruta​

Cuerpo de la solicitud​

Ejemplo de código​

Respuesta de ejemplo​

Errores​

Relacionado​

Listar dispositivos

Parámetros de consulta

Campos de la respuesta

Ejemplo de código

Respuesta de ejemplo

Detalle del dispositivo

Parámetros de ruta

Campos de la respuesta

Ejemplo de código

Respuesta de ejemplo

Posición del dispositivo

Parámetros de ruta

Campos de la respuesta

Ejemplo de código

Respuesta de ejemplo

Campos de posición

Actualizar dispositivo

Parámetros de ruta

Cuerpo de la solicitud

Ejemplo de código

Respuesta de ejemplo

Errores

Relacionado