Saltar al contenido principal

Reporte de Demanda vs Capacidad

Saturación por turno — minutos de trabajo disponibles versus minutos dedicados a tareas, con un porcentaje de saturación y una clasificación de sobrecarga/subutilización/óptimo para cada turno de conductor.

GET/apidev/v1/reports/gt/demand-capacity
PermisoAPICLI_RPTGT_DEMANDACAPACIDAD
Límite de tasa10 req/min
Caché300s
Rango máximo92 días

Resumen​

Este reporte contrasta cuánto tiempo de trabajo tuvo disponible cada turno de conductor contra cuánto de ese tiempo se dedicó realmente a tareas. Para cada turno registrado devuelve los minutos disponibles (recortados a la ventana solicitada y descontando descansos), los minutos usados en tareas finalizadas, un porcentaje de saturación, la cantidad de tareas asignadas, un backlog estimado al cierre y una clasificación del turno como sobreutilizado (sobrecarga), subutilizado (subutilizacion) u óptimo (optimo).

A diferencia de los otros reportes GT Avanzados, los resultados se devuelven con una fila por turno de conductor — no se agrupan por una dimensión elegida. Los parámetros group_by, sla_threshold_minutes y revisit_window_days no aplican a este reporte y se ignoran si se envían. Los filtros GT estándar (dispositivo, conductor, tipo de servicio, etc.) acotan las tareas contadas dentro de cada turno.

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.
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.

group_by, sla_threshold_minutes y revisit_window_days son aceptados por el esquema de consulta compartido pero no tienen efecto en este reporte.

Ejemplos de código​

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

Respuesta​

Campos de la respuesta​

CampoTipoDescripción
conjorlabidnumberID del turno (sesión de trabajo).
conjorconidnumberID del conductor asociado al turno.
connomstringNombre del conductor (Sin nombre cuando no se puede resolver).
conjorinifchstringFecha-hora de inicio del turno.
conjorfinfchstringFecha-hora de fin del turno (recortada a la ventana solicitada).
minutos_disponiblesnumberMinutos de trabajo disponibles, descontando descansos.
minutos_usados_tareasnumberMinutos dedicados a tareas finalizadas durante el turno.
porcentaje_saturacionnumberPorcentaje de saturación (minutos usados / minutos disponibles * 100).
clasificacionstringClasificación del turno: sobrecarga (sobre), subutilizacion (sub) u optimo (óptimo).
tareas_asignadasnumberTareas finalizadas distintas asignadas durante el turno.
backlog_estimadonumberTareas estimadas aún pendientes al cierre del día del turno.

Ejemplo de respuesta​

{
  "success": true,
  "data": [
    {
      "conjorlabid": 88123,
      "conjorconid": 10293,
      "connom": "Carlos Martinez",
      "conjorinifch": "2026-03-03T08:00:00",
      "conjorfinfch": "2026-03-03T17:00:00",
      "minutos_disponibles": 480,
      "minutos_usados_tareas": 522,
      "porcentaje_saturacion": 108.75,
      "clasificacion": "sobrecarga",
      "tareas_asignadas": 14,
      "backlog_estimado": 3
    }
  ],
  "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.