Reporte de Resumen de Trabajo

Resumen de días trabajados agrupado por conductor/vehículo o por prestador, con tareas de apertura/cierre, ventanas de descanso y alertas de desvío geodésico.

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

PermisoAPICLI_RPTCPM_RESUMENTRABAJO

Límite de solicitudes10 req/min

Caché300s

Rango máximo31 días

---

Resumen

Devuelve una fila de resumen por cada día trabajado dentro del período seleccionado. En modo móvil, cada fila se ancla a un turno de trabajo del conductor (conductor + vehículo), y en modo prestador, cada fila se ancla a un prestador + día. Cada fila expone la tarea que abrió el día y la tarea que lo cerró, la ventana de descanso y el desvío geodésico entre la dirección de la tarea y el lugar donde realmente se registró el evento de campo.

• Agrupación — group_by=movil ancla las filas a turnos de conductor; group_by=prestador las ancla a prestador + día
• Modo de fecha — date_type controla a qué fecha de la tarea se aplica el período (finalización, ingreso o proceso completo)
• Alertas de desvío — deviation_threshold define la distancia de alerta (metros); deviation_only=true devuelve solo las filas que la superaron
• Filtros de alcance — acotá los resultados por vehículo, conductor, prestador o código de finalización de servicio

---

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
startdate	string	Sí	—	Fecha-hora de inicio en ISO 8601 (ej. 2026-03-01T00:00:00).
enddate	string	Sí	—	Fecha-hora de fin en ISO 8601. Rango máximo 31 días desde startdate.
group_by	string	No	movil	Modo de agrupación: movil (turno de conductor/vehículo) o prestador (prestador + día).
date_type	string	No	finalizacion	A qué fecha de la tarea se aplica el período: finalizacion (fin de tarea), ingreso (llamado/ingreso de tarea) o todo (solapamiento del proceso completo).
devices	string	No	Todos los visibles	IDs de vehículo separados por coma. Aplica a group_by=movil. Máximo 500.
drivers	string	No	Todos los visibles	IDs de conductor separados por coma. Aplica a group_by=movil. Máximo 500.
suppliers	string	No	Todos los visibles	IDs de prestador separados por coma. Aplica a group_by=prestador. Máximo 500.
service_end_codes	string	No	—	IDs de finalización de servicio separados por coma. Máximo 100.
deviation_threshold	integer	No	200	Distancia de alerta en metros. Una fila se marca cuando un evento se registra a mayor distancia que esta de la dirección de la tarea.
deviation_only	boolean	No	false	Devuelve solo las filas con al menos una alerta de desvío.
limit	integer	No	25	Cantidad de registros por página (1–100).
offset	integer	No	0	Cantidad de registros 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/work-summary?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&group_by=movil&date_type=finalizacion&limit=25"

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/reports/cpm/work-summary?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&group_by=movil&date_type=finalizacion&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/work-summary",
    headers={"Authorization": f"Bearer {token}", "X-API-Key": api_key, "tenant": TENANT},
    params={
        "startdate": "2026-03-01T00:00:00",
        "enddate": "2026-03-15T23:59:59",
        "group_by": "movil",
        "date_type": "finalizacion",
        "limit": 25,
    },
)
data = response.json()

---

Respuesta

Campos de la respuesta

Cada fila representa un día trabajado. Los bloques opening y closing describen la tarea que abrió y cerró el día; ambos comparten la misma estructura de extremo de tarea.

Campo	Tipo	Descripción
shift_id	string | null	Identificador del turno de trabajo del conductor. null en modo prestador.
schema	string	Conjunto de tablas del que salió la jornada: public (abierta/vigente) o historic (cerrada).
driver_id	string | null	Identificador del conductor.
driver_name	string | null	Nombre del conductor.
driver_image_url	string | null	URL de la foto del conductor.
device_id	string | null	Identificador del móvil (vehículo).
device_name	string | null	Nombre del móvil (vehículo).
supplier_id	string | null	Identificador del prestador (modo prestador).
supplier_name	string | null	Nombre del prestador (modo prestador).
shift_start	string | null	Marca de tiempo de inicio del turno (QRA).
shift_end	string | null	Marca de tiempo de fin del turno (QTP).
rest_start	string | null	Inicio de la ventana de descanso.
rest_end	string | null	Fin de la ventana de descanso.
opening	object | null	La tarea que abrió el día (ver campos de Extremo de tarea). null si la jornada no emparejó ninguna tarea.
closing	object | null	La tarea que cerró el día (ver campos de Extremo de tarea). null si la jornada no emparejó ninguna tarea.
tasks	array	Todas las tareas del día, cada una como un objeto de Extremo de tarea.
task_count	number	Cantidad de elementos de tasks.

Nombres de los campos

device_* y supplier_* son los nombres del dominio GeoTareas para lo que versiones anteriores de esta página llamaban vehicle_* / provider_*. La API usa el vocabulario del dominio.

Campos de Extremo de tarea

Campo	Tipo	Descripción
task_id	string	Identificador de la tarea.
task_number	string | null	Número de servicio/tarea.
status_name	string | null	Nombre del estado del evento.
finalization_code_id	string | null	Identificador del código de finalización de servicio.
finalization_code_name	string | null	Nombre del código de finalización de servicio.
account_external_code	string | null	Código externo de la cuenta.
account_name	string | null	Nombre de la cuenta.
task_address	string | null	Dirección de la tarea (calle/número/apartamento/esquina).
event_time	string | null	Marca de tiempo del evento (inicio o fin).
event_address	string | null	Dirección donde se registró el evento.
deviation_distance	number | null	Distancia geodésica (metros) entre la dirección de la tarea y la ubicación del evento.
deviation_alert	boolean	Si deviation_distance superó el umbral.
parameters	string | null	Resumen legible del evento (código de finalización, parámetros, notas).

Ejemplo de respuesta

{
  "success": true,
  "data": [
    {
      "shift_id": "982710394857201664",
      "schema": "historic",
      "driver_id": "982710394857201700",
      "driver_name": "Carlos Martinez",
      "driver_image_url": null,
      "device_id": "982710394857201800",
      "device_name": "Unit-105",
      "supplier_id": null,
      "supplier_name": null,
      "shift_start": "2026-03-05T07:00:00",
      "shift_end": "2026-03-05T15:00:00",
      "rest_start": "2026-03-05T11:30:00",
      "rest_end": "2026-03-05T12:00:00",
      "opening": {
        "task_id": "982710394857202001",
        "task_number": "100245",
        "status_name": "Started",
        "finalization_code_id": null,
        "finalization_code_name": null,
        "account_external_code": "CLI-0098",
        "account_name": "Acme Logistics",
        "task_address": "Av. Reforma 1234, Esq. Juarez",
        "event_time": "2026-03-05T07:42:00",
        "event_address": "Av. Reforma 1234, Col. Centro",
        "deviation_distance": 35,
        "deviation_alert": false,
        "parameters": "Finalization Code: Completed | Notes: Delivered on time"
      },
      "closing": {
        "task_id": "982710394857202055",
        "task_number": "100312",
        "status_name": "Finished",
        "finalization_code_id": "982710394857203001",
        "finalization_code_name": "Completed",
        "account_external_code": "CLI-0142",
        "account_name": "Globex Retail",
        "task_address": "Calle Madero 456, Col. Centro",
        "event_time": "2026-03-05T14:48:00",
        "event_address": "Calle Madero 460, Col. Centro",
        "deviation_distance": 320,
        "deviation_alert": true,
        "parameters": "Finalization Code: Completed | Signature: Yes"
      },
      "tasks": [
        {
          "task_id": "982710394857202001",
          "task_number": "100245",
          "status_name": "Finalizada",
          "finalization_code_id": "982710394857203001",
          "finalization_code_name": "Completada",
          "account_external_code": "CLI-0098",
          "account_name": "Acme Logistics",
          "task_address": "Av. Reforma 1234, Esq. Juarez",
          "event_time": "2026-03-05T08:15:00",
          "event_address": "Av. Reforma 1234, Col. Centro",
          "deviation_distance": 35,
          "deviation_alert": false,
          "parameters": "Codigo de finalizacion: Completada | Notas: Entregado en tiempo"
        },
        {
          "task_id": "982710394857202055",
          "task_number": "100312",
          "status_name": "Finalizada",
          "finalization_code_id": "982710394857203001",
          "finalization_code_name": "Completada",
          "account_external_code": "CLI-0142",
          "account_name": "Globex Retail",
          "task_address": "Calle Madero 456, Col. Centro",
          "event_time": "2026-03-05T14:48:00",
          "event_address": "Calle Madero 460, Col. Centro",
          "deviation_distance": 320,
          "deviation_alert": true,
          "parameters": "Codigo de finalizacion: Completada | Firma: Si"
        }
      ],
      "task_count": 2
    }
  ],
  "meta": {
    "total": 1,
    "limit": 25,
    "offset": 0
  }
}

---

Errores

Código	HTTP	Descripción
VALIDATION_ERROR	400	Parámetros inválidos (ej. el rango de fechas supera los 31 días, o un valor desconocido de group_by / date_type).
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