Reporte de Rendimiento del Vehículo

Análisis de rendimiento de combustible — distancia, consumo de combustible, costo y eficiencia por vehículo o conductor.

GET/apidev/v1/reports/avl/vehicle-performance

PermisoAPICLI_RPTAVL_RENDIMIENTO

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

Caché300s (5 min)

Rango máximo31 días

---

Resumen

Combina distancia recorrida, consumo de combustible, costo y eficiencia en un solo reporte. Los resultados pueden agruparse por vehículo o por vehículo + conductor.

• Segmentación por conductor — el parámetro drivers filtra por conductores específicos
• Agrupación por vehículo + conductor — group_by_device=true agrupa por vehículo y conductor en lugar de solo por vehículo
• Métrica de eficiencia — rendimiento promedio (kms por litro) para comparación de referencia

Basado en recargas de combustible

El rendimiento se calcula a partir de las recargas de combustible registradas. Se necesitan al menos 2 recargas por vehículo dentro del rango de fechas para producir métricas — con una sola recarga los valores devuelven 0.

---

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
drivers	string	No	Todos	IDs de conductor separados por coma. Máximo 500
group_by_device	boolean	No	false	Agrupa por vehículo + conductor en lugar de solo por vehículo
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/vehicle-performance?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&limit=50&group_by_device=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

JavaScript

const params = new URLSearchParams({
  startdate: "2026-03-01T00:00:00",
  enddate: "2026-03-15T23:59:59",
  limit: "50",
  group_by_device: "true",
});

const response = await fetch(
  `https://${TENANT}/apidev/v1/reports/avl/vehicle-performance?${params}`,
  { headers }
);

const { data, meta } = await response.json();
for (const row of data) {
  console.log(`${row.device_name}: ${row.kms_traveled} km — ${row.fuel_liters} L — ${row.avg_km_per_liter} km/L`);
}

Python

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/avl/vehicle-performance",
    headers=headers,
    params={
        "startdate": "2026-03-01T00:00:00",
        "enddate": "2026-03-15T23:59:59",
        "limit": 50,
        "group_by_device": True,
    },
)

result = response.json()
for row in result["data"]:
    print(f"{row['device_name']}: {row['kms_traveled']} km — {row['avg_km_per_liter']} km/L")

---

Campos de la respuesta

Campo	Tipo	Descripción
device_name	string	Nombre visible del vehículo/dispositivo
driver_name	string	Nombre del conductor (relevante con group_by_device=true)
kms_traveled	number	Kilómetros recorridos entre recargas
fuel_liters	number	Litros de combustible cargados
fuel_cost	number	Importe total de las recargas
avg_km_per_liter	number	Rendimiento promedio (kms por litro)

tip

Las métricas se calculan a partir de las recargas de combustible registradas en el sistema. Si un vehículo tiene menos de 2 recargas dentro del rango, sus valores devuelven 0.

Ejemplo de respuesta

{
  "success": true,
  "data": [
    {
      "device_name": "Truck A-101",
      "driver_name": "Carlos Martinez",
      "kms_traveled": 267.7,
      "fuel_liters": 32.12,
      "fuel_cost": 48.18,
      "avg_km_per_liter": 8.33
    },
    {
      "device_name": "Van B-205",
      "driver_name": "Maria Lopez",
      "kms_traveled": 142.3,
      "fuel_liters": 11.38,
      "fuel_cost": 17.07,
      "avg_km_per_liter": 12.5
    }
  ],
  "meta": {
    "total": 84,
    "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, limit > 100
UNAUTHORIZED	401	tenant / Authorization / X-API-Key faltante, inválido o expirado
FORBIDDEN	403	El usuario carece del permiso APICLI_RPTAVL_RENDIMIENTO
RATE_LIMITED	429	Se superaron las 10 req/min
INTERNAL_ERROR	500	Error inesperado del servidor

---

Relacionado

• Reporte de Kilómetros — Agregados de distancia y consumo
• Reporte de Ignición — Seguimiento de horas de motor
• API de Conductores — Obtené IDs de conductor para filtrar
• Paginación — Parámetros de paginación estándar