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
Stiamo sostituendo i codici con alternative parlanti. ad esempio per la pesa in entrata PEIN
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
PEIN.MAKG
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_cod_2": "Codice testuale nuovo: TESTO (40)",
"f_json_description": "{\"it\":\"descrizione in italiano\",\"en\":\"Descrizione in inglese\",\"es\":\"...\",\"fr\":\"...\"}"
},
{
"plant_control_points_id": 10401,
"f_cod": "2.08",
"f_cod_2": "CALD",
"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_cod_2": "Codice testuale TESTO(40)",
"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": "Vecchio codice completo di punto di controllo e misura"
"f_cod_misura_2": "Nuovo 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"
"f_cod_misura": "GENS.KW"
},
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
GET https://smartbiogas.it/api/v1/controlpoints?f_cod_2={codice o parte del codice}
esempio: https://smartbiogas.it/api/v1/controlpoints?f_cod_2=PEIN
Ricerca diretta Misura per codice IT
Per facilitare l'inserimento delle misure note, sarà possibile ottenere gli ID di punto di controllo e misura dell'impianto utilizzando una ricerca per codice interno che comprende sia il punto di controllo che la misura.
ad esempio:
Punto di controllo PE (pesa in)
Misura: WQ.IN (massa in ingresso (t)
https://smartbiogas.it/api/v1/controlpoints?f_direct_cod=PE-WQ.IN
Risultato
{
"plant_control_points_id": 10415,
"plant_control_points_misure_id": 40252
}
In questo modo sapendo il codice diretto si può risalire agli id da usare per l'inserimento della lettura spiegato qui di seguito
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"
}