Reporte de Resumen de Actividad

Calendario mensual de actividad por persona: una fila por persona, una celda por día, con estado de turno, descanso y ausencia.

GET/apidev/v1/reports/cpm/activity-summary

PermisoAPICLI_RPTCPM_RESUMENACTIVIDAD

Límite de solicitudes10 req/min

Caché300s

Rango máximo1 mes

---

Resumen

Devuelve un resumen tipo calendario para el mes seleccionado. Cada persona aparece una vez, con una lista de entradas de actividad diaria que muestran el turno trabajado, los períodos de descanso, las horas trabajadas y descansadas, los kilómetros recorridos y el estado a nivel de día (trabajado, día de descanso o ausencia). Úsalo para revisar la asistencia y la carga de trabajo de todo un mes de un vistazo.

• Vista mensual — el período es un único mes calendario; se evalúan los días hasta la fecha actual de la compañía, y los días futuros quedan vacíos
• Estado del día — cada día lleva un estado para que puedas detectar ausencias, días de descanso e incumplimientos sin analizar marcas de tiempo en bruto
• Filtros de alcance — acotá los resultados por persona, dispositivo, tipo de dispositivo o categoría de turno

---

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
month	string	Sí	—	Mes objetivo en ISO 8601 (ej. 2026-03 o 2026-03-01). Cubre el mes calendario completo.
drivers	string	No	Todos los visibles	IDs de persona separados por coma. Máximo 500.
devices	string	No	Todos los visibles	IDs de dispositivo separados por coma. Máximo 500.
device_types	string	No	—	IDs de tipo de dispositivo separados por coma. Máximo 100.
shift_categories	string	No	—	IDs de categoría de turno separados por coma. Máximo 50.
limit	integer	No	25	Cantidad de personas por página (1–100).
offset	integer	No	0	Cantidad de personas a omitir para la paginación.

---

Ejemplos de código

cURL

curl -s -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  "https://$TENANT/apidev/v1/reports/cpm/activity-summary?month=2026-03&limit=25"

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/reports/cpm/activity-summary?month=2026-03&limit=25`,
  {
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-API-Key': apiKey,
      'tenant': TENANT,
    },
  }
);
const data = await res.json();

Python

import requests

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/cpm/activity-summary",
    headers={"Authorization": f"Bearer {token}", "X-API-Key": api_key, "tenant": TENANT},
    params={"month": "2026-03", "limit": 25},
)
data = response.json()

---

Respuesta

Campos de la respuesta

Cada elemento en data es una persona con un array activities de entradas diarias.

Campo	Tipo	Descripción
person_id	string | null	Identificador de la persona.
person_name	string | null	Nombre de la persona.
person_image	string | null	URL de la imagen de la persona.
total_worked_minutes	number	Minutos trabajados en el mes (suma de activities[].worked_minutes).
total_discount_minutes	number	Minutos de descuento del mes (llegadas tarde + salidas anticipadas).
activities	array	Una entrada por día del mes (ver más abajo).

Entrada de actividad (activities[])

Una entrada por día del mes, incluidos los días sin jornada (llevan solo day, date y status) — son las mismas celdas que pinta la matriz de la pantalla.

Campo	Tipo	Descripción
day	number | null	Día del mes (1–31).
date	string | null	Fecha de la entrada (YYYY-MM-DD).
shift_id	string | null	Identificador de la jornada.
shift_line	number | null	Número de línea del descanso dentro de la jornada.
shift_name	string | null	Nombre del turno/horario.
device_name	string | null	Nombre del móvil (vehículo).
shift_start	string | null	Marca de tiempo de inicio del turno.
shift_end	string | null	Marca de tiempo de fin del turno.
rest_start	string | null	Marca de tiempo de inicio del descanso.
rest_end	string | null	Marca de tiempo de fin del descanso.
qra_time	string | null	Marca efectiva de inicio de jornada (QRA).
qtp_time	string | null	Marca efectiva de fin de jornada (QTP).
start_address	string | null	Dirección donde comenzó la jornada.
end_address	string | null	Dirección donde terminó la jornada.
worked_minutes	number | null	Minutos trabajados ese día (jornada menos descanso).
discount_minutes	number | null	Minutos de descuento del día (llegada tarde + salida anticipada).
status	string | null	Estado del día: OK (cumplió), WARN (revisar), ERROR (incumplió). null = sin jornada.
status_reason	string | null	Código del motivo del estado (ej. absent). null si no hay motivo.
edited	boolean	true cuando un supervisor corrigió alguna marca del día.
edited_by	string | null	Quién corrigió la marca.
shifts_count	number	Jornadas de ese día (> 1 = varias jornadas en un día). 0 = sin jornada.

Datos no disponibles

Los kilómetros (kms_shift / kms_rest) y las horas descansadas no los devuelve este reporte: el motor de la matriz mensual no los calcula. Versiones anteriores de esta página listaban worked_hours, rested_hours, kms_shift y kms_rest — solo existe el tiempo trabajado, y se publica como worked_minutes. Los kilómetros por jornada están en Detalle de Actividades.

Ejemplo de respuesta

{
  "success": true,
  "data": [
    {
      "person_id": "982710394857201700",
      "person_name": "Carlos Martinez",
      "person_image": "https://cdn.example.com/people/982710394857201700.jpg",
      "total_worked_minutes": 9450,
      "total_discount_minutes": 65,
      "activities": [
        {
          "day": 5,
          "date": "2026-03-05",
          "shift_id": "982710394857201664",
          "shift_line": 1,
          "shift_name": "Turno Mañana",
          "device_name": "Unit-105",
          "shift_start": "2026-03-05T07:00:00",
          "shift_end": "2026-03-05T15:00:00",
          "rest_start": "2026-03-05T11:00:00",
          "rest_end": "2026-03-05T11:30:00",
          "qra_time": "2026-03-05T07:02:00",
          "qtp_time": "2026-03-05T15:04:00",
          "start_address": "Av. Reforma 1234, Col. Centro",
          "end_address": "Calle Madero 456, Col. Centro",
          "worked_minutes": 450,
          "discount_minutes": 0,
          "status": "OK",
          "status_reason": null,
          "edited": false,
          "edited_by": null,
          "shifts_count": 1
        },
        {
          "day": 6,
          "date": "2026-03-06",
          "shift_id": null,
          "shift_line": null,
          "shift_name": null,
          "device_name": null,
          "shift_start": null,
          "shift_end": null,
          "rest_start": null,
          "rest_end": null,
          "qra_time": null,
          "qtp_time": null,
          "start_address": null,
          "end_address": null,
          "worked_minutes": null,
          "discount_minutes": null,
          "status": "ERROR",
          "status_reason": "absent",
          "edited": false,
          "edited_by": null,
          "shifts_count": 0
        }
      ]
    },
    {
      "person_id": "982710394857201701",
      "person_name": "Laura Hernandez",
      "person_image": null,
      "total_worked_minutes": 7680,
      "total_discount_minutes": 0,
      "activities": [
        {
          "day": 5,
          "date": "2026-03-05",
          "shift_id": "982710394857201999",
          "shift_line": null,
          "shift_name": "Turno Noche",
          "device_name": "Unit-203",
          "shift_start": "2026-03-05T22:00:00",
          "shift_end": "2026-03-06T06:00:00",
          "rest_start": null,
          "rest_end": null,
          "qra_time": "2026-03-05T22:00:00",
          "qtp_time": "2026-03-06T06:00:00",
          "start_address": "Ruta 8 Km 24",
          "end_address": "Ruta 8 Km 24",
          "worked_minutes": 480,
          "discount_minutes": 0,
          "status": "OK",
          "status_reason": null,
          "edited": true,
          "edited_by": "supervisor.mendez",
          "shifts_count": 1
        }
      ]
    }
  ],
  "meta": {
    "total": 2,
    "limit": 25,
    "offset": 0
  }
}

---

Errores

Código	HTTP	Descripción
VALIDATION_ERROR	400	Parámetros inválidos (ej. month mal formado).
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 las 10 req/min.
INTERNAL_ERROR	500	Error inesperado del servidor.

---

Relacionado

• Autenticación
• Paginación
• Límites de solicitudes
• Manejo de errores