API de Streaming de Eventos

API de streaming de eventos en tiempo real con consultas por ventana temporal, filtrado por viewport, selección automática de modo de respuesta y suscripciones WebSocket.

Última actualización: 2025-02-18

API de Streaming de Eventos

La API de Streaming de Eventos proporciona acceso eficiente a eventos logísticos para visualización en mapas, dashboards y analíticas. Selecciona automáticamente el formato de respuesta óptimo basándose en los parámetros de consulta.

certexi.com/app/geo/heatmap
Loading interactive demo...

500 eventos logísticos renderizados desde la API de streaming con selección automática de modo.

Endpoint Principal

GET/api/events/stream

Consultar eventos dentro de una ventana temporal y viewport

Parámetros Requeridos:

ParámetroTipoDescripción
fromISO 8601Inicio de ventana temporal
toISO 8601Fin de ventana temporal

Parámetros Opcionales:

ParámetroTipoDescripción
minLngnumberLímite oeste del viewport
maxLngnumberLímite este del viewport
minLatnumberLímite sur del viewport
maxLatnumberLímite norte del viewport
typestringFiltrar por tipo de evento (entry, exit, placement, etc.)
warehousenumberFiltrar por ID de almacén
limitnumberMáximo de eventos (por defecto: 10000)

Modos de Respuesta

La API selecciona automáticamente el formato de respuesta óptimo:

Rango TemporalCantidad de EventosModo de RespuestaFormato
< 1 día< 10,000Eventos crudosPuntos individuales
< 1 día> 10,000Clusters espacialesAgrupados con conteo
1-7 díasCualquieraBuckets por horaAgregados por hora
7-30 díasCualquieraBuckets por díaAgregados por día
> 30 díasCualquieraBuckets por semanaAgregados por semana

Respuesta de Eventos Crudos

{
  "mode": "raw",
  "total": 847,
  "events": [
    {
      "id": "evt-001",
      "type": "entry",
      "lat": 25.6714,
      "lng": -100.3097,
      "timestamp": "2025-01-15T14:32:07Z",
      "tu_id": "TU-2025-00042",
      "operator": "carlos.mendez",
      "warehouse": "Monterrey Hub"
    }
  ]
}

Respuesta Agrupada

{
  "mode": "clustered",
  "total": 24500,
  "clusters": [
    {
      "lat": 25.67,
      "lng": -100.31,
      "count": 342,
      "types": { "entry": 120, "exit": 115, "placement": 107 }
    }
  ]
}

Respuesta Agregada

{
  "mode": "aggregated",
  "total": 156000,
  "buckets": [
    {
      "start": "2025-01-15T00:00:00Z",
      "end": "2025-01-15T01:00:00Z",
      "count": 245,
      "byType": { "entry": 82, "exit": 78, "placement": 85 }
    }
  ]
}

Suscripción WebSocket

Para actualizaciones en tiempo real, suscríbete al endpoint WebSocket:

const ws = new WebSocket('wss://your-app.com/api/events/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({
    action: 'subscribe',
    filters: {
      warehouse: 1,
      types: ['entry', 'exit', 'placement'],
    },
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // { type: 'event', payload: { ... } }
};

Tipos de Evento

TipoDescripciónFrecuencia Típica
entryVehículo ingresa a la instalación50-200/día
exitVehículo sale de la instalación50-200/día
placementActivo colocado en slot200-500/día
removalActivo retirado del slot200-500/día
verificationVerificación de supervisor100-300/día
weighingMedición de báscula50-200/día
incidentIncidente de cumplimiento0-10/día
motionDetección de movimiento CCTV50-500/día

Rendimiento

EscenarioLatencia ObjetivoReal
10k eventos en ventana< 200ms~120ms
50k eventos (agrupados)< 300ms~200ms
100k eventos (agregados)< 400ms~250ms
1M eventos (buckets semanales)< 500ms~300ms

Límites de Tasa

PlanSolicitudes/minVentana temporal máxima
Prueba gratuita3024 horas
Profesional10090 días
Empresarial5001 año

Integración del Cliente

import { useEvents } from '@/hooks/useEvents';

const {
  events,
  clusters,
  isLoading,
  totalCount,
  renderMode,
} = useEvents({
  timeWindow: { from, to },
  bounds: { minLng, minLat, maxLng, maxLat },
  enabled: true,
});

// renderMode: 'raw' | 'clustered' | 'aggregated'
// Events are automatically cached with 5-min TTL
ℹ️

Gestión de Memoria

La caché del lado del cliente mantiene un máximo de 5 segmentos temporales (50MB). La política de evicción LRU elimina el segmento menos usado recientemente cuando uno nuevo se carga. Todas las solicitudes pendientes se cancelan al desmontar el componente.

Relacionado