Panoramica dell'API

La piattaforma Mirox espone un'API REST che ti consente di integrare dati degli impianti, automazione e reportistica nei tuoi sistemi e flussi di lavoro. Tutto ciò che fa l'interfaccia web si basa sugli stessi endpoint pubblici, quindi puoi pilotare la piattaforma in modo programmatico.

Documentazione interattiva

La specifica completa dell'API viene generata in tempo reale dalla piattaforma in esecuzione ed è disponibile in due viste interattive:

  • Swagger UI su /docs — un riferimento interattivo con un costruttore di richieste integrato per provare le chiamate direttamente nel browser.
  • ReDoc su /redoc — la stessa specifica in un layout ottimizzato per la lettura e la navigazione.

Entrambe le viste ti permettono di esplorare ogni endpoint disponibile, i suoi parametri, il corpo della richiesta e il formato della risposta. Sono il riferimento autorevole e sempre aggiornato su ciò che l'API può fare.

Come è organizzata l'API

Gli endpoint dell'API sono raggruppati in base a ciò su cui operano, e ogni percorso è versionato (ad esempio /v1/...). Le aree comuni includono:

  • Impianti, portfolio e componenti — leggi e gestisci i tuoi siti monitorati e la loro struttura.
  • Metriche ed esportazione dati — esporta qualsiasi metrica come serie temporale, in CSV oppure, con format=json, in JSON, e definisci metriche tue.
  • Eventi, ticket e report — recupera segnali rilevati automaticamente, attività di follow-up gestite dalle persone e report generati.
  • Organizzazione, cooperazioni e accessi — gestisci membri, condivisione e token di integrazione.

L'accesso a ogni endpoint è regolato dal tuo ruolo e dai tuoi permessi. Una chiamata restituisce solo gli impianti e i dati che hai diritto di vedere, quindi l'API applica le stesse regole di accesso dell'interfaccia.

Non tutto è elencato in /docs

Alcuni gruppi di route sono intenzionalmente nascosti dalla specifica pubblicata, quindi non appariranno in /docs o /redoc anche se funzionano:

  • Endpoint amministrativi — funzioni di amministrazione della piattaforma riservate al personale Mirox.
  • Route di assegnazione dei dispositivi (/v1/device).

Se devi integrarti con una di queste, contatta il supporto Mirox per assistenza.

Dati di serie temporali

Per i dati di serie temporali usa la Metric Export API. Esporta ogni metrica della raccolta — impianto, componente, sensore, turbina e livello di batteria, e le metriche della tua organizzazione — con passi da 1 minuto a un anno. Una richiesta GET risponde in CSV; format=json risponde in JSON.

Metriche di organizzazione (MetricsQL)

Le metriche definite in Metriche hanno un proprio gruppo di rotte, /v1/report/metric: elencare, leggere, creare, aggiornare ed eliminare una metrica, POST /v1/report/metric/validate per verificare un'espressione, POST /v1/report/metric/preview per eseguirla su un impianto e GET /v1/report/metric/building-blocks per le serie e i valori configurati che un'espressione può leggere. Queste metriche alimentano allo stesso modo i report e il Metric Export. Le formule MiroxQL sono le colonne calcolate dell'esportazione legacy; le loro rotte restano disponibili.

Per iniziare

Per chiamare l'API ti autentichi con un token API associato a un gruppo di permessi. Consulta la guida Token API per scoprire come creare, definire l'ambito e ruotare i token, quindi usali per effettuare le richieste.

Apri in Mirox

Crea e gestisci i tuoi token in Profilo — apri il menu del profilo (in alto a destra) ▸ Profilo e usa la sezione token API.

Per codice di integrazione end-to-end eseguibile, consulta l'esempio pratico Generatore di report esterno.

Funzionalità correlate