Reporte de Geocercas

Entradas y salidas de vehículos en zonas con geocerca, incluyendo tiempo de permanencia y filtrado de visitas.

GET/apidev/v1/reports/avl/geofence

PermisoAPICLI_RPTAVL_GEOCERCA

Límite de solicitudes10 req/min (ventana deslizante)

Caché300s (5 min)

Rango máximo31 días

Resumen

Devuelve los eventos de entrada y salida de vehículos que cruzan zonas geográficas predefinidas (geocercas). Cada registro representa una sola visita — desde la entrada hasta la salida.

Filtrado por zona — restringe a geocercas específicas con el parámetro geofences
Umbral de tiempo de permanencia — usa idletime para excluir visitas más cortas que una duración mínima
Analítica de visitas — calcula el tiempo total dentro de cada zona para el cumplimiento de rutas y el monitoreo de SLA

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
`devices`	string	No	Todos los visibles	IDs de dispositivo separados por coma. Máximo 500
`geofences`	string	No	Todas las visibles	IDs de geocerca separados por coma. Máximo 500
`idletime`	number	No	`0`	Tiempo mínimo de permanencia en minutos. Las visitas más cortas se excluyen
`limit`	integer	No	`25`	Registros por página (`1`–`100`)
`offset`	integer	No	`0`	Registros a omitir

Visibilidad de geocercas

Solo se pueden consultar las geocercas visibles para el usuario autenticado. Solicitar el ID de una geocerca inaccesible no devuelve datos para esa zona — no se genera ningún error.

Ejemplos de código

cURL
JavaScript
Python

curl -s "https://$TENANT/apidev/v1/reports/avl/geofence?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&limit=50&geofences=101,102,103" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

const params = new URLSearchParams({
  startdate: "2026-03-01T00:00:00",
  enddate: "2026-03-15T23:59:59",
  limit: "50",
  geofences: "101,102,103",
});

const response = await fetch(
  `https://${TENANT}/apidev/v1/reports/avl/geofence?${params}`,
  { headers }
);

const { data, meta } = await response.json();
for (const visit of data) {
  console.log(`${visit.device_name} → ${visit.geofence}: ${visit.idle} min`);
}

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/avl/geofence",
    headers=headers,
    params={
        "startdate": "2026-03-01T00:00:00",
        "enddate": "2026-03-15T23:59:59",
        "limit": 50,
        "geofences": "101,102,103",
    },
)

result = response.json()
for visit in result["data"]:
    print(f"{visit['device_name']} → {visit['geofence']}: {visit['idle']} min")

Campos de la respuesta

Campo	Tipo	Descripción
`device_name`	string	Nombre visible del vehículo/dispositivo
`person_name`	string	Nombre del conductor asignado al momento de la visita
`geofence`	string	Nombre de la zona de geocerca visitada
`datetime_in`	string \| null	Marca de tiempo cuando el dispositivo entró a la geocerca
`datetime_out`	string \| null	Marca de tiempo cuando el dispositivo salió. `null` si aún está dentro
`idle`	number	Tiempo de permanencia dentro de la geocerca en minutos

Marcas de tiempo

Todas las marcas de tiempo se devuelven sin zona horaria (ej. "2026-03-05T08:12:33"). Consultá Paginación y sobre para el contenedor de respuesta estándar.

Ejemplo de respuesta

{
  "success": true,
  "data": [
    {
      "device_name": "Van B-205",
      "person_name": "Carlos Medina",
      "geofence": "Warehouse Central",
      "datetime_in": "2026-03-05T08:12:33",
      "datetime_out": "2026-03-05T09:35:10",
      "idle": 82.6
    },
    {
      "device_name": "Truck A-101",
      "person_name": "Maria Lopez",
      "geofence": "Client Site North",
      "datetime_in": "2026-03-05T10:05:00",
      "datetime_out": null,
      "idle": 0
    }
  ],
  "meta": {
    "total": 47,
    "limit": 50,
    "offset": 0
  }
}

Usar `idletime` para filtrar visitas cortas

Con idletime=5, las visitas de menos de 5 minutos se excluyen — útil para filtrar la deriva del GPS cerca de los límites de las zonas:

GET /apidev/v1/reports/avl/geofence?startdate=...&enddate=...&idletime=5

Solo se devuelven las visitas con idle >= 5.

Errores

Código	HTTP	Descripción
`INVALID_DATE_RANGE`	400	El rango de fechas supera el máximo de 31 días, el fin es anterior al inicio, o fechas no ISO
`VALIDATION_ERROR`	400	Parámetros inválidos: faltan fechas, `limit` > 100, > 500 dispositivos/geocercas
`UNAUTHORIZED`	401	tenant / Authorization / X-API-Key faltante, inválido o expirado
`FORBIDDEN`	403	El usuario carece del permiso `APICLI_RPTAVL_GEOCERCA`
`RATE_LIMITED`	429	Se superaron las 10 req/min
`INTERNAL_ERROR`	500	Error inesperado del servidor

Límites de solicitudes — Detalles de la ventana deslizante
Paginación — Parámetros de paginación estándar
API de Dispositivos — Obtené IDs de dispositivo para filtrar reportes

Resumen​

Solicitud​

Encabezados de la solicitud​

Parámetros de consulta​

Ejemplos de código​

Campos de la respuesta​

Ejemplo de respuesta​

Usar idletime para filtrar visitas cortas​

Errores​

Relacionado​