Reporte de Ubicación en Vivo

Analítica de uso de los enlaces de seguimiento — creación, aperturas y cantidad de respuestas.

GET/apidev/v1/reports/gt/live-location

PermisoAPICLI_RPTGT_LIVELOCATION

Límite de solicitudes10 req/min

Caché300s

Rango máximo31 días

---

Resumen

Devuelve la analítica de uso de los enlaces de seguimiento compartidos con los clientes finales dentro de un rango de fechas — cuántos enlaces se crearon, se abrieron, se usaron y obtuvieron respuesta, junto con la cantidad de receptores únicos. Usá group_by para agregar por día, producto, causa o dispositivo, y filtrá por dispositivos, conductores, tipos de servicio, causas o geografía.

---

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	Por defecto	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.
devices	string	No	—	IDs de dispositivos separados por comas. Máximo 500.
drivers	string	No	—	IDs de conductores separados por comas. Máximo 500.
service_types	string	No	—	IDs de tipos de servicio separados por comas. Máximo 100.
causes	string	No	—	IDs de causas separados por comas. Máximo 100.
countries	string	No	—	IDs de países separados por comas. Máximo 50.
departments	string	No	—	IDs de departamentos separados por comas. Máximo 50.
group_by	enum	No	day	Modo de agrupación: detail (una fila por link de seguimiento — la vista por defecto del reporte web), day, product, cause, device.
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/gt/live-location?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&group_by=day&limit=25"

JavaScript

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

---

Respuesta

Campos de la respuesta

Campo	Tipo	Descripción
task_number	string | null	Número de tarea.
product_name	string	Nombre del producto.
product_type	string	Tipo de producto.
service_type	string	Tipo de servicio.
cause	string	Nombre de la causa.
device_name	string	Nombre del vehículo. Presente en detail y device.
receiver	string	Solo detail — a dónde se envió el último aviso (correo o teléfono).
channel_name	string	Solo detail — canal del último aviso, ya legible (Correo, SMS, WhatsApp, Webhook).
created_at	string | null	Solo detail — cuándo se creó el link de seguimiento.
used_at	string | null	Solo detail — cuándo lo abrió el destinatario. null si nunca lo abrió.
access_count	number | null	Solo detail — cuántas veces se abrió el link.
status_name	string	Solo detail — estado del link, ya legible (Activo, Vencido, Inactivo).
link_path	string	Solo detail — ruta relativa del link compartible (anteponer el origen de tu portal).
link_count	number | null	Solo modos agrupados — cantidad de links del grupo.
created_count	number	Enlaces creados.
used_count	number	Enlaces usados.
receiver_count	number	Receptores únicos.
hash	string	Hash del enlace de seguimiento.
total_links	number	Total de enlaces generados.
unopened	number	Enlaces no abiertos.
opened	number	Enlaces abiertos.
date	string | null	Fecha (cuando se agrupa por día).
response_count	number	Respuestas recibidas.

El modo de agrupación cambia la forma de la respuesta

El reporte web abre sin agrupar (group_by=detail): una fila por link de seguimiento, con destinatario, canal, fecha de apertura, cantidad de accesos, estado y el link. Los modos agrupados (day, product, cause, device) devuelven una fila por grupo, con link_count, unopened y opened. Los campos que no aplican al modo pedido vuelven vacíos ('') o null — en ese modo el dato no existe.

Ejemplo de respuesta

{
  "success": true,
  "data": [
    {
      "task_number": "104820580001",
      "product_name": "Installation",
      "product_type": "Field",
      "service_type": "Maintenance",
      "cause": "Scheduled",
      "device_name": "Truck A-101",
      "receiver": "cliente@ejemplo.com",
      "channel_name": "Correo",
      "created_at": "2026-03-05T08:15:00",
      "used_at": "2026-03-05T08:41:00",
      "access_count": 2,
      "status_name": "Activo",
      "link_path": "/seg/6f2b9c1d",
      "link_count": null,
      "created_count": 3,
      "used_count": 2,
      "receiver_count": 1,
      "hash": "abc123",
      "total_links": 3,
      "unopened": 1,
      "opened": 2,
      "date": "2026-03-05",
      "response_count": 1
    }
  ],
  "meta": {
    "total": 1,
    "limit": 25,
    "offset": 0
  }
}

---

Errores

Código	HTTP	Descripción
VALIDATION_ERROR	400	Parámetros inválidos: faltan fechas, rango > 31 días, valores de enum inválidos.
UNAUTHORIZED	401	tenant / Authorization / X-API-Key faltante, inválido o expirado
FORBIDDEN	403	El usuario no tiene el permiso requerido.
RATE_LIMITED	429	Se superaron las 10 req/min.
INTERNAL_ERROR	500	Error inesperado del servidor.

---

Relacionados

• Reporte de Tareas General
• Paginación