Reporte de Detenido

Análisis del tiempo de inactividad del vehículo — inactividad con motor encendido y paradas con motor apagado, con contexto de geocercas y POIs.

GET/apidev/v1/reports/avl/idle

PermisoAPICLI_RPTAVL_DETENIDO

Límite de solicitudes10 req/min (ventana deslizante)

Caché300s (5 min)

Rango máximo31 días

Resumen

Desglose detallado de cada período en que un vehículo estuvo detenido, clasificado por estado de la ignición.

Filtrado por ignición — ignition aísla la inactividad con motor encendido (desperdicio de combustible) de las paradas con motor apagado
Contexto de geocerca — geofences restringe a zonas específicas
Umbral de duración — idle_min excluye paradas breves
Evidencia de cada parada — si el motor estaba encendido, qué la terminó y qué tan firme fue la señal (engine, ended_by, points, max_silence_seconds, radius_m, reappeared_far)

Solicitud

Encabezados de la solicitud

Every request to a protected endpoint requires these headers:

Header	Required	Description
`Authorization`	Yes	Bearer token obtained from the Login endpoint. Format: `Bearer <token>`
`X-API-Key`	Yes	Company integration key provided during onboarding. Format: `gtk_xxx...`
`tenant`	Yes	Your assigned tenant domain (default: `geotareas.com`) — always send your assigned tenant
`Content-Type`	Conditional	`application/json` — required for `POST` and `PUT` requests

Parámetros de consulta

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`startdate`	string	Sí	—	Fecha-hora de inicio en ISO 8601
`enddate`	string	Sí	—	Fecha-hora de fin en ISO 8601. Rango máximo 31 días
`devices`	string	No	Todos los visibles	IDs de dispositivo separados por coma. Máximo 500
`geofences`	string	No	Todas	IDs de geocerca separados por coma. Máximo 500
`idle_min`	integer	No	`0`	Tiempo mínimo de inactividad en minutos
`ignition`	enum	No	—	Filtra por estado del motor: `on` (solo con motor encendido), `off` (motor apagado — por compatibilidad incluye también las paradas sin dato de motor), `unknown` (solo las paradas sin dato de motor). Omitido = todas las detenciones
`subtotals`	boolean	No	`false`	Se ignora. Se sigue aceptando para que las llamadas existentes no fallen, pero el endpoint nunca devuelve filas de subtotal ni de total general
`limit`	integer	No	`25`	Registros por página (`1`–`100`)
`offset`	integer	No	`0`	Registros a omitir

Sin filas de resumen

Cada fila de data es una parada. Nunca vienen filas de subtotal ni de total general (tampoco con subtotals=true), así que podés sumar idle_min por tu cuenta sin contar dos veces. meta.total cuenta paradas.

Ejemplos de código

cURL
JavaScript
Python

curl -s "https://$TENANT/apidev/v1/reports/avl/idle?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&limit=50&ignition=on" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

const response = await fetch(
  `https://${TENANT}/apidev/v1/reports/avl/idle?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&limit=50&ignition=on`,
  { headers }
);
const { data, meta } = await response.json();

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/avl/idle",
    headers=headers,
    params={
        "startdate": "2026-03-01T00:00:00",
        "enddate": "2026-03-15T23:59:59",
        "limit": 50,
        "ignition": "on",
    },
)
result = response.json()

Campos de la respuesta

Campo	Tipo	Descripción
`device_name`	string	Nombre visible del vehículo/dispositivo
`person_name`	string	Conductor asignado al momento del evento
`datetime_start`	string \| null	Marca de tiempo de cuando comenzó el período de inactividad
`datetime_end`	string \| null	Marca de tiempo de cuando terminó el período de inactividad. `null` si la parada está abierta (`open`)
`idle_min`	number	Duración del período de inactividad en minutos
`type`	string	Estado de la ignición durante la detención: `Apagada` / `Encendida`
`address`	string	Dirección geocodificada inversa de la ubicación de inactividad
`geofences`	string	Nombres de las geocercas dentro de las cuales cae la ubicación de inactividad. Cadena vacía si no hay
`pois`	string	Puntos de interés cercanos. Cadena vacía si no hay
`engine`	string \| null	Estado del motor durante la parada: `off` (apagado), `on` (encendido) o `unknown` (el equipo no mandó dato de motor)
`ended_by`	string \| null	Qué terminó la parada: `movement` (el vehículo arrancó), `engine_on` (encendió el motor; si no se movió, empieza otra parada en el mismo lugar con el motor encendido), `engine_off` (apagó el motor sin moverse; empieza otra parada en el mismo lugar con el motor apagado), `drift` (se alejó del lugar donde se detuvo). En una parada abierta: `day_end` = parada de un día anterior que seguía al terminar ese día (el día siguiente trae la suya); `null` = parada de hoy, el vehículo sigue detenido
`open`	boolean \| null	`true` si la parada no terminó dentro de su día (ver `ended_by`); en ese caso `datetime_end` viene `null`
`points`	integer \| null	Posiciones quietas que sostienen la parada
`max_silence_seconds`	integer \| null	Mayor tiempo sin reportar durante la parada (incluido el previo al cierre), en segundos
`radius_m`	integer \| null	Distancia máxima desde el lugar donde se detuvo, en metros
`reappeared_far`	boolean \| null	`true` si el equipo se quedó sin señal y reapareció lejos: la parada se cerró en el último reporte quieto y el tiempo sin señal no se contó

Paradas todavía no reprocesadas

Los campos de motor y de evidencia (de engine a reappeared_far) salen del motor de detección actual. Las paradas calculadas antes y todavía no reprocesadas los traen todos en null; el resto de sus campos no cambia. Ninguna parada cruza la medianoche: cada una se informa en el día en que empezó.

Ejemplo de respuesta

{
  "success": true,
  "data": [
    {
      "device_name": "Van B-205",
      "person_name": "Carlos Medina",
      "datetime_start": "2026-03-10T11:05:00",
      "datetime_end": "2026-03-10T11:47:00",
      "idle_min": 42,
      "type": "Encendida",
      "address": "Av. 18 de Julio 1234, Montevideo",
      "geofences": "Client Zone A",
      "pois": "",
      "engine": "on",
      "ended_by": "movement",
      "open": false,
      "points": 9,
      "max_silence_seconds": 300,
      "radius_m": 12,
      "reappeared_far": false
    },
    {
      "device_name": "Truck A-101",
      "person_name": "",
      "datetime_start": "2026-03-07T16:18:14",
      "datetime_end": "2026-03-07T21:18:12",
      "idle_min": 300,
      "type": "Apagada",
      "address": "Camino Carrasco 4500, Montevideo",
      "geofences": "",
      "pois": "Depósito Central",
      "engine": "off",
      "ended_by": "engine_on",
      "open": false,
      "points": 3,
      "max_silence_seconds": 4250,
      "radius_m": 15,
      "reappeared_far": false
    }
  ],
  "meta": {
    "total": 38,
    "limit": 50,
    "offset": 0
  }
}

Errores

Código	HTTP	Descripción
`INVALID_DATE_RANGE`	400	El rango de fechas supera el máximo de 31 días, el fin es anterior al inicio, o fechas no ISO
`VALIDATION_ERROR`	400	Parámetros inválidos: faltan fechas, valor de `ignition` inválido
`UNAUTHORIZED`	401	tenant / Authorization / X-API-Key faltante, inválido o expirado
`FORBIDDEN`	403	El usuario carece del permiso `APICLI_RPTAVL_DETENIDO`
`RATE_LIMITED`	429	Se superaron las 10 req/min
`INTERNAL_ERROR`	500	Error inesperado del servidor

Reporte de Ignición — Horas de motor y seguimiento del horómetro
Reporte de Geocerca — Eventos de entrada/salida por zona
Paginación — Parámetros de paginación estándar

Resumen​

Solicitud​

Encabezados de la solicitud​

Parámetros de consulta​

Ejemplos de código​

Campos de la respuesta​

Ejemplo de respuesta​

Errores​

Relacionado​