Saltar al contenido principal

Reporte de Benchmark Temporal

Compará el volumen de tareas del período seleccionado contra el período inmediatamente anterior, con la variación absoluta y porcentual por grupo.

GET/apidev/v1/reports/gt/benchmark
PermisoAPICLI_RPTGT_BENCHMARK
Límite de tasa10 req/min
Caché300s
Rango máximo92 días

Resumen​

Este reporte mide cómo cambió el volumen de tareas finalizadas entre el período que seleccionás y el período justo anterior. Para cada grupo — prestador, dispositivo, conductor, tipo de servicio, causa, geografía, fecha y más — devuelve la cantidad del período actual, la cantidad del período anterior, la variación absoluta y la variación porcentual. Usalo para detectar tendencias, crecimiento o caídas entre períodos consecutivos.

El período anterior se calcula automáticamente del lado del servidor: es una ventana de la misma duración que tu rango seleccionado, que termina justo donde empieza tu rango. Por ejemplo, una solicitud del 1 al 15 de marzo se compara contra el 14 al 28 de febrero (una ventana de 15 días inmediatamente anterior). No pasás el período anterior de forma explícita. 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. El período anterior (misma duración, inmediatamente antes de startdate) se calcula automáticamente.
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/benchmark?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&group_by=service_type&limit=25"

Respuesta​

Campos de la respuesta​

CampoTipoDescripción
group_labelstringNombre visible del grupo (ej. tipo de servicio, conductor, prestador).
group_idstring | nullID interno del grupo, o null cuando no se puede resolver.
totalnumberCantidad de tareas finalizadas del período actual (igual que valor_actual).
valor_actualnumberTareas finalizadas en el período seleccionado.
valor_anteriornumberTareas finalizadas en el período anterior (misma duración, inmediatamente antes).
deltanumberVariación absoluta (valor_actual - valor_anterior).
delta_pctnumberVariación porcentual respecto al período anterior. Cuando el período anterior es 0, vale 100 si el período actual tiene tareas, de lo contrario 0.

Ejemplo de respuesta​

{
  "success": true,
  "data": [
    {
      "group_label": "Maintenance",
      "group_id": "42",
      "total": 320,
      "valor_actual": 320,
      "valor_anterior": 268,
      "delta": 52,
      "delta_pct": 19.4
    }
  ],
  "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.