Reporte de Productividad

Métricas de productividad de tareas por vehículo/conductor — cantidades de tareas, horas, kilómetros y ocupación.

GET/apidev/v1/reports/gt/productivity

PermisoAPICLI_RPTGT_PRODUCTIVIDAD

Límite de solicitudes10 req/min

Caché300s

Rango máximo31 días

Resumen

Devuelve métricas de productividad agregadas por vehículo o conductor dentro de un rango de fechas — cantidades de tareas (programadas, no programadas, total), horas de tareas y de turno, kilómetros (trabajados, ideales, de turno), tiempo promedio de llegada y tasa de ocupación. Usá group_by_person=true para agregar por conductor en lugar de por dispositivo, y acotá los resultados con filtros de dispositivo, conductor, tipo de dispositivo o tipo de servicio.

Hay tres métricas que hoy no son confiables

task_hours, shift_hours y avg_arrival_time vuelven en null justo cuando traen un valor real, y en 0 cuando la métrica es genuinamente cero. Leé Campos de la respuesta antes de construir sobre ellas.

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 31 días desde `startdate`.
`devices`	string	No	—	IDs de dispositivos separados por comas. Máximo 500.
`drivers`	string	No	—	IDs de conductores separados por comas. Máximo 500.
`device_groups`	string	No	—	Ids de tipo de dispositivo separados por comas (el catálogo `device_group` que expone Flota / Dispositivos). Máximo 100.
`service_types`	string	No	—	IDs de tipos de servicio separados por comas. Máximo 100.
`group_by_person`	boolean	No	`false`	Agrupar resultados por conductor en lugar de por dispositivo.
`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.

Ejemplos de código

cURL
JavaScript
Python

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

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

import requests

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

Respuesta

Campos de la respuesta

Todos los campos de abajo vienen siempre como clave. Lo que cambia entre filas es si traen valor o no — ver las dos notas que siguen a la tabla.

Campo	Tipo	Descripción
`service_type`	string	Nombre del tipo de servicio. Hoy siempre llega vacío — ver la nota más abajo.
`driver_name`	string	Nombre del conductor. Se completa solo con `group_by_person=true`; en el resto de los casos llega vacío.
`device_name`	string	Nombre del vehículo. Se completa solo con `group_by_person=false` (el valor predeterminado); en el resto de los casos llega vacío.
`unscheduled_tasks`	number	Cantidad de tareas no programadas.
`scheduled_tasks`	number	Cantidad de tareas programadas.
`total_tasks`	number	Cantidad total de tareas.
`task_hours`	number \| null	Tiempo dedicado a tareas. Llega `null` toda vez que el valor no es cero — ver la nota más abajo.
`shift_hours`	number \| null	Tiempo total de jornada. Llega `null` toda vez que el valor no es cero — ver la nota más abajo.
`kms_worked`	number	Kilómetros durante las tareas.
`kms_ideal`	number	Kilómetros ideales/planificados (la distancia ruteada).
`kms_shift`	number	Total de kilómetros de la jornada.
`avg_arrival_time`	number \| null	Tiempo promedio de llegada a las tareas no programadas. Llega `null` toda vez que el valor no es cero — ver la nota más abajo.
`occupancy`	number	Porcentaje de ocupación (tiempo de tareas sobre tiempo de jornada).

task_hours, shift_hours y avg_arrival_time todavía no son utilizables

Son los tres únicos campos nulables del reporte, y su null no significa "sin datos". El patrón está invertido:

la métrica vale cero → llega 0
la métrica tiene cualquier valor real → llega null

Es decir: una fila que sí tuvo horas trabajadas informa null, y una fila sin actividad informa 0. No interpretes el null como jornada vacía ni sumes estos tres campos: los totales quedarían mal en las dos direcciones.

Hasta que esto se corrija, calculá lo que necesites con los campos confiables: occupancy ya expresa el tiempo de tareas sobre el de jornada en porcentaje, y total_tasks / kms_worked / kms_shift traen números reales.

service_type siempre llega vacío

El reporte de base agrupa únicamente por vehículo o por conductor, así que nunca arrastra el nombre del tipo de servicio: el campo está por compatibilidad de forma, pero lee "" en todas las filas. El filtro service_types sí funciona (acota qué tareas se cuentan); lo único que no vuelve es la etiqueta.

Ejemplo de respuesta

Modo predeterminado (sin group_by_person), con lo que producción devuelve hoy:

{
  "success": true,
  "data": [
    {
      "service_type": "",
      "driver_name": "",
      "device_name": "Truck A-101",
      "unscheduled_tasks": 3,
      "scheduled_tasks": 12,
      "total_tasks": 15,
      "task_hours": null,
      "shift_hours": null,
      "kms_worked": 142.3,
      "kms_ideal": 135.0,
      "kms_shift": 180.0,
      "avg_arrival_time": null,
      "occupancy": 81
    },
    {
      "service_type": "",
      "driver_name": "",
      "device_name": "Van B-205",
      "unscheduled_tasks": 0,
      "scheduled_tasks": 0,
      "total_tasks": 0,
      "task_hours": 0,
      "shift_hours": 0,
      "kms_worked": 0,
      "kms_ideal": 0,
      "kms_shift": 0,
      "avg_arrival_time": 0,
      "occupancy": 0
    }
  ],
  "meta": {
    "total": 2,
    "limit": 25,
    "offset": 0
  }
}

Con `group_by_person=true`

Las filas se agregan por conductor: driver_name trae el nombre y device_name pasa a llegar vacío.

{
  "service_type": "",
  "driver_name": "Carlos Martinez",
  "device_name": "",
  "unscheduled_tasks": 5,
  "scheduled_tasks": 18,
  "total_tasks": 23,
  "task_hours": null,
  "shift_hours": null,
  "kms_worked": 210.6,
  "kms_ideal": 198.0,
  "kms_shift": 265.0,
  "avg_arrival_time": null,
  "occupancy": 74
}

Errores

Código	HTTP	Descripción
`VALIDATION_ERROR`	400	Parámetros inválidos: faltan fechas, rango > 31 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 superaron las 10 req/min.
`INTERNAL_ERROR`	500	Error inesperado del servidor.

Resumen​

Solicitud​

Encabezados de la solicitud​

Parámetros de consulta​

Ejemplos de código​

Respuesta​

Campos de la respuesta​

Ejemplo de respuesta​

Con group_by_person=true​

Errores​

Relacionados​