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
• Subtotales — subtotals=true para resúmenes agregados

---

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 de la ignición: on (solo con ignición encendida), off (solo apagada). Omitido = todas las detenciones
subtotals	boolean	No	false	Incluye filas de subtotal
limit	integer	No	25	Registros por página (1–100)
offset	integer	No	0	Registros a omitir

---

Ejemplos de código

cURL

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"

JavaScript

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();

Python

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
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

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": ""
    },
    {
      "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"
    }
  ],
  "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

---

Relacionado

• 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