80 lines
2.2 KiB
Markdown
Executable File
80 lines
2.2 KiB
Markdown
Executable File
# Gateway letture acqua
|
|
|
|
## Obiettivo
|
|
|
|
NetGescon puo ricevere letture cumulative dei contatori acqua da un gateway esterno e salvarle nello stesso archivio operativo usato da `servizi-utenze` e dalla scheda `unita-immobiliare`.
|
|
|
|
## Configurazione
|
|
|
|
Impostare un token condiviso nell'ambiente applicativo:
|
|
|
|
```env
|
|
WATER_GATEWAY_TOKEN=<token-gateway>
|
|
```
|
|
|
|
Il gateway deve inviare il token in uno di questi modi:
|
|
|
|
- header `X-Netgescon-Water-Token`
|
|
- bearer token `Authorization: Bearer ...`
|
|
- query string `?token=...`
|
|
|
|
In ambiente non locale, se il token non e configurato l'endpoint risponde `503`.
|
|
|
|
## Endpoint
|
|
|
|
```http
|
|
POST /api/netgescon/v1/water-meter/readings
|
|
Content-Type: application/json
|
|
X-Netgescon-Water-Token: <token-gateway>
|
|
```
|
|
|
|
Payload minimo:
|
|
|
|
```json
|
|
{
|
|
"device_id": "GW-ACEA-0001",
|
|
"serial": "WTTS115224000400",
|
|
"value": 123.456,
|
|
"read_at": "2026-06-27T10:00:00+02:00",
|
|
"unit": "mc"
|
|
}
|
|
```
|
|
|
|
Campi accettati:
|
|
|
|
- `device_id`: identificativo dispositivo gateway, preferenziale per aggancio unita;
|
|
- `serial`: seriale/matricola contatore acqua dell'unita;
|
|
- `unita_id`: opzionale, utile per test o gateway gia mappati;
|
|
- `value`: lettura cumulativa;
|
|
- `read_at`: data/ora lettura;
|
|
- `unit`: unita di misura, default `mc`;
|
|
- `battery`, `rssi`, `payload`: dati diagnostici opzionali.
|
|
|
|
## Aggancio unita
|
|
|
|
La scheda `admin-filament/unita-immobiliare?unita_id=...` espone in modifica:
|
|
|
|
- `acqua_contatore_seriale`
|
|
- `acqua_gateway_device_id`
|
|
|
|
L'API cerca l'unita in questo ordine:
|
|
|
|
1. `unita_id`, se inviato;
|
|
2. `acqua_gateway_device_id = device_id`;
|
|
3. `acqua_contatore_seriale = serial`.
|
|
|
|
Se l'unita viene trovata e non esiste ancora un servizio acqua attivo nello stabile, viene creato un servizio `Acqua - gateway contatori`.
|
|
|
|
## Salvataggio lettura
|
|
|
|
La lettura viene salvata in `stabile_servizio_letture` con:
|
|
|
|
- `canale_acquisizione = gateway`
|
|
- `rilevatore_tipo = gateway_iot`
|
|
- `lettura_fine = value`
|
|
- `lettura_inizio` e `lettura_precedente_valore` dalla lettura precedente della stessa unita/servizio
|
|
- `consumo_valore = max(0, lettura_fine - lettura_precedente)`
|
|
- `raw.source = water_meter_gateway`
|
|
|
|
Queste righe diventano visibili nella scheda unita e nella pagina `condomini/servizi-utenze`, e potranno essere confrontate con le fatture acqua/ACEA per riparti piu precisi.
|