Reporte de Tiempo Total Control

Distribución del tiempo total de servicio por franjas de tiempo y por agrupación.

GET/apidev/v1/reports/gt/control-total-time

PermisoAPICLI_RPTGT_CTT

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

Caché300s (5 min)

Rango máximo31 días

---

Resumen

Devuelve cómo se reparten los tiempos totales de servicio en franjas de tiempo fijas (0–30 min, 30–60 min, 1–2 h, 2–3 h y más de 3 h), con el conteo de tareas en cada franja más el promedio, agregado por una dimensión de agrupación elegida. Úsalo para entender la distribución de la duración total del servicio, no solo un promedio único.

• Agrupación — group_by elige la dimensión que representa cada fila (ver los valores más abajo)
• Base de fecha — el rango de fechas siempre filtra por la fecha de finalización de la tarea (startdate/enddate)
• Filtrado — acota los resultados por dispositivos, conductores, tipos de servicio, proveedores y otros filtros de catálogo

Las franjas no coinciden con la pantalla "Control de Tiempo Total"

La pantalla agrupa las tareas por el tiempo total del ciclo (desde la llamada hasta la finalización) en Rápido 0–60 min, Normal 60–120, Extendido 120–240, Largo 240–480 y Muy largo 480+. Este endpoint franjea, en cambio, el tiempo de trabajo, cortado en 0–30 / 30–60 min y 1–2 / 2–3 / 3+ h, así que solo la franja de 1–2 h coincide. Su avg_time_sec va en segundos, mientras que la pantalla muestra minutos. No compares una contra otra. Alinear las franjas con la pantalla está previsto y va a cambiar los campos de la 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	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 dispositivos separados por coma. Máximo 500
drivers	string	No	Todos	IDs de conductores separados por coma. Máximo 500
service_types	string	No	Todos	IDs de tipos de servicio separados por coma. Máximo 100
causes	string	No	Todas	IDs de causas separados por coma. Máximo 100
subcauses	string	No	Todas	IDs de subcausas separados por coma. Máximo 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	Todos	IDs de orígenes separados por coma. Máximo 100
providers	string	No	Todos	IDs de proveedores separados por coma. Máximo 100
route_ids	string	No	Todas	IDs de rutas separados por coma. Máximo 100
operators	string	No	Todos	IDs de operadores separados por coma. Máximo 100
client_id	string	No	—	Filtrar por un cliente específico
account_id	string	No	—	Filtrar por una cuenta específica
shift_id	string	No	—	Filtrar por un turno específico
group_by	enum	No	—	Dimensión de agrupación (ver abajo)
limit	integer	No	25	Registros por página (1–100)
offset	integer	No	0	Registros a omitir

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.

Valores de group_by

date · month · hour · weekday · department · city · zone · provider · device · device_group · driver · shift · cause · subcause · end_code · origin · telephonist · operator

---

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/control-total-time?startdate=2026-03-01T00:00:00&enddate=2026-03-31T23:59:59&group_by=device&limit=25"

JavaScript

const headers = {
  'Authorization': `Bearer ${TOKEN}`,
  'X-API-Key': APIKEY,
  'tenant': TENANT,
};

const res = await fetch(
  `https://${TENANT}/apidev/v1/reports/gt/control-total-time?startdate=2026-03-01T00:00:00&enddate=2026-03-31T23:59:59&group_by=device&limit=25`,
  { headers }
);
const data = await res.json();

Python

import requests

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "X-API-Key": APIKEY,
    "tenant": TENANT,
}

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/gt/control-total-time",
    headers=headers,
    params={
        "startdate": "2026-03-01T00:00:00",
        "enddate": "2026-03-31T23:59:59",
        "group_by": "device",
        "limit": 25,
    },
)
data = response.json()

---

Campos de la respuesta

Campo	Tipo	Descripción
group_label	string	Nombre visible del grupo
group_id	string | null	Identificador del elemento del grupo
total_tasks	number	Cantidad total de tareas
band_0_30	number	Tareas completadas en 0–30 min
band_30_60	number	Tareas completadas en 30–60 min
band_1_2hrs	number	Tareas completadas en 1–2 horas
band_2_3hrs	number	Tareas completadas en 2–3 horas
band_3_plus	number	Tareas completadas en > 3 horas
avg_time_sec	number	Tiempo total promedio en segundos

Respuesta de ejemplo

{
  "success": true,
  "data": [
    {
      "group_label": "Truck A-101",
      "group_id": "104820579301",
      "total_tasks": 47,
      "band_0_30": 5,
      "band_30_60": 14,
      "band_1_2hrs": 18,
      "band_2_3hrs": 7,
      "band_3_plus": 3,
      "avg_time_sec": 4920
    },
    {
      "group_label": "Truck B-205",
      "group_id": "104820579402",
      "total_tasks": 32,
      "band_0_30": 3,
      "band_30_60": 10,
      "band_1_2hrs": 12,
      "band_2_3hrs": 5,
      "band_3_plus": 2,
      "avg_time_sec": 5280
    }
  ],
  "meta": {
    "total": 2,
    "limit": 25,
    "offset": 0
  }
}

---

Errores

Código	HTTP	Descripción
VALIDATION_ERROR	400	Parámetros inválidos: fechas faltantes, rango > 31 días, group_by inválido
UNAUTHORIZED	401	tenant / Authorization / X-API-Key faltante, inválido o expirado
FORBIDDEN	403	El usuario carece del permiso requerido
RATE_LIMITED	429	Se superaron 10 req/min
INTERNAL_ERROR	500	Error inesperado del servidor

---

Relacionado

• Tiempo de Llegada Control
• Franjas de Demora
• Tiempo Total de Servicio
• Cantidad de Servicios
• Paginación