Da v2 a v3

API in beta

La v3 è beta — vedi Panoramica per cosa può ancora cambiare. Questa pagina non è una guida “aggiorna il tuo client”: è la spiegazione di cosa c’è di nuovo e di cosa, invece, non tocchi.

In breve

Non devi migrare niente. La v3 non sostituisce la v2, entrambe restano attive: nessun endpoint v2 cambia forma, nessun campo sparisce, nessuna chiave smette di funzionare. Se oggi integri dispositivi, posizioni, storico ed eventi con /api/v2, puoi continuare a farlo esattamente come prima. Oppure, se preferisci, puoi integrare da subito solo /api/v3: include tutto quello che c’è in /api/v2 (stesso codice, stesse risposte) più le aree — non è un obbligo, solo un’opzione in più.

Cosa aggiunge la v3

Due cose, rispetto alla v2:

1. Tutta la v2, montata sotto /api/v3 invece che /api/v2: dispositivi, posizioni, storico, comandi, eventi — stesso codice, stessi scope, stesse risposte. Chi vuole può integrare solo la v3 invece di v2 + v3 separate.
2. Le aree (geofence), una risorsa che la v2 non ha mai esposto: crearle, leggerle, modificarle, cancellarle, verificare se un punto ci è dentro, leggerne gli eventi di ingresso e uscita — con codice esterno (external_id) per sincronizzarle da un tuo sistema senza doppioni e permanenza minima (dwell_seconds) prima di notificare l’entrata. Prima l’unico modo per gestire le aree era l’app. Vedi il riferimento completo in Aree.

	v2	v3 (beta)
Risorse	dispositivi, posizioni, storico, eventi (sola lettura)	le stesse della v2, identiche, più aree/geofence (lettura e scrittura)
Permessi (scope)	read_devices, read_locations, read_history, read_history_summary, read_events, send_commands	tutti quelli della v2, più read_areas, write_areas
Base URL	/api/v2	/api/v3
Stato	stabile	beta (le parti ereditate dalla v2 hanno lo stesso contratto stabile; vedi Panoramica)

Le due basi URL convivono: una stessa chiave, con lo scope giusto, può leggere /api/v2/devices e scrivere /api/v3/areas nella stessa integrazione — oppure usare solo /api/v3 per tutto.

Cosa resta identico

• Autenticazione: header X-API-Key, stesso ciclo di vita della chiave — vedi Autenticazione.
• Busta delle risposte: { data, meta } / { error: { code, message } } — la v3 aggiunge solo details[] sugli errori di validazione.
• Rate limit: 120/minuto e 1000/ora per chiave, 120/minuto per IP — condiviso tra v2 e v3, non raddoppiato per versione.
• Perimetro: sempre lo scope del proprietario della chiave; risorse di un altro cliente sempre 404, mai 403.
• Errori generali (API_KEY_INVALID, API_KEY_REVOKED, API_KEY_OWNER_INACTIVE, API_KEY_IP_BLOCKED, sempre 403) — vedi Versioning.

Cosa è diverso solo nella v3

• Header X-API-Status: beta su ogni risposta.
• Idempotency-Key su POST /api/v3/areas — non esiste un equivalente in v2.
• Documentazione machine-readable propria: /api/v3/openapi.json e /api/v3/docs.

Se integri solo v2 oggi

Non serve fare nulla. Se in futuro ti servirà leggere o scrivere aree via API (per esempio sincronizzare le geofence con un tuo sistema esterno, o generarle da un tuo processo), hai due strade: aggiungere lo scope read_areas/write_areas alla chiave esistente — o crearne una dedicata — e chiamare /api/v3/areas accanto a /api/v2, senza toccare l’integrazione già in produzione; oppure passare del tutto a /api/v3 (stesso comportamento per dispositivi ed eventi, più le aree) e smettere di usare /api/v2. Nessuna delle due è obbligatoria.