Reporte de Eficiencia de Flota

KPIs operativos por grupo de vehículos — cantidad de tareas finalizadas y totales de distancia, con espacios reservados para métricas de tiempo inactivo y CO2 derivadas del GPS.

GET/apidev/v1/reports/gt/fleet-efficiency

PermisoAPICLI_RPTGT_EFICIENCIAFLOTA

Límite de tasa10 req/min

Caché300s

Rango máximo92 días

---

Resumen

Este reporte devuelve métricas operativas de flota para tareas finalizadas, agrupadas por grupo — por prestador, dispositivo, conductor, tipo de servicio, causa, geografía, fecha y más. Cada fila reporta la cantidad de tareas más los totales de distancia (suma, promedio, mínimo, máximo) durante el período seleccionado. Elegí cómo se agrupan las filas con group_by (por defecto es prestador).

Los campos idle_ratio_pct y co2_estimado_kg se devuelven como espacios reservados fijados en 0. Estas métricas se derivan del rastreo GPS en crudo y se calculan en la capa de la aplicación en lugar de en este endpoint agregado, por lo que están presentes en la forma de la respuesta por compatibilidad futura pero no se completan aquí.

---

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	Por defecto	Descripción
startdate	string	Sí	—	Fecha-hora de inicio en ISO 8601 (ej. 2026-03-01T00:00:00).
enddate	string	Sí	—	Fecha-hora de fin en ISO 8601. Rango máximo de 92 días desde startdate.
group_by	string	No	provider	Cómo se agrupan las filas. Uno de: provider, device, driver, cause, subcause, service_type, product, origin, shift, end_code, comm_media, route, country, department, city, zone, client, telephonist, operator, resource_type, date, month, weekday, hour.
devices	string	No	—	IDs de dispositivos separados por coma. Máx 500.
drivers	string	No	—	IDs de conductores separados por coma. Máx 500.
providers	string	No	—	IDs de prestadores separados por coma. Máx 100.
service_types	string	No	—	IDs de tipos de servicio separados por coma. Máx 100.
causes	string	No	—	IDs de causas separados por coma. Máx 100.
subcauses	string	No	—	IDs de subcausas separados por coma. Máx 100.
statuses	string	No	—	Códigos de estado de tarea separados por coma. Máx 100.
device_groups	string	No	Todos	Ids de tipo de dispositivo separados por comas (el catálogo device_group que expone Flota / Dispositivos). Acota las tareas a los dispositivos de esos tipos; se combina con devices como intersección. Máximo 100
origins	string	No	—	IDs de orígenes separados por coma. Máx 100.
route_ids	string	No	—	IDs de rutas separados por coma. Máx 100.
operators	string	No	—	IDs de operadores separados por coma. Máx 100.
client_id	string	No	—	ID de un solo cliente.
account_id	string	No	—	ID de una sola cuenta.
shift_id	string	No	—	ID de un solo turno.
limit	integer	No	25	Cantidad de registros por página (1–100).
offset	integer	No	0	Cantidad de registros a omitir para la paginación.

Cómo se combina device_groups con devices

device_groups se expande a todos los dispositivos de esos tipos, y si además mandás devices, se quedan solo los dispositivos que están en las dos listas. Si esa intersección queda vacía, el reporte no devuelve filas.

---

Ejemplos de código

cURL

curl -s -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  "https://$TENANT/apidev/v1/reports/gt/fleet-efficiency?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&group_by=device&limit=25"

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/reports/gt/fleet-efficiency?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&group_by=device&limit=25`,
  {
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      'tenant': TENANT,
    },
  }
);
const data = await res.json();

Python

import requests

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/gt/fleet-efficiency",
    headers={"Authorization": f"Bearer {TOKEN}", "X-API-Key": APIKEY, "tenant": TENANT},
    params={
        "startdate": "2026-03-01T00:00:00",
        "enddate": "2026-03-15T23:59:59",
        "group_by": "device",
        "limit": 25,
    },
)
data = response.json()

---

Respuesta

Campos de la respuesta

Campo	Tipo	Descripción
group_label	string	Nombre visible del grupo (ej. dispositivo, conductor, prestador).
group_id	string | null	ID interno del grupo, o null cuando no se puede resolver.
total	number	Total de tareas finalizadas en el grupo.
dist_total	number	Distancia total de las tareas del grupo.
dist_prom	number	Distancia promedio por tarea.
dist_max	number	Distancia máxima de una sola tarea.
dist_min	number	Distancia mínima distinta de cero de una sola tarea.
idle_ratio_pct	number	Espacio reservado para el ratio de tiempo inactivo derivado del GPS. Siempre 0 desde este endpoint.
co2_estimado_kg	number	Espacio reservado para el CO2 estimado derivado del GPS. Siempre 0 desde este endpoint.

Ejemplo de respuesta

{
  "success": true,
  "data": [
    {
      "group_label": "Truck A-101",
      "group_id": "55012",
      "total": 138,
      "dist_total": 4210,
      "dist_prom": 31,
      "dist_max": 92,
      "dist_min": 4,
      "idle_ratio_pct": 0,
      "co2_estimado_kg": 0
    }
  ],
  "meta": {
    "total": 1,
    "limit": 25,
    "offset": 0
  }
}

---

Errores

Código	HTTP	Descripción
VALIDATION_ERROR	400	Parámetros inválidos: fechas faltantes, rango > 92 días, valores de enum inválidos.
UNAUTHORIZED	401	tenant / Authorization / X-API-Key faltante, inválido o expirado
FORBIDDEN	403	El usuario no tiene el permiso requerido.
RATE_LIMITED	429	Se superó el límite de 10 req/min.
INTERNAL_ERROR	500	Error inesperado del servidor.

---

Relacionados

• Reporte de Demanda vs Capacidad
• Reporte de Kilómetros GT
• Reporte de Productividad
• Paginación