Saltar al contenido principal

Reporte de Detalle de Actividad

Actividad de turnos del personal con seguimiento de cumplimiento, contexto de geocerca y desgloses de sub-turnos.

GET/apidev/v1/reports/cpm/activity-detail
PermisoAPICLI_RPTCPM_DETALLE
Límite de solicitudes10 req/min
Caché300s
Rango máximo31 días

Resumen​

Devuelve los registros de turnos del personal durante el período seleccionado, cada uno enriquecido con el estado de cumplimiento, las direcciones de inicio/fin y la geocerca donde el turno comenzó y terminó. Úsalo para auditar las horas trabajadas y de descanso, los kilómetros recorridos y los registros QRA/QRX/QRV/QTP.

  • Solo cumplimiento — compliance_only=true devuelve únicamente los registros que incumplieron una regla
  • Vista detallada — detailed=true agrega el desglose de sub-turnos de cada turno
  • Filtros de alcance — acotá los resultados por conductor, dispositivo, grupo de dispositivos, categoría de turno o un turno específico

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ámetroTipoRequeridoPredeterminadoDescripció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 31 días desde startdate.
driversstringNoTodos los visiblesIDs de conductor separados por coma. Máximo 500.
devicesstringNoTodos los visiblesIDs de dispositivo separados por coma. Máximo 500.
device_groupsstringNo—IDs de grupo de dispositivos separados por coma. Máximo 100.
shift_categoriesstringNo—IDs de categoría de turno separados por coma. Máximo 50.
shift_idstringNo—Identificador específico del turno.
compliance_onlybooleanNofalseDevuelve solo los registros no conformes.
detailedbooleanNofalseIncluye el desglose de sub-turnos en la respuesta.
limitintegerNo25Cantidad de registros por página (1–100).
offsetintegerNo0Cantidad de registros a omitir para la paginación.

Ejemplos de código​

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

Respuesta​

Campos de la respuesta​

CampoTipoDescripción
shift_idstring | nullIdentificador del turno.
shift_linenumberNúmero de línea del turno.
driver_idstring | nullIdentificador del conductor.
driver_namestringNombre del conductor.
device_namestringNombre del vehículo.
shift_startstring | nullMarca de tiempo de inicio del turno.
shift_endstring | nullMarca de tiempo de fin del turno.
shift_namestringNombre del turno/horario.
shift_hoursnumberHoras de turno configuradas.
start_addressstringDirección al inicio del turno.
end_addressstringDirección al fin del turno.
start_geofencestringGeocerca al inicio del turno.
end_geofencestringGeocerca al fin del turno.
qra_timestring | nullMarca de tiempo de registro QRA.
qrx_timestring | nullMarca de tiempo de registro QRX.
qrv_timestring | nullMarca de tiempo de registro QRV.
qtp_timestring | nullMarca de tiempo de registro QTP.
worked_hoursnumberHoras trabajadas.
rested_hoursnumberHoras de descanso.
kms_shiftnumberKilómetros durante el turno.
kms_restnumberKilómetros durante el descanso.
compliance_breachbooleanSi se detectó un incumplimiento de cumplimiento.
sub_shiftsarrayDesglose de sub-turnos (incluido cuando detailed=true).

Ejemplo de respuesta​

{
  "success": true,
  "data": [
    {
      "shift_id": "982710394857201664",
      "shift_line": 1,
      "driver_id": "982710394857201700",
      "driver_name": "Carlos Martinez",
      "device_name": "Unit-105",
      "shift_start": "2026-03-05T07:00:00",
      "shift_end": "2026-03-05T15:00:00",
      "shift_name": "Morning Shift",
      "shift_hours": 8,
      "start_address": "Av. Reforma 1234, Col. Centro",
      "end_address": "Av. Reforma 1234, Col. Centro",
      "start_geofence": "Depot Central",
      "end_geofence": "Depot Central",
      "qra_time": "2026-03-05T06:55:00",
      "qrx_time": "2026-03-05T15:05:00",
      "qrv_time": "2026-03-05T07:02:00",
      "qtp_time": null,
      "worked_hours": 7.8,
      "rested_hours": 0.2,
      "kms_shift": 145.3,
      "kms_rest": 2.1,
      "compliance_breach": false,
      "sub_shifts": []
    },
    {
      "shift_id": "982710394857201665",
      "shift_line": 2,
      "driver_id": "982710394857201701",
      "driver_name": "Laura Hernandez",
      "device_name": "Unit-203",
      "shift_start": "2026-03-05T22:00:00",
      "shift_end": "2026-03-06T06:00:00",
      "shift_name": "Night Shift",
      "shift_hours": 8,
      "start_address": "Blvd. Manuel Avila Camacho, Naucalpan",
      "end_address": "Calle Madero 456, Col. Centro",
      "start_geofence": "Zone North",
      "end_geofence": "",
      "qra_time": "2026-03-05T22:10:00",
      "qrx_time": null,
      "qrv_time": "2026-03-05T22:15:00",
      "qtp_time": null,
      "worked_hours": 9.2,
      "rested_hours": 0,
      "kms_shift": 210.5,
      "kms_rest": 0,
      "compliance_breach": true,
      "sub_shifts": []
    }
  ],
  "meta": {
    "total": 2,
    "limit": 25,
    "offset": 0
  }
}

Errores​

CódigoHTTPDescripción
VALIDATION_ERROR400Parámetros inválidos (ej. el rango de fechas supera los 31 días).
UNAUTHORIZED401tenant / Authorization / X-API-Key faltante, inválido o expirado
FORBIDDEN403El usuario carece del permiso requerido.
RATE_LIMITED429Se superaron las 10 req/min.
INTERNAL_ERROR500Error inesperado del servidor.