API/PuntidiControlloMisure
Elenco dei punti di controllo di un impianto
Nell'header delle richieste va specificata l'autenticazione
X-API-TOKEN: {chiave da 128 caratteri fornita per l'impianto in questione)
Ogni impianto ha un set di punti di controllo standardizzati, ci possono essere differenze tra impianti biogas e biometano. Ogni punto di controllo può a sua volta avere più misurazioni.
Per ogni misura si potranno inserire delle letture a frequenze variabili. Tali frequenze sono descritte in ogni misura, ma non è vincolante.
I dati di una misura potranno essere:
- letture singole puntuali
- valori progressivi (contatori)
- campionamenti di un periodo con un valore medio.
Queste caratteristiche possono essere lette nell'anagrafica delle misure stesse.
Ogni punto di controllo ha un codice di questo tipo:
a.bb
a cui seguono le misurazioni con un ulteriore codice:
in totale una misura sarà definita da un codice che comprende il punto di controllo e la misura stessa.
Esempio
2.04.a
2.04 -> punto di controllo
a -> misura
Elenco Punti di Controllo
GET https://smartbiogas.it/api/v1/controlpoints
Risultato: Json con un array di risultati
[
{
"plant_control_points_id": idPuntoDiControllo,
"f_cod": "Codice testuale (formato n.mm)",
"f_json_description": "{\"it\":\"descrizione in italiano\",\"en\":\"Descrizione in inglese\",\"es\":\"...\",\"fr\":\"...\"}"
},
{
"plant_control_points_id": 10401,
"f_cod": "2.08",
"f_json_description": "{\"it\":\"BG alla caldaia\",\"en\":\"Biogas to the boiler\",\"es\":\"Biogas to the boiler\",\"fr\":\"Biogas to the boiler\"}"
},
...
]
Dati punto di controllo e misure collegate
Ad ogni punto di controllo possono essere associate più misure. Ogni misura avrà uno storico di letture che saranno i dati veri e propri nel tempo.
GET https://smartbiogas.it/api/v1/controlpoints/{idPuntoDiControllo}
esempio: https://smartbiogas.it/api/v1/controlpoints/10335
Risultato: Stesso Json sopra di un unico punto di controllo che contiene un elenco chiamato misure.
[
{
"plant_control_points_id": idPuntoDiControllo,
"f_cod": "Codice testuale (formato n.mm)",
"f_json_description": "{\"it\":\"descrizione in italiano\",\"en\":\"Descrizione in inglese\",\"es\":\"...\",\"fr\":\"...\"}",
"measures": [
{
"plant_control_points_misure_id": idMisura (collegata a questo impianto / Punto di controllo),
"f_description": "Descrizione testuale",
"frequency_unita_misura_id": idUnitàDiMisura (della frequenza di campionamento: del gruppo Tempo),
"f_frequency": valore della frequenza,
"measure_unita_misura_id": idUnitàDiMisura (dei valori della misura),
"measure_type_id": idTipoMisura (vedi Tipi di misurazioni),
"f_cod_misura": "Codice completo di punto di controllo e misura"
},
{
"plant_control_points_misure_id": 21042,
"f_description": "Produzione EE FV1",
"frequency_unita_misura_id": 32,
"f_frequency": "1.0000",
"measure_unita_misura_id": 25,
"measure_type_id": 1,
"f_cod_misura": "2.12.a"
},
Ricerca Punti di controllo
GET https://smartbiogas.it/api/v1/controlpoints?f_cod={codice o parte del codice}
esempio: https://smartbiogas.it/api/v1/controlpoints?f_cod=2.13
Inserimento di una lettura
Una volta individuata una misura (plant_control_points_misure_id) e il relativo punto di controllo (plant_control_points_id) è possibile inserire una lettura nello storico
L'unità di misura della lettura inviata dal sensore deve essere deciso a monte e configurato quindi su SB. E' possibile capire l'unità di misura corrente tramite le api nei dati della misura della quale si inserisce la lettura.
POST https://smartbiogas.it/api/v1/controlpoints/{idPuntoDiControllo}/measures/{idMisura}/readings
esempio: https://smartbiogas.it/api/v1/controlpoints/10431/measures/20583/readings
La chiamata deve avere, oltre all'autenticazione X-API-TOKEN, un JSON così formato
{
"f_data_lettura_inizio_campione":DATETIME (nullable) "data/ora in formato ISO",
"f_data_lettura": DATETIME "data/ora in formato ISO",
"f_rilevatore": TEXT "Identificazione dell'operatore",
"f_lettura": DECIMAL "misura numerica",
"f_note":TEXT "Eventuali note",
"plant_inspections_id": INT "ID della visita (lasciare -1 o non mettere proprio il campo in caso di misura non inserita per visite/ispezioni),
"analisi_id": INT "ID dell'analisi (lasciare -1 o non mettere proprio il campo in caso di misura non da analisi)
}
Esempio di misura in un periodo di 1 ora:
{
"f_data_lettura_inizio_campione":"2006-01-01 00:00:00",
"f_data_lettura":"2026-01-01 01:00:00",
"f_rilevatore":"test api",
"f_lettura": 15.42,
"f_note":"15.42 kW in un ora",
"analisi_id":-1
}
Esempio di misura puntuale
{
"f_data_lettura_inizio_campione":"",
"f_data_lettura":"2026-01-01 23:59:59",
"f_rilevatore":"",
"f_lettura": 15.42,
"f_note":"A fine giornata il contatore segnava 15.42 kw",
"analisi_id":-1
}
Il sistema deve ritornare un Json come risultato:
{
"error_code": vedi Codici errore API,
"reading_id": idLettura(torna l'id appena inserito),
"message": "Messaggio per capire l'eventuale errore"
}