Eventi

API in beta

Questa pagina descrive /api/v3/events, sotto l’API v3 beta — vedi Panoramica. Il contratto è identico a Eventi (v2): stesso codice, stesso filtro, stesse risposte. Anche se la risposta porta comunque l’header X-API-Status: beta (vale per tutta la v3), qui «beta» descrive la superficie v3 nel suo insieme — in particolare le aree — non un rischio di cambiamento per questo endpoint: cambia solo la base URL, /api/v3 invece di /api/v2.

GET /api/v3/events

Eventi della flotta dell’owner della chiave (ingresso/uscita da un’area, accensione, sosta, allarmi…). Permesso: read_events.

Parametro	Default	Note
type	—	filtro per tipo evento — vedi sotto per i valori delle geofence
device	—	filtro per IMEI
from / to	—	finestra temporale, ISO 8601
limit	50	1–200
offset	0

Per gli eventi di geofence, type accetta:

Valore	Cosa filtra
geofence	tutti gli eventi di geofence (ingressi e uscite)
geofence_enter / geofence_entry	solo gli ingressi
geofence_exit	solo le uscite

geofence_enter/geofence_entry/geofence_exit sono alias che filtrano sullo stesso evento geofence, distinguendo ingresso da uscita.

cURL

curl -H "X-API-Key: $AITRACK_API_KEY" \
  "https://api.aitrack.it/api/v3/events?type=geofence_enter&limit=50"

Node.js

const url = new URL('https://api.aitrack.it/api/v3/events');
url.searchParams.set('type', 'geofence_enter');
url.searchParams.set('limit', '50');

const res = await fetch(url, { headers: { 'X-API-Key': process.env.AITRACK_API_KEY } });
const { data, meta } = await res.json();

Python

res = requests.get(
    "https://api.aitrack.it/api/v3/events",
    headers={"X-API-Key": api_key},
    params={"type": "geofence_enter", "limit": 50},
    timeout=10,
)
events = res.json()["data"]

{
  "data": [
    {
      "id": 5521,
      "type": "geofence",
      "message": "Furgone 1 è entrato in Magazzino",
      "device_imei": "352093081452312",
      "data": { "areaId": 12, "event": "entry" },
      "read": false,
      "occurred_at": "2026-07-14T08:59:00.000Z"
    }
  ],
  "meta": { "pagination": { "limit": 50, "offset": 0, "count": 1 } }
}

Note

Il campo type di un evento di geofence è sempre "geofence", anche filtrando per type=geofence_enter o type=geofence_exit: il filtro sceglie la riga (ingresso o uscita), ma il valore restituito in type resta "geofence"; ingresso o uscita si leggono in data.event ("entry" | "exit").

Permanenza minima sulle geofence

Se l’area coinvolta ha una permanenza minima (dwell_seconds) impostata (via aree o dall’editor dell’app), un evento di entry qui non compare finché il dispositivo non è rimasto dentro l’area per quel tempo: chi ha solo attraversato l’area non genera nessun evento, né di ingresso né di uscita.

Preferisci il push al polling

Interrogare /events a intervalli regolari funziona, ma introduce latenza e chiamate sprecate quando non succede nulla. Per ricevere gli eventi in tempo reale, appena accadono, registra un webhook: stessi tipi di evento, consegnati via POST e firmati.

Vedi anche Errori e limiti per la busta e i codici comuni (stessi della v2), e Aree per gli eventi di ingresso/uscita filtrati per singola area (GET /api/v3/areas/{id}/events).