Reporte de Tiempo de Llegada Control

Distribución del tiempo de llegada por franjas de tiempo y por agrupación.

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

PermisoAPICLI_RPTGT_CTLL

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 de llegada en franjas de tiempo fijas (0–15, 15–30, 30–45, 45–60 y más de 60 minutos), con el conteo de tareas en cada franja más el promedio, agregado por una dimensión de agrupación elegida. Úsalo para ver la forma de tus tiempos de respuesta, no solo el promedio.

• 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

Todavía no coincide con la pantalla "Control Tiempo Prometido de Llegada"

La pantalla del mismo nombre mide otra cosa: compara el tiempo real de llegada de cada tarea contra el tiempo que se le prometió al cliente e informa cuántas se cumplieron, cuántas se excedieron y el porcentaje de cumplimiento. Este endpoint devuelve, en cambio, franjas de tiempo de llegada, y su avg_time_sec es el promedio de viaje en segundos (la pantalla lo muestra en minutos). No compares una contra otra. Alinear este endpoint 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-arrival-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-arrival-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-arrival-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_15	number	Tareas con tiempo de llegada de 0–15 min
band_15_30	number	Tareas con tiempo de llegada de 15–30 min
band_30_45	number	Tareas con tiempo de llegada de 30–45 min
band_45_60	number	Tareas con tiempo de llegada de 45–60 min
band_60_plus	number	Tareas con tiempo de llegada > 60 min
avg_time_sec	number	Tiempo de llegada promedio en segundos

Respuesta de ejemplo

{
  "success": true,
  "data": [
    {
      "group_label": "Truck A-101",
      "group_id": "104820579301",
      "total_tasks": 47,
      "band_0_15": 18,
      "band_15_30": 12,
      "band_30_45": 8,
      "band_45_60": 5,
      "band_60_plus": 4,
      "avg_time_sec": 1560
    },
    {
      "group_label": "Truck B-205",
      "group_id": "104820579402",
      "total_tasks": 32,
      "band_0_15": 10,
      "band_15_30": 9,
      "band_30_45": 6,
      "band_45_60": 4,
      "band_60_plus": 3,
      "avg_time_sec": 1740
    }
  ],
  "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 Total Control
• Franjas de Demora
• Cantidad de Servicios
• Paginación