API REST per accedere ai dati dei dispositivi IoT della piattaforma EOS. Questa documentazione ti guida nell’utilizzo delle API per integrare i dati dei dispositivi nelle tue applicazioni.

📥 Scarica la specifica OpenAPI e condividila con il tuo agente AI per ottenere il contesto completo delle API.

Scarica openapi.json

Nota: Questo è un nuovo prodotto (versione 1.0.0). Accogliamo con piacere ogni feedback per aiutarci a migliorare le API. Non esitare a condividere i tuoi suggerimenti o a segnalare eventuali problemi riscontrati.

Autenticazione

Tutte le richieste devono includere l’header x-api-key con la tua API key fornita in fase di registrazione.

Esempio:

curl -H "x-api-key: YOUR_API_KEY" https://p2uyaymt8c.execute-api.eu-south-1.amazonaws.com/v1/integration/devices

Sicurezza:

  • ⚠️ Non condividere mai la tua API key
  • ⚠️ Non inserirla nel codice sorgente
  • ✅ Usa variabili d’ambiente per memorizzarla

Limitazione delle richieste

Le API sono soggette a limitazione delle richieste (rate limiting) per garantire la stabilità del servizio. I limiti specifici dipendono dal tuo piano di utilizzo:

Piano Standard:

  • Rate: 0,5 richieste al secondo
  • Burst: 5 richieste simultanee
  • Quota: 100.000 richieste al mese

Piani Personalizzati: Sono disponibili altri piani con limiti differenti. Contatta il supporto per maggiori informazioni.

⚠️ Importante: Fai attenzione a non consumare tutta la tua quota nei primi tre giorni del mese. Pianifica l’utilizzo delle API per distribuire le richieste in modo uniforme durante l’intero periodo di fatturazione ed evitare di esaurire la quota troppo presto.

Misurazioni multiple

Alcuni dispositivi possono avere più sensori dello stesso tipo. Ad esempio, un dispositivo può avere:

  • Due sensori di temperatura (uno interno e uno esterno)

In questi casi:

  • Il campo measure sarà lo stesso (es. “temperature”)
  • Il campo sensor_type sarà differente (es. “in100-q1-r-rc0i” vs “sht40-ad1b-r2”)

Usa il parametro sensorType per filtrare un sensore specifico quando necessario.

Formato data

Tutte le date devono essere in formato ISO 8601 con fuso orario UTC:

  • Formato: YYYY-MM-DDTHH:mm:ssZ
  • Esempio: 2026-02-04T15:30:00Z

Granularita dei dati storici

L’endpoint /devices/{deviceId}/history supporta diverse granularità:

  • raw: Dati grezzi senza aggregazione
  • 15m: Dati aggregati ogni 15 minuti (media, min, max)
  • 1h: Dati aggregati su base oraria (media, min, max)
  • 1d: Dati aggregati su base giornaliera (media, min, max)

Paginazione

L’endpoint /devices/{deviceId}/history supporta la paginazione:

  • limit: Numero massimo di risultati (default: 100, max: 100)
  • offset: Numero di risultati da saltare (default: 0)
  • La risposta include le informazioni di paginazione nel campo pagination

Disponibilita dei dati

La disponibilità dei dati storici dipende dalla granularità e dalla data di installazione del sensore:

  • Data di inizio disponibilità dati: I dati sono disponibili a partire dalla data di installazione del sensore per ciascun dispositivo
  • Dati grezzi (raw): Disponibili per 30 giorni a partire dalla data corrente
  • File CSV di dati ad alta frequenza: Disponibili per 30 giorni a partire dalla data corrente (stessa retention dei dati grezzi)

Nota: Questa funzionalità è disponibile solo se disponi di dispositivi ad alta frequenza (es. sensori di motori). Se il tuo tenant/sito non dispone di dispositivi ad alta frequenza, l’API restituirà un messaggio di errore.

  • Dati aggregati a 15 minuti (15m): Disponibili per 90 giorni a partire dalla data corrente
  • Dati aggregati su base oraria (1h): Disponibili per 2 anni a partire dalla data corrente
  • Dati aggregati su base giornaliera (1d): Disponibili in modo permanente (nessuna scadenza)

Raccomandazioni:

  • Usa raw per analisi dettagliate recenti (ultimi 30 giorni)
  • Usa i file CSV ad alta frequenza per il download massivo di dati recenti (ultimi 30 giorni)
  • Usa 15m per i trend a medio termine (fino a 90 giorni)
  • Usa 1h per analisi a lungo termine (fino a 2 anni)
  • Usa 1d per analisi storiche oltre i 2 anni

Supporto

Per assistenza o domande, contatta il supporto tecnico.

Codici di stato HTTP

  • 200 OK: Richiesta completata con successo
  • 400 Bad Request: Richiesta malformata o parametri mancanti
  • 401 Unauthorized: API key mancante o non valida
  • 403 Forbidden: Accesso negato
  • 404 Not Found: Risorsa non trovata
  • 500 Internal Server Error: Errore interno del server

Dispositivi

Operazioni per interrogare i dispositivi IoT disponibili.

Questi endpoint ti permettono di:

  • Ottenere l’elenco dei dispositivi
  • Interrogare le misurazioni disponibili per ciascun dispositivo

Elenca dispositivi

Restituisce l’elenco dei dispositivi disponibili per la tua API key.

Comportamento:

  • Senza parametri: restituisce tutti i dispositivi disponibili
  • Con includeMeasures=true: include le misurazioni disponibili per ciascun dispositivo

Prestazioni:

  • Senza includeMeasures: query veloce, ideale per elenchi lunghi
  • Con includeMeasures=true: query più lenta, da usare solo quando necessario

Esempi di utilizzo:

  • Elenco semplice: GET /devices
  • Con misurazioni: GET /devices?includeMeasures=true

Autorizzazioni: ApiKeyAuth

Parametri query

includeMeasures boolean — Default: false — Esempio: includeMeasures=true

Se true, include le misurazioni disponibili per ciascun dispositivo nel campo available_measures.

Quando usarlo:

  • Quando hai bisogno di sapere quali misurazioni sono disponibili prima di effettuare chiamate ai dati
  • Quando vuoi mostrare agli utenti le opzioni disponibili

Quando NON usarlo:

  • Quando vuoi solo l’elenco dei dispositivi (più veloce)
  • Quando hai già informazioni sulle misurazioni disponibili

Risposte

  • 200 — Elenco dispositivi restituito con successo
  • 400 — Richiesta non valida. Cause comuni: parametri mancanti o malformati, valori fuori intervallo, formato data non valido, array vuoto o troppo grande
  • 401 — Non autorizzato, autenticazione fallita. Cause: API key mancante nell’header x-api-key, API key non valida o scaduta, API key non associata a un Usage Plan valido
  • 403 — Accesso negato, permessi insufficienti
  • 500 — Errore interno del server. Riprova la richiesta dopo qualche secondo; se il problema persiste, contatta il supporto fornendo il requestId se disponibile nei log

get /devices

Dati

Operazioni per accedere ai dati dei dispositivi.

Questi endpoint ti permettono di:

  • Ottenere l’ultimo valore disponibile per un dispositivo
  • Ottenere gli ultimi valori di più dispositivi in una singola chiamata
  • Interrogare i dati storici con diverse granularità
  • Filtrare per tipo di misurazione e sensore

Ultimo valore del dispositivo

Restituisce l’ultimo valore disponibile per un dispositivo specifico.

Comportamento in base ai parametri:

  • Senza parametri (GET /devices/{deviceId}/last): restituisce tutte le misurazioni dall’ultimo timestamp disponibile. Formato: oggetto con device_id, timestamp e array data. Utile quando vuoi vedere tutte le misurazioni simultanee
  • Con measure (GET /devices/{deviceId}/last?measure=temperature): restituisce solo quella misurazione. Se ci sono più sensori con lo stesso measure, li restituisce tutti. Formato: oggetto singolo o array (se più sensori)
  • Con measure e sensorType (GET /devices/{deviceId}/last?measure=temperature&sensorType=in100-q1-r-rc0i): restituisce solo quel sensore specifico. Formato: oggetto singolo

Esempi di utilizzo:

  • Tutte le misurazioni: GET /devices/aa:bb:cc:dd:ee:ff/last
  • Solo temperatura: GET /devices/aa:bb:cc:dd:ee:ff/last?measure=temperature
  • Sensore specifico: GET /devices/aa:bb:cc:dd:ee:ff/last?measure=temperature&sensorType=in100-q1-r-rc0i

Autorizzazioni: ApiKeyAuth

Parametri path

deviceId required string ^[0-9a-fA-F]{2}(:[0-9a-fA-F]{2}){5}$ — Esempio: aa:bb:cc:dd:ee:ff

ID del dispositivo (indirizzo MAC in formato XX:XX:XX:XX:XX:XX). Separatore: due punti (:). Case insensitive.

Parametri query

  • measure string — Esempio: measure=temperature. Filtra per tipo di misurazione. Valori accettati: qualsiasi tipo di misurazione restituito dai sensori (es. temperature, humidity, pressure, co2, battery_percentage, battery_voltage, rssi, a_current, b_current, c_current, total_current, a_voltage, b_voltage, c_voltage, a_act_power, b_act_power, c_act_power, total_act_power, ecc.) oppure "all" per restituire tutte le misurazioni. Il valore deve corrispondere esattamente al campo measure restituito dai sensori (case-sensitive)
  • sensorType string — Esempio: sensorType=in100-q1-r-rc0i. Filtra per tipo di sensore. Esempi: in100-q1-r-rc0i (sensore di temperatura interno), sht40-ad1b-r2 (sensore di temperatura esterno), dht22 (sensore umidità/temperatura). Nota: deve essere usato insieme a measure per essere efficace

Risposte

  • 200 — Ultimo/i valore/i restituito/i con successo
  • 400 — Richiesta non valida
  • 401 — Non autorizzato, autenticazione fallita
  • 403 — Accesso negato, permessi insufficienti
  • 404 — Risorsa non trovata. Cause: Device ID inesistente, dispositivo non accessibile con la tua API key, nessun dato disponibile per il dispositivo richiesto. Nota: se il dispositivo esiste ma non ha dati, riceverai comunque 404
  • 500 — Errore interno del server

get /devices/{deviceId}/last

Esempio di risposta (con measure e sensorType, oggetto singolo):

{
  "timestamp": "2026-02-04T15:30:00Z",
  "device_id": "aa:bb:cc:dd:ee:ff",
  "sensor_type": "in100-q1-r-rc0i",
  "measure": "temperature",
  "unit": "C",
  "value": 22.5
}

Ultimi valori di piu dispositivi

Restituisce gli ultimi valori di più dispositivi in una singola chiamata.

Vantaggi:

  • Riduce il numero di chiamate HTTP necessarie
  • Più efficiente quando si leggono dati da molti dispositivi
  • Mantiene la stessa logica di filtri di /devices/{deviceId}/last

Limitazioni:

  • Massimo 100 dispositivi per richiesta
  • Timeout più lungo per elenchi grandi

Comportamento:

  • Senza measure: restituisce tutte le misurazioni per ciascun dispositivo
  • Con measure: restituisce solo quella misurazione per ciascun dispositivo
  • Con measure e sensorType: restituisce solo quel sensore per ciascun dispositivo

Esempi di utilizzo:

  • Tutti i dispositivi, tutte le misurazioni: POST /devices/last/bulk con {"deviceIds": [...]}
  • Tutti i dispositivi, solo temperatura: POST /devices/last/bulk con {"deviceIds": [...], "measure": "temperature"}
  • Sensore specifico: POST /devices/last/bulk con {"deviceIds": [...], "measure": "temperature", "sensorType": "in100-q1-r-rc0i"}

Autorizzazioni: ApiKeyAuth

Request Body schema: application/json

  • deviceIds required Array of strings [ 1 .. 100 ] items — Elenco dei device ID da interrogare. Minimo: 1 dispositivo. Massimo: 100 dispositivi. Formato: array di stringhe (indirizzo MAC)
  • measure string — Filtra per tipo di misurazione (opzionale). Se omesso, restituisce tutte le misurazioni per ciascun dispositivo
  • sensorType string — Filtra per tipo di sensore (opzionale). Deve essere usato insieme a measure per essere efficace

Risposte

  • 200 — Ultimi valori restituiti con successo
  • 400 — Richiesta non valida
  • 401 — Non autorizzato, autenticazione fallita
  • 403 — Accesso negato, permessi insufficienti
  • 500 — Errore interno del server

post /devices/last/bulk

Esempio di richiesta:

{
  "deviceIds": ["aa:bb:cc:dd:ee:ff", "11:22:33:44:55:66", "ff:ee:dd:cc:bb:aa"]
}

Esempio di risposta:

{
  "results": [{}, {}],
  "count": 2,
  "requested": 2
}

Dati storici del dispositivo

Restituisce i dati storici di un dispositivo all’interno di un intervallo temporale specificato.

Granularità disponibili:

  • raw (default): Dati grezzi senza aggregazione. Ogni riga rappresenta una singola misurazione. Massima precisione temporale, più dati restituiti
  • 15m: Dati aggregati ogni 15 minuti. Ogni riga contiene media, minimo e massimo. Riduce significativamente il volume di dati
  • 1h: Dati aggregati su base oraria. Ogni riga contiene media, minimo e massimo. Ancora più compatto
  • 1d: Dati aggregati su base giornaliera. Ogni riga contiene media, minimo e massimo per il giorno. Volume di dati minimo

Paginazione:

  • Usa limit per controllare quanti risultati ottenere (max 100)
  • Usa offset per navigare tra le pagine
  • La risposta include pagination.hasMore per sapere se ci sono altri dati

Filtri:

  • measure: Filtra per tipo di misurazione
  • sensorType: Filtra per tipo di sensore (deve essere usato con measure)

Esempi di utilizzo:

  • Storico completo: GET /devices/{id}/history?startDate=...&endDate=...
  • Solo temperatura: GET /devices/{id}/history?startDate=...&endDate=...&measure=temperature
  • Sensore specifico: GET /devices/{id}/history?startDate=...&endDate=...&measure=temperature&sensorType=in100-q1-r-rc0i
  • Dati aggregati: GET /devices/{id}/history?startDate=...&endDate=...&granularity=1d

Autorizzazioni: ApiKeyAuth

Parametri path

deviceId required string ^[0-9a-fA-F]{2}(:[0-9a-fA-F]{2}){5}$ — Esempio: aa:bb:cc:dd:ee:ff. ID del dispositivo (indirizzo MAC)

Parametri query

  • startDate required string <date-time> — Esempio: startDate=2026-02-04T00:00:00Z. Data/ora di inizio dell’intervallo (ISO 8601, UTC)
  • endDate required string <date-time> — Esempio: endDate=2026-02-04T23:59:59Z. Data/ora di fine dell’intervallo (ISO 8601, UTC). Nota: deve essere successiva a startDate
  • granularity string — Default: "raw" — Enum: "raw" "15m" "1h" "1d". Granularità dei dati restituiti
  • measure string — Esempio: measure=temperature. Filtra per tipo di misurazione
  • sensorType string — Esempio: sensorType=in100-q1-r-rc0i. Filtra per tipo di sensore (deve essere usato con measure)
  • limit integer [ 1 .. 100 ] — Default: 100 — Esempio: limit=100. Numero massimo di risultati da restituire
  • offset integer >= 0 — Default: 0 — Esempio: offset=0. Numero di risultati da saltare (per la paginazione)

Risposte

  • 200 — Dati storici restituiti con successo
  • 400 — Richiesta non valida
  • 401 — Non autorizzato, autenticazione fallita
  • 403 — Accesso negato, permessi insufficienti
  • 404 — Risorsa non trovata
  • 500 — Errore interno del server

get /devices/{deviceId}/history

Esempio di risposta (granularity=raw):

{
  "data": [{}, {}, {}],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 96,
    "hasMore": true,
    "returned": 96
  },
  "granularity": "raw"
}

Dati ad alta frequenza

Operazioni per accedere ai file CSV dei dati ad alta frequenza dei dispositivi.

Questi endpoint ti permettono di:

  • Elencare i file CSV di dati ad alta frequenza disponibili
  • Scaricare i file CSV tramite URL S3 prefirmati
  • Filtrare i file per data, ora e dispositivo
  • Monitorare le quote giornaliere di download

Elenca file CSV ad alta frequenza

Restituisce un elenco dei file CSV disponibili per i dati ad alta frequenza dei dispositivi, con URL S3 prefirmati per il download.

⚠️ Importante: Questo endpoint è disponibile solo se disponi di dispositivi ad alta frequenza (es. sensori di motori). Se il tuo tenant/sito non dispone di dispositivi ad alta frequenza, l’API restituirà un messaggio di errore NoHighFrequencyDevices.

Sistema dati ad alta frequenza:

  • I file CSV vengono creati automaticamente ogni ora (al minuto 10) per l’ora precedente
  • Un file per dispositivo per ora (solo se esistono dati)
  • I file sono memorizzati in S3 e organizzati per tenant, dispositivo, data e ora
  • Sono inclusi solo i dispositivi contrassegnati come highfrequency = true

Retention dati: I file CSV di dati ad alta frequenza sono disponibili per 30 giorni (come i dati grezzi).

Quote di download:

  • Ogni tenant ha un limite giornaliero di download (backup_hf_daily_download_limit)
  • Il limite è condiviso tra tutte le API key/utenti all’interno del tenant
  • La quota si azzera a mezzanotte UTC
  • Ogni generazione di URL prefirmato conta ai fini del limite giornaliero

Comportamento di default (senza deviceId e senza hour):

  • Restituisce solo l’ultimo file disponibile per ciascun dispositivo (per la data selezionata, default: giorno corrente UTC)
  • Mantiene le risposte di dimensioni ridotte ed è ideale per i client di “sincronizzazione giornaliera”

Modalità giornata intera:

  • Per recuperare tutti i file del giorno per tutti i dispositivi, usa mode=day

Filtri:

  • date: Filtra per data specifica (YYYY-MM-DD). Default: giorno corrente
  • hour: Filtra per ora specifica (0-23)
  • deviceId: Filtra per dispositivo specifico (deve appartenere al tuo tenant)
  • mode: latest (default) o day

Formato risposta:

  • I file sono raggruppati per device_id, poi per ora
  • Ogni ora contiene un URL S3 prefirmato (valido per 15 minuti)
  • Le informazioni sulla quota mostrano limite giornaliero, utilizzo e download rimanenti

Casi di errore:

  • Se il tenant/sito non ha dispositivi ad alta frequenza: restituisce errore "NoHighFrequencyDevices"
  • Se la quota giornaliera è superata: restituisce 429 Too Many Requests
  • Se il dispositivo non appartiene al tenant: restituisce 403 Forbidden

Autorizzazioni: ApiKeyAuth

Parametri query

  • date string ^\d{4}-\d{2}-\d{2}$ — Esempio: date=2026-02-19. Data per cui interrogare i file di dati ad alta frequenza (formato YYYY-MM-DD). Default: giorno corrente (UTC)
  • hour integer [ 0 .. 23 ] — Esempio: hour=15. Ora per filtrare i file (0-23). Esempio: 15 per le 15:00
  • deviceId string ^[0-9a-fA-F]{2}(:[0-9a-fA-F]{2}){5}$ — Esempio: deviceId=ad:6a:f5:ae:c9:b5. Device ID per filtrare i file (formato indirizzo MAC). Nota: il dispositivo deve appartenere al tuo tenant
  • mode string — Default: "latest" — Enum: "latest" "day" — Esempio: mode=latest. Modalità di risposta: latest (default) restituisce solo l’ultimo file disponibile per ciascun dispositivo; day restituisce tutti i file dell’intera giornata (può essere voluminoso)

Risposte

  • 200 — Elenco file di dati ad alta frequenza restituito con successo
  • 400 — Parametri della richiesta non validi
  • 401 — Non autorizzato, autenticazione fallita
  • 403 — Vietato, permesso mancante o dispositivo non appartenente al tenant
  • 404 — Dispositivo non trovato
  • 429 — Quota giornaliera di download superata
  • 500 — Errore interno del server

get /backup_files_highfrequency

Esempio di risposta (successo con file):

{
  "files": {
    "ad:6a:f5:ae:c9:b5": {}
  },
  "quota": {
    "dailyLimit": 100,
    "usedToday": 3,
    "remaining": 97,
    "resetAt": "2026-02-20T00:00:00.000Z"
  }
}

Richiedi un preventivo

Estimated in 30 seconds. No obligation.