Reporte de Tiempo Total de Servicio

Tiempo combinado de viaje + atención por agrupación, con distancia total.

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

PermisoAPICLI_RPTGT_TTS

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

Caché300s (5 min)

Rango máximo31 días

---

Resumen

Devuelve estadísticas combinadas de tiempo de servicio (promedio, mínimo y máximo del tiempo de viaje más atención) junto con la distancia total, agregadas por una dimensión de agrupación elegida. Úsalo para ver el costo operativo completo del servicio tanto en tiempo como en kilómetros.

• Agrupación — group_by elige la dimensión que representa cada fila (ver los valores más abajo)
• Base de fecha — date_field controla si el rango filtra por fecha de creación, programada o de finalización
• Filtrado — acota los resultados por dispositivos, conductores, tipos de servicio, proveedores y otros filtros de catálogo

---

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
statuses	string	No	Todos	Códigos de estado 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
date_field	enum	No	—	Campo de fecha sobre el cual filtrar: created, scheduled, finished
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/total-service-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/total-service-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/total-service-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
avg_total_sec	number	Tiempo total de servicio promedio en segundos
min_total_sec	number	Tiempo total de servicio mínimo en segundos
max_total_sec	number	Tiempo total de servicio máximo en segundos
dist_total	number	Distancia total de todas las tareas (km)

Respuesta de ejemplo

{
  "success": true,
  "data": [
    {
      "group_label": "Truck A-101",
      "group_id": "104820579301",
      "total_tasks": 47,
      "avg_total_sec": 4500,
      "min_total_sec": 1200,
      "max_total_sec": 10800,
      "dist_total": 892.3
    },
    {
      "group_label": "Truck B-205",
      "group_id": "104820579402",
      "total_tasks": 32,
      "avg_total_sec": 5100,
      "min_total_sec": 900,
      "max_total_sec": 12600,
      "dist_total": 614.7
    }
  ],
  "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
• Tiempo de Atención
• Tiempo Completo de Servicio
• Kilómetros de Tarea
• Paginación