Saltar al contenido principal

Reporte de Cumplimiento de Ventana Horaria

¿Las tareas finalizadas iniciaron dentro de su ventana programada? Cantidad de inicios anticipados, en tiempo y tardíos por grupo, con la desviación promedio.

GET/apidev/v1/reports/gt/time-window-compliance
PermisoAPICLI_RPTGT_CUMPLIMIENTOVENTANA
Límite de tasa10 req/min
Caché300s
Rango máximo92 días

Resumen​

Para las tareas finalizadas que tenían una ventana programada, este reporte compara la hora de inicio real contra la ventana planificada y clasifica cada tarea como anticipada (inició antes de la ventana), en tiempo (inició dentro de la ventana) o tardía (inició después de la ventana). Los resultados se agrupan por grupo — por prestador, dispositivo, conductor, tipo de servicio, causa, geografía, fecha y más — e incluyen la desviación de inicio promedio en minutos y un porcentaje de cumplimiento en tiempo.

Solo se clasifican las tareas que tienen tanto un inicio programado válido como un fin programado válido; las tareas sin ventana programada no contribuyen a la cantidad de anticipadas/en tiempo/tardías. Elegí cómo se agrupan las filas con group_by (por defecto es prestador).

Solicitud​

Encabezados de la solicitud​

Every request to a protected endpoint requires these headers:

HeaderRequiredDescription
AuthorizationYesBearer token obtained from the Login endpoint. Format: Bearer <token>
X-API-KeyYesCompany integration key provided during onboarding. Format: gtk_xxx...
tenantYesYour assigned tenant domain (default: geotareas.com) — always send your assigned tenant
Content-TypeConditionalapplication/json — required for POST and PUT requests

Parámetros de consulta​

ParámetroTipoRequeridoPor defectoDescripción
startdatestringSí—Fecha-hora de inicio en ISO 8601 (ej. 2026-03-01T00:00:00).
enddatestringSí—Fecha-hora de fin en ISO 8601. Rango máximo de 92 días desde startdate.
group_bystringNoproviderCómo se agrupan las filas. Uno de: provider, device, driver, cause, subcause, service_type, product, origin, shift, end_code, comm_media, route, country, department, city, zone, client, telephonist, operator, resource_type, date, month, weekday, hour.
devicesstringNo—IDs de dispositivos separados por coma. Máx 500.
driversstringNo—IDs de conductores separados por coma. Máx 500.
providersstringNo—IDs de prestadores separados por coma. Máx 100.
service_typesstringNo—IDs de tipos de servicio separados por coma. Máx 100.
causesstringNo—IDs de causas separados por coma. Máx 100.
subcausesstringNo—IDs de subcausas separados por coma. Máx 100.
statusesstringNo—Códigos de estado de tarea separados por coma. Máx 100.
device_groupsstringNoTodosIds 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
originsstringNo—IDs de orígenes separados por coma. Máx 100.
route_idsstringNo—IDs de rutas separados por coma. Máx 100.
operatorsstringNo—IDs de operadores separados por coma. Máx 100.
client_idstringNo—ID de un solo cliente.
account_idstringNo—ID de una sola cuenta.
shift_idstringNo—ID de un solo turno.
limitintegerNo25Cantidad de registros por página (1–100).
offsetintegerNo0Cantidad de registros a omitir para la paginación.
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.

Ejemplos de código​

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

Respuesta​

Campos de la respuesta​

CampoTipoDescripción
group_labelstringNombre visible del grupo (ej. conductor, dispositivo, prestador).
group_idstring | nullID interno del grupo, o null cuando no se puede resolver.
totalnumberTotal de tareas finalizadas en el grupo.
antesnumberTareas que iniciaron antes de la ventana programada (anticipadas).
dentronumberTareas que iniciaron dentro de la ventana programada (en tiempo).
despuesnumberTareas que iniciaron después de la ventana programada (tardías).
desfase_promedio_minnumberDesviación de inicio promedio respecto al inicio planificado, en minutos.
cumplimiento_pctnumberPorcentaje de cumplimiento en tiempo (dentro / total * 100).

Ejemplo de respuesta​

{
  "success": true,
  "data": [
    {
      "group_label": "Carlos Martinez",
      "group_id": "10293",
      "total": 120,
      "antes": 14,
      "dentro": 95,
      "despues": 11,
      "desfase_promedio_min": -3.42,
      "cumplimiento_pct": 79.17
    }
  ],
  "meta": {
    "total": 1,
    "limit": 25,
    "offset": 0
  }
}

Errores​

CódigoHTTPDescripción
VALIDATION_ERROR400Parámetros inválidos: fechas faltantes, rango > 92 días, valores de enum inválidos.
UNAUTHORIZED401tenant / Authorization / X-API-Key faltante, inválido o expirado
FORBIDDEN403El usuario no tiene el permiso requerido.
RATE_LIMITED429Se superó el límite de 10 req/min.
INTERNAL_ERROR500Error inesperado del servidor.