Panoramica

API in beta

La v3 è beta: la usiamo già in produzione, ma la forma dei dati può ancora cambiare prima della versione stabile. Ogni cambiamento sarà annunciato — niente rotture silenziose. La v2 non è toccata da questo: resta stabile e invariata accanto alla v3. Vedi Da v2 a v3 per cosa cambia (in breve: niente si rompe — la v3 include tutta la v2 più le aree, e la v2 resta com’è per chi non vuole cambiare nulla).

La v3 include tutta l’API v2 — dispositivi, posizioni, storico, comandi, eventi — con lo stesso codice, sotto /api/v3 invece di /api/v2, più la risorsa che alla v2 è sempre mancata: le aree (geofence) — crearle, leggerle, modificarle, cancellarle, verificare se un punto ci è dentro e leggerne gli eventi di ingresso e uscita. Prima nessuna API key poteva gestire le aree: si potevano gestire solo dall’app. Si può integrare solo con la v3 (v2 + aree) senza toccare /api/v2 — oppure continuare a usare la v2 per tutto tranne le aree: Da v2 a v3 spiega quando conviene l’una o l’altra.

Risorse

Risorsa	Endpoint	Pagina
Dispositivi	/api/v3/devices	Dispositivi
Eventi	/api/v3/events	Eventi
Aree (geofence)	/api/v3/areas	Aree

Dispositivi ed eventi sono lo stesso contratto stabile della v2, solo montato sotto /api/v3: le uniche novità reali della v3 sono le aree, e — dentro le aree — il codice esterno external_id e la permanenza minima dwell_seconds.

Base URL

https://api.aitrack.it/api/v3

Autenticazione

Stessa dell’API v2: header X-API-Key, creata da Impostazioni → API Keys. Authorization: Bearer resta riservato ai token di sessione dell’app ed è rifiutato — vedi Autenticazione. Le sessioni web (login utente) non bastano: la v3 richiede sempre un’API key, altrimenti risponde 403 API_KEY_REQUIRED.

curl https://api.aitrack.it/api/v3/areas \
  -H "X-API-Key: $AITRACK_API_KEY"

Permessi (scope)

Stessi permessi della v2 per dispositivi ed eventi, più due nuovi per le aree — tutti concedibili alla chiave in Impostazioni → API Keys, indipendentemente l’uno dall’altro:

Permesso	Cosa apre
read_devices	Elenco dispositivi, dispositivo più vicino, dettaglio
read_locations	Ultima posizione nota, dispositivo più vicino
read_history	Storico delle posizioni
read_history_summary	Riepiloghi dello storico
send_commands	Lettura della coda comandi (l’invio non è esposto in API)
read_events	Eventi della flotta
read_areas	Elenco, dettaglio, contains, eventi di ingresso/uscita delle aree
write_areas	Creazione, modifica, eliminazione, import e upsert per external_id delle aree

Senza il permesso: 403 INSUFFICIENT_SCOPE. Un’area di un altro cliente non risponde mai 403, ma sempre 404: non conferma nemmeno che l’area esista — stessa regola per i dispositivi (404 DEVICE_NOT_FOUND), vedi Errori e limiti per i codici propri di dispositivi ed eventi.

Header di risposta

Ogni risposta v3 porta X-API-Status: beta, per distinguerla in automatico dalla v2 anche solo guardando gli header. A differenza della v1 (deprecata), v2 e v3 non portano Deprecation né Sunset: sono entrambe superfici attive, solo con uno stato diverso.

Busta delle risposte

Stessa busta della v2 — vedi Errori e limiti — con un campo in più sugli errori di validazione:

{ "data": { }, "meta": { "pagination": { "limit": 50, "offset": 0, "count": 3 } } }

{ "error": { "code": "VALIDATION_ERROR", "message": "Il nome è obbligatorio.", "details": [
  { "field": "name", "code": "REQUIRED", "message": "Il nome è obbligatorio." }
] } }

details compare solo su 422 VALIDATION_ERROR ed elenca ogni campo non valido, non solo il primo — vedi la tabella completa dei codici in Aree.

Errori generali

HTTP	error.code	Significato
400	BAD_REQUEST	Parametro non valido (es. type sconosciuto in un filtro, lat/lng mancanti, id/external_id malformato nel percorso)
403	API_KEY_REQUIRED	Autenticato ma non con API key (sessione web), o key assente
403	INSUFFICIENT_SCOPE	Permesso mancante sulla chiave (read_areas/write_areas, o quelli della v2)
404	NOT_FOUND	Area inesistente o di un altro cliente — le due situazioni non si distinguono
409	CONFLICT	external_id già usato da un’altra tua area, solo su POST /areas — vedi Aree
422	VALIDATION_ERROR	Corpo della richiesta non valido — dettaglio in details[]
429	(nessun code dedicato)	Rate limit superato
500	INTERNAL_ERROR	Errore nostro

I dispositivi e gli eventi hanno anche i propri codici (DEVICE_NOT_FOUND, LOCATION_NOT_FOUND, COORDINATES_REQUIRED…), identici alla v2 — vedi Errori e limiti. Le richieste rifiutate prima di entrare nella v3 (API key sconosciuta, revocata, IP bloccato) usano gli stessi codici generali della v2 — API_KEY_INVALID, API_KEY_REVOKED, API_KEY_OWNER_INACTIVE, API_KEY_IP_BLOCKED — sempre 403.

Rate limit

Stesso limite della v2, condiviso per chiave (non per versione):

Limite	Valore
Per chiave, al minuto	120
Per chiave, all’ora	1000
Per indirizzo IP, al minuto	120

Oltre il limite: 429, senza header X-RateLimit-* né Retry-After.

Idempotency-Key

Solo su POST /api/v3/areas (creazione): un header opzionale Idempotency-Key (1–200 caratteri: lettere, cifre, . _ : -) fa sì che ripetere la stessa richiesta con lo stesso valore, entro 24 ore, restituisca la stessa risposta invece di creare un’area doppia. La risposta rigiocata porta l’header Idempotent-Replayed: true. Utile quando un client ritenta dopo un timeout senza sapere se la prima richiesta è arrivata.

curl -X POST https://api.aitrack.it/api/v3/areas \
  -H "X-API-Key: $AITRACK_API_KEY" \
  -H "Idempotency-Key: crea-magazzino-nord-2026-09-27" \
  -H "Content-Type: application/json" \
  -d '{"name":"Magazzino Nord","type":"circle","center":{"lat":45.4642,"lng":9.19},"radius_m":150}'

Non è applicata su PATCH, DELETE o POST /areas/import.

Documentazione machine-readable

La v3 espone la propria spec OpenAPI 3.0 e una pagina interattiva, pubbliche (nessuna API key richiesta per leggerle):

• GET /api/v3/openapi.json — la spec
• GET /api/v3/docs — Swagger UI, per provare le chiamate dal browser

Cosa può ancora cambiare (beta)

Non congeliamo ancora questi dettagli come garanzia di compatibilità: possono affinarsi prima della versione stabile, sempre con un annuncio prima.

• Nomi ed elenco esatto dei codici in details[].code sugli errori di validazione (l’insieme può crescere; i codici già esistenti non cambiano significato).
• Campi aggiuntivi nella risposta delle aree (metrics, bounds) — solo aggiunte, non rimozioni.
• Il formato della risposta di POST /areas/import (oggi { dry_run, valid, created, errors, warnings }).

Quello che non cambia senza preavviso: header di autenticazione, forma dell’envelope { data, meta } / { error }, scope read_areas/write_areas, e ogni endpoint già documentato in Aree resta raggiungibile.

Prossimi passi

• Dispositivi e Eventi — stesso riferimento della v2, sotto /api/v3.
• Aree — riferimento completo di ogni endpoint, con esempi curl e JSON.
• Da v2 a v3 — cosa cambia per chi integra già la v2.