Reporte de Proactividad por Dispositivo

Cumplimiento de tareas a nivel de dispositivo para una fecha de ejecución específica — resumen + desglose por dispositivo.

GET/apidev/v1/reports/gt/proactivity-device

PermisoAPICLI_RPTGT_PROACTIVIDAD_DISP

Límite de solicitudes10 req/min

Caché60s (1 min)

Resumen

Devuelve el cumplimiento de tareas de una única fecha de ejecución, agrupado por tipo de móvil — lo mismo que muestra la pantalla de Proactividad. Cada grupo trae su propia fila de subtotales (summary) y su propio desglose por vehículo (devices): conductor, jornada, cantidades de tareas, tiempo sin asignar, ocupación y promedios. Establecé realtime=true para obtener cifras en vivo, y filtrá por dispositivos, conductores, tipos de servicio, causas, geografía o geocercas.

Cambio de contrato — 2026-08-17

data ahora es un arreglo de grupos por tipo de móvil. Antes era un único objeto { summary, devices } armado con el primer grupo solamente, que descartaba en silencio todos los demás tipos de móvil (una flota con autos y motos recibía solo autos). Ver Respuesta.

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
`execution_date`	string	Sí	—	Fecha en ISO 8601 (ej. `2026-03-19`). Una sola fecha, no un rango.
`realtime`	boolean	No	—	Incluir datos en tiempo real.
`devices`	string	No	—	IDs de dispositivos separados por comas. Máximo 500.
`drivers`	string	No	—	IDs de conductores separados por comas. Máximo 500.
`service_types`	string	No	—	IDs de tipos de servicio separados por comas. Máximo 100.
`causes`	string	No	—	IDs de causas separados por comas. Máximo 100.
`subcauses`	string	No	—	IDs de subcausas separados por comas. Máximo 100.
`countries`	string	No	—	IDs de países separados por comas. Máximo 50.
`departments`	string	No	—	IDs de departamentos separados por comas. Máximo 50.
`geofences`	string	No	—	IDs de geocercas separados por comas. Máximo 100.
`limit`	integer	No	`25`	Cantidad de grupos de tipo de móvil por página (`1`–`100`).
`offset`	integer	No	`0`	Cantidad de grupos de tipo de móvil a omitir para la paginación.

La paginación aplica a los grupos, no a los dispositivos

limit / offset paginan los grupos de tipo de móvil, y meta.total es la cantidad total de grupos. Cada grupo viaja siempre con todos sus dispositivos — de lo contrario, un grupo con subtotales pero sin vehículos con tareas volvería a desaparecer de la respuesta.

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/proactivity-device?execution_date=2026-03-19&limit=25"

const res = await fetch(
  `https://${TENANT}/apidev/v1/reports/gt/proactivity-device?execution_date=2026-03-19&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/proactivity-device",
    headers={"Authorization": f"Bearer {TOKEN}", "X-API-Key": APIKEY, "tenant": TENANT},
    params={"execution_date": "2026-03-19", "limit": 25},
)
data = response.json()

Respuesta

data es un arreglo de grupos por tipo de móvil. Un elemento por tipo de móvil (la agrupación "Tipo de móvil" del reporte web), cada uno con su fila de subtotales y sus filas por vehículo.

Todas las duraciones vienen en minutos (*_min) y además ya formateadas para mostrar (*_text, por ejemplo "1h 35m"). Un *_text vacío significa que ese valor no se pudo calcular para el grupo.

Campos del grupo

Campo	Tipo	Descripción
`device_type`	string	Nombre del tipo de móvil / grupo de proactividad.
`device_type_id`	string \| null	Identificador del tipo de móvil.
`summary`	object	Subtotales del grupo — ver abajo.
`devices`	array	Una fila por vehículo del grupo — ver abajo.

Campos del resumen

Campo	Tipo	Descripción
`device_type`	string	Nombre del tipo de móvil (igual que el del grupo).
`device_type_id`	string \| null	Identificador del tipo de móvil.
`total_devices`	number	Dispositivos activos del grupo.
`devices_free`	number	Dispositivos activos sin tarea en curso.
`total_tasks`	number	Suma de conveniencia: `tasks_pending + tasks_finished + tasks_in_progress + tasks_cancelled`. No es una columna del reporte web.
`tasks_finished`	number	Tareas finalizadas.
`tasks_pending`	number	Tareas sin asignar (no programadas).
`tasks_pending_scheduled`	number	Tareas sin asignar programadas a futuro.
`tasks_in_progress`	number	Tareas en progreso.
`tasks_cancelled`	number	Tareas canceladas.
`tasks_rejected`	number	Tareas rechazadas por los conductores.
`max_time_unassigned_min` / `_text`	number / string	Mayor tiempo que un vehículo estuvo sin asignación.
`compliance_pct`	number	Ocupación: porcentaje de la jornada dedicado a tareas.
`avg_arrival_last_hour_min` / `_text`	number / string	Promedio de llegada de la última hora.
`avg_arrival_day_min` / `_text`	number / string	Promedio de llegada del día.
`avg_assignment_min` / `_text`	number / string	Promedio de tiempo hasta asignar una tarea.
`avg_arrival_min` / `_text`	number / string	Promedio desde la aceptación hasta el arribo.
`avg_on_task_min` / `_text`	number / string	Promedio de tiempo en tarea.
`avg_km`	number	Promedio de kilómetros por tarea finalizada.

Campos del arreglo Devices

Campo	Tipo	Descripción
`device_id`	string \| null	Identificador del dispositivo.
`device_name`	string	Nombre del vehículo.
`driver_id`	string \| null	Identificador del conductor.
`driver_name`	string	Nombre del conductor.
`active`	boolean	El vehículo tiene jornada abierta en la fecha de ejecución.
`worked_min` / `worked_text`	number / string	Duración de la jornada del conductor.
`total_tasks`	number	`tasks_finished + tasks_in_progress + tasks_cancelled + tasks_rejected`.
`tasks_finished`	number	Tareas finalizadas.
`tasks_in_progress`	number	Tareas en progreso.
`tasks_cancelled`	number	Tareas canceladas.
`tasks_rejected`	number	Tareas rechazadas por el conductor.
`time_unassigned_min` / `_text`	number / string	Mayor lapso sin asignación.
`compliance_pct`	number	Ocupación de la jornada de este vehículo.
`avg_arrival_day_min` / `_text`	number / string	Promedio de llegada del día.
`avg_assignment_min` / `_text`	number / string	Promedio de tiempo hasta asignar.
`avg_arrival_min` / `_text`	number / string	Promedio desde la aceptación hasta el arribo.
`avg_on_task_min` / `_text`	number / string	Promedio de tiempo en tarea.
`last_signal_min` / `_text`	number / string	Tiempo desde la última señal recibida.
`last_gps_min` / `_text`	number / string	Tiempo desde la última posición GPS válida.
`total_km`	number	Kilómetros recorridos en tareas finalizadas.
`avg_km`	number	Promedio de kilómetros por tarea finalizada.
`time_since_last_task_min` / `_text`	number / string	Tiempo desde la última tarea finalizada (`0` mientras haya una en curso).
`avg_arrival_last_hour_min` / `_text`	number / string	Promedio de llegada de la última hora.

tasks_pending se eliminó de las filas por dispositivo

Se derivaba por resta y siempre daba exactamente la cantidad de tareas rechazadas. "Sin asignar" es un concepto del grupo y vive en summary.tasks_pending; el rechazo por vehículo ahora se publica como tasks_rejected.

Ejemplo de respuesta

{
  "success": true,
  "data": [
    {
      "device_type": "Autos",
      "device_type_id": "104820570001",
      "summary": {
        "device_type": "Autos",
        "device_type_id": "104820570001",
        "total_devices": 5,
        "devices_free": 2,
        "total_tasks": 47,
        "tasks_finished": 35,
        "tasks_pending": 8,
        "tasks_pending_scheduled": 2,
        "tasks_in_progress": 3,
        "tasks_cancelled": 1,
        "tasks_rejected": 0,
        "max_time_unassigned_min": 95,
        "max_time_unassigned_text": "1h 35m",
        "compliance_pct": 74,
        "avg_arrival_last_hour_min": 18,
        "avg_arrival_last_hour_text": "18m",
        "avg_arrival_day_min": 22,
        "avg_arrival_day_text": "22m",
        "avg_assignment_min": 4,
        "avg_assignment_text": "4m",
        "avg_arrival_min": 19,
        "avg_arrival_text": "19m",
        "avg_on_task_min": 41,
        "avg_on_task_text": "41m",
        "avg_km": 12.4
      },
      "devices": [
        {
          "device_id": "104820579301",
          "device_name": "Truck A-101",
          "driver_id": "104820561122",
          "driver_name": "Carlos Martinez",
          "active": true,
          "worked_min": 480,
          "worked_text": "8h",
          "total_tasks": 12,
          "tasks_finished": 10,
          "tasks_in_progress": 1,
          "tasks_cancelled": 1,
          "tasks_rejected": 0,
          "time_unassigned_min": 35,
          "time_unassigned_text": "35m",
          "compliance_pct": 83,
          "avg_arrival_day_min": 20,
          "avg_arrival_day_text": "20m",
          "avg_assignment_min": 3,
          "avg_assignment_text": "3m",
          "avg_arrival_min": 17,
          "avg_arrival_text": "17m",
          "avg_on_task_min": 39,
          "avg_on_task_text": "39m",
          "last_signal_min": 2,
          "last_signal_text": "2m",
          "last_gps_min": 2,
          "last_gps_text": "2m",
          "total_km": 124.5,
          "avg_km": 12.45,
          "time_since_last_task_min": 0,
          "time_since_last_task_text": "",
          "avg_arrival_last_hour_min": 15,
          "avg_arrival_last_hour_text": "15m"
        }
      ]
    },
    {
      "device_type": "Motos",
      "device_type_id": "104820570002",
      "summary": {
        "device_type": "Motos",
        "device_type_id": "104820570002",
        "total_devices": 2,
        "devices_free": 1,
        "total_tasks": 9,
        "tasks_finished": 7,
        "tasks_pending": 1,
        "tasks_pending_scheduled": 0,
        "tasks_in_progress": 1,
        "tasks_cancelled": 0,
        "tasks_rejected": 0,
        "max_time_unassigned_min": 40,
        "max_time_unassigned_text": "40m",
        "compliance_pct": 61,
        "avg_arrival_last_hour_min": 11,
        "avg_arrival_last_hour_text": "11m",
        "avg_arrival_day_min": 13,
        "avg_arrival_day_text": "13m",
        "avg_assignment_min": 2,
        "avg_assignment_text": "2m",
        "avg_arrival_min": 12,
        "avg_arrival_text": "12m",
        "avg_on_task_min": 28,
        "avg_on_task_text": "28m",
        "avg_km": 6.2
      },
      "devices": []
    }
  ],
  "meta": {
    "total": 2,
    "limit": 25,
    "offset": 0
  }
}

Errores

Código	HTTP	Descripción
`VALIDATION_ERROR`	400	Parámetros inválidos: falta `execution_date`, 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 del grupo​

Campos del resumen​

Campos del arreglo Devices​

Ejemplo de respuesta​

Errores​

Relacionados​