Indice del Documento
Responsabilità del caricamento Dati
Descrizione del flusso autorizzativo Utenti
Modalità di inserimento di programmi di controllo
Descrizione dei parametri richiesti per programmi di controllo
Caricamento tramite Interfaccia
Caricamento Programmi di Controllo
Caricamento tramite File Excel
Caricamento Tramite Webservice
Caricamento Singolo Punto di Campionamento
Caricamento JSON in modalità batch
Formato File dei Programmi di Controllo
Interrogazione stato elaborazioni in batch
Tipologie dei Punti di Campionamento
Canale di Assistenza e supporto
Contesto di Riferimento
AnTeA – Anagrafe Territoriale dinamica delle Acque potabili – è una piattaforma digitale concepita per l’acquisizione, controllo, gestione, analisi dei dati sulle acque destinate al consumo umano in Italia, in conformità al D.Lgs 23 febbraio 2023, n. 18, Attuazione della direttiva (UE) 2020/2184 del Parlamento europeo e del Consiglio, del 16 dicembre 2020.
AnTeA è strutturata per garantire l’interoperabilità dei dati e la condivisione degli stessi con i principali soggetti istituzionali e i gestori Idropotabili che presiedono all’accesso all’acqua e alla garanzia di sicurezza delle acque destinate al consumo umano. La cooperazione vede coinvolte diverse entità, quali il Ministero della Salute, il Ministero dell’Ambiente e della Sicurezza Energetica (MASE), l’Istituto Superiore di Sanità (ISS) – Centro Nazionale per la Sicurezza delle Acque (ISS – CeNSiA), l’Autorità di Regolazione per Energia, Reti e Ambiente (ARERA), l’Istituto Nazionale di Statistica (ISTAT), le Regioni, i Sindaci, l’Istituto Superiore per la Protezione e la Ricerca Ambientale (ISPRA) e il Sistema Nazionale per la Protezione dell’Ambiente (SNPA), gli Enti di Governo dell’Ambito Territoriale Ottimale (EGATO). Le Regioni sono responsabili della registrazione dei punti di campionamento nei piani di controllo, mentre le ASL e i Gestori Idropotabili sono incaricati dell’inserimento dei risultati dei controlli.
Le principali finalità di AnTea consistono nell’assicurare la disponibilità delle informazioni sull’accesso all’acqua e sulla qualità delle acque al punto di utilizzo – a partire dalle risorse idriche nell’ambiente e lungo l’intera filiera di trattamenti e distribuzione. L’obiettivo principale quindi è facilitare la trasmissione informatizzata dei risultati dei controlli interni ed esterni sulla qualità delle acque. Le Regioni, le ASL e i Gestori Idropotabili sono chiamati a collaborare per monitorare costantemente la qualità delle acque e garantire il rispetto dei parametri normativi stabiliti a livello nazionale ed europeo. In questo contesto, AnTea rappresenta una piattaforma cruciale per l’acquisizione, l’elaborazione, l’analisi e la condivisione dei dati relativi ai controlli effettuati su campioni d’acqua prelevati in diverse aree geografiche. Il sistema facilita la comunicazione, l’integrazione e la condivisione delle informazioni tra le autorità ambientali e sanitarie a livello nazionale, regionale e locale, oltre che con gli operatori del settore idropotabile, migliorando la cooperazione e la risposta tempestiva a eventuali problemi di qualità dell’acqua. Un altro obiettivo cruciale è garantire un idoneo accesso pubblico alle informazioni, promuovendo la trasparenza e consentendo ai cittadini di essere informati sulla qualità dell’acqua che consumano. AnTea assicura inoltre che le informazioni e i dati siano disponibili, aggiornati e accessibili alla Commissione europea, all’Agenzia Europea per l’Ambiente e al Centro europeo per la prevenzione e il controllo delle malattie, permettendo un monitoraggio e una risposta coordinata a livello europeo. La piattaforma facilita anche lo scambio di informazioni con ARERA, ISTAT e altre istituzioni nazionali, nonché con l’Organizzazione Mondiale della Sanità (OMS) e altre organizzazioni internazionali, per le rispettive finalità di competenza. Questo scambio è vitale per garantire che tutte le parti interessate dispongano delle informazioni necessarie per monitorare, gestire e migliorare la qualità delle acque destinate al consumo umano, contribuendo così alla tutela della salute pubblica e dell’ambiente a livello globale.
L’implementazione di AnTea mira a standardizzare e ottimizzare il processo di trasmissione dei dati, tra i quali:
- Dati sulle informazioni al pubblico sulle misure adottate per migliorare l’accesso all’acqua;
- Dati sulle valutazioni e gestioni del rischio delle aree di alimentazione per i punti di prelievo di acque da destinare al consumo umano;
- Dati sulle valutazioni e gestioni del rischio dei sistemi di distribuzione idrica interni;
- Dati sui risultati dei controlli volti a verificare la qualità delle acque destinate al consumo umano;
- Dati e informazioni sugli incidenti attinenti all’acqua destinata al consumo umano che hanno generato un potenziale rischio per la salute umana;
- Dati e informazioni su tutte le deroghe concesse ai valori di parametro fissati dal D.Lgs18/2023.
La piattaforma facilita l’inserimento dei dati tramite interfaccia utente, file di caricamento e API, gestendo grandi volumi di dati e automatizzando il processo per ridurre errori. La sicurezza e la tracciabilità sono garantite tramite autenticazione digitale, con un sistema di autorizzazione gerarchica che assicura operazioni qualificate. L’integrazione con un sistema di gestione delle identità centralizzato permette di gestire credenziali e permessi, migliorando la protezione dei dati. La piattaforma rispetta i requisiti normativi, assicurando una raccolta dati accurata e tempestiva. L’uso di un codice unico per ogni punto di campionamento garantisce tracciabilità e integrità dei dati.
Definizioni e Abbreviazioni
| Acronimo | Descrizione |
|---|---|
| DB | Database |
| IAM | Identity and Access Management |
| PSN | Polo Strategico Nazionale |
| AnTeA | Anagrafe Territoriale dinamica delle Acque potabili |
| PSA | Piani di Sicurezza dell’Acqua |
| WSZ | Water Supply Zone, Zone di Fornitura Idrica |
| ISS | Istituto Superiore di Sanità |
| CeNSiA | Centro nazionale Sicurezza delle Acque |
| ARERA | Autorità di Regolazione per Energia Reti e Ambiente |
| ATO | Ambito Territoriale Ottimale |
| EGATO | Ente di Governo dell’Ambito Territoriale Ottimale |
| GUI | Graphical User Interface – Interfaccia Grafica |
Scopo del Documento
Lo scopo principale di questa RFC è illustrare il quadro di cooperazione applicativa necessario tra le regioni e il sistema AnTeA gestito dall’ISS al fine di definire all’interno di AnTeA i programmi di controllo.
I processi saranno progettati per adattarsi alle diverse competenze informatiche e disponibilità dei vari attori, consentendo loro di implementare un flusso di dati informatizzato in maniera efficace ed efficiente.
Il documento delineerà inoltre i processi per ottenere le credenziali necessarie per accedere al portale e per l’inserimento dei dati all’interno della piattaforma.
Responsabilità del caricamento Dati
Descrizione del flusso autorizzativo Utenti
L’autorizzazione degli utenti sulla piattaforma Antea di produzione avverrà tramite una richiesta di accesso, che dovrà essere presentata dal responsabile della regione. Questa richiesta sarà validata e autorizzata dal Censia. Una volta ottenuta l’autorizzazione, l’utente potrà autenticarsi tramite SPID (Sistema Pubblico di Identità Digitale) e CIE (Carta d’Identità Elettronica).
Il responsabile della regione avrà inoltre la possibilità di delegare altri dipendenti della stessa azienda o di altre aziende al caricamento dei punti di campionamento. In base ai permessi e alle autorizzazioni fornite, sarà possibile operare nelle proprie aree di competenza. Questo sistema garantisce che solo gli utenti autorizzati possano accedere e gestire le funzionalità della piattaforma Antea, assicurando al contempo la tracciabilità e la sicurezza delle operazioni svolte.
Per accedere all’ambiente di test si veda paragrafo Ambiente di Test.
Modalità di inserimento di programmi di controllo
I programmi di controllo da inserire nella piattaforma corrispondono all’insieme di tutti i punti di campionamento con tutte le informazioni relative e necessarie, ovvero le sedi designate per i prelievi finalizzati ai controlli delle acque.
Le opzioni disponibili per l’inserimento dei programmi di controllo includono:
- Interfaccia Grafica Utente (GUI):
- Inserimento Singolo : attraverso l’interfaccia della piattaforma, gli utenti possono aggiungere i punti manualmente, uno alla volta.
- Caricamento tramite file Excel: permette l’importazione di dati in massa utilizzando fogli di calcolo Excel. Il formato del file è definito tra gli allegati.
- API:
- Caricamento tramite JSON (Elaborazione in Batch): permette agli enti di inserire i piani di controllo all’interno della piattaforma attraverso un unico file JSON contenente tutti i dati.
- Caricamento Singolo: questa modalità offre la flessibilità di aggiungere dati uno per volta attraverso API, adatta per l’integrazione di sistemi informatici esterni avanzati.
Nelle sezioni successive del documento, verranno fornite specifiche dettagliate e linee guida sui formati accettati per l’inserimento dei dati.
Utilizzo API
Al fine di garantire una gestione efficiente e sicura delle informazioni è fortemente raccomandato l’utilizzo di API/REST con formato JSON.
Questi metodi consentono un’integrazione rapida tra i sistemi informatici e permettono di automatizzare il flusso dei dati, riducendo il rischio di errori umani e migliorando la tempestività degli interventi in caso di problemi. Le API REST, in particolare, facilitano lo scambio di informazioni in tempo reale e la scalabilità futura del sistema, assicurando che i dati siano accessibili e condivisi in modo standardizzato e sicuro.
Al contrario, l’uso di file Excel dovrebbe essere limitato a quei gestori che non dispongono ancora di strumenti informatizzati. Excel, sebbene diffuso, non è ottimale per la gestione di dati complessi come quelli del progetto AnTeA, perché non garantisce lo stesso livello di flessibilità e interoperabilità. Dovrebbe essere considerato solo come una soluzione temporanea, mentre si promuove la transizione verso metodi più moderni, come l’uso di API e formati dati strutturati.
Schema concettuale
Illustriamo di seguito lo schema dei dati che saranno inviati in piattaforma dai vari attori coinvolti nel processo. Il Modello Entità Relazione (ER) del sistema e la relativa descrizione granulare dei dati in esso contenuti forniranno una struttura dati chiara per guidare la raccolta, l’inserimento e l’analisi dei parametri rilevanti per i Programmi di Controllo.
Modello Entità Relazione (ER)
Il modello ER illustrato di seguito fornisce un quadro strutturato per la gestione dei dati nel contesto della piattaforma AnTeA. In esso si nota che i Programmi di controllo sono composti da N punti di campionamento e ad ognuno di essi sono collegati N “Risultati dei Controlli” Interni o Esterni.
Lo scopo del seguente documento è soltanto il caricamento dei Piani di controllo, mentre per i Risultati dei Controlli si rimanda ad un’altra RFC.
Descrizione dei parametri richiesti per programmi di controllo
Nella tabella 1, riportata di seguito, sono dettagliati tutti i parametri richiesti in fase di inserimento dei dati che compongono i punti di Campionamento.
| Nome Campo | Obbl. | Formato | Note |
|---|---|---|---|
| uuid | SI | string | Unique id del punto di campionamento da generare secondo le specifiche indicate nel paragrafo Codice di Riferimento Unico |
| istatRegione | SI | integer | Codice Istat della regione di riferimento del punto di campionamento indicato |
| istatComune | SI | integer | Codice Istat del comune di riferimento del punto di campionamento indicato |
| tipoPuntoCampionamento | SI | string | Tipologia del punto di controllo. Vedi paragrafo Tipologie dei Punti di Campionamento |
| idPuntoCampionamento | SI | string | identificativo del punto di campionamento coerente con quanto inserito nel campo uuid |
| idAreraAto | SI | integer | Codice Arera dell’ATO di riferimento |
| idAreraGestore | SI | integer | Codice Arera del gestore Idropotabile responsabile del punto di campionamento |
| codiceAcquedotto | SI | string | Codice di riferimento dell’acquedotto |
| wsz | string | Nome della Water Supply Zone di riferimento | |
| progressivoLineAcquedottistica | integer | Numero progressivo della linea acquedottistica associata al punto di campionamento. | |
| coordinateEPSG4326lat | SI | decimal | Latitudine nel sistema di riferimento WGS84 (EPSG::4326). |
| coordinateEPSG4326lon | SI | decimal | Longitudine nel sistema di riferimento WGS84 (EPSG::4326). |
| coordinateEPSG4326z | SI | decimal | Altezza nel sistema di riferimento WGS84 (EPSG::4326). |
| previsioneAbitantiServiti | integer | Stima del numero di abitanti serviti dal punto di campionamento. Vedi Nota. | |
| previsionePortata | decimal | Stima della portata del punto di campionamento. Vedi Nota. | |
| descrizionePunto | string | Descrizione dettagliata del punto di campionamento. E’ un elemento opzionale, utile per capire dove si sta prelevando attraverso una definizione che il gestore riterrà più appropriata; | |
| note | string | Eventuali note aggiuntive o osservazioni pertinenti sul punto di controllo. | |
| numeroCampionamentoAnnuoInternoPrevisto | SI | integer | numero previsto di campionamenti annuali nel punto di campionamento (controllo interno) |
| numeroCampionamentoAnnuoEsterniPrevisto | SI | integer | numero previsto di campionamenti annuali nel punto di campionamento (controllo esterno) |
| dataInizioValidita | SI | date | Data di inizio validità del punto di campionamento |
| dataFineValidita | SI | date | Data di fine validità del punto di campionamento |
Tabella 1 Parametri del Punto di Campionamento
Per ogni punto di campionamento, è essenziale stabilire un intervallo di date di validità entro cui devono essere effettuati i prelievi effettivi. Questo garantisce che i campionamenti siano eseguiti in un periodo temporale definito e regolamentato, assicurando la coerenza e la rilevanza dei dati raccolti. Una volta che l’intervallo di validità scade, non è più possibile aggiungere controlli o eseguire nuovi prelievi per quel punto di campionamento. Ciò impedisce l’inserimento di dati obsoleti o non conformi, contribuendo a mantenere l’integrità e l’accuratezza del processo di campionamento.
Come si evidenzia dai campi sopra richiesti nel caricamento degli identificativi dei punti di campionamento in coerenza con le direttive ARERA, dovranno essere implementati elementi di caratterizzazione del sistema acquedottistico e dati di portata che dovranno essere congruenti con i dati di popolazione servita.
previsionePortata: se si sta caratterizzando una rete magliata chiusa, è possibile identificare in ogni nodo la portata transitante e il suo verso in funzione del comportamento simulato della rete in condizioni medio annue. Salvo diverse motivate scelte del gestore, si potrebbero identificare le portate in transito in condizioni di funzionamento ordinario del sistema acquedottistico. Si tratta di previsioni, in quanto dati stimati per il regime idrico che il gestore ritiene più significativo; [l’unità di misura è m³/anno]
previsioneAbitantiServiti: attraverso la stima delle portate, è facile stimare la popolazione servita come rapporto tra i volumi immessi in rete e gli abitanti residenti e fluttuanti nelle diverse Zone di Fornitura (WSZ).
Codice di Riferimento Unico
Ciascun punto di campionamento sarà identificabile mediante un codice di riferimento unico a livello nazionale (uuid), che integrerà diversi elementi informativi. Il codice univoco sarà costituito da quattro campi alfanumerici:
- Il Codice Istat relativo alla Regione;
- Il Codice Istat relativo al Comune;
- Un codice identificativo della specificità del punto di campionamento (Dettagliati nel paragrafo Tipologie dei Punti di Campionamento )
- Un Codice progressivo attribuito per ogni punto di controllo di un singolo Comune.
Questi dati saranno collegati tra loro tramite il simbolo “_”.
Ecco un esempio di codice punto di campionamento per un punto di interesse nella regione Lazio, specificamente per il Comune di Roma:
- Codice Istat Regione (es. Regione Lazio): 12 (Il campo deve essere formattato in modo da avere sempre due cifre, aggiungendo uno zero davanti se necessario);
- Codice Istat Comuni (es. Comune di Roma): 058091;
- Tipologia del Punto di prelievo (es. Serbatoio Interrato): D1;
- Numero del Punto di prelievo assegnato (alfanumerico max 32 char): 121;
Il Codice Univoco (uuid) risultante per il punto di campionamento esemplificativo sarà:
12_058091_SE_121
Tutti i dati presenti nei quattro campi dell’uuid dovranno essere soltanto caratteri alfanumerici maiuscoli e non sarà permesso alcun simbolo speciale.
Espressione regolare di riferimento:
^[A-Z0-9]+$
Ambiente di Test
Al fine di supportare gli enti nella transazione e supporto della seguente RFC si rende disponibile un ambiente di test che permetterà agli interlocutori di testare il funzionamento del portale, i formati di interscambio e le API messe a disposizione.
Per accedere all’ambiente di test, è necessario richiedere le credenziali inviando una email con i seguenti dettagli:
- Codice Istat della Regione;
- Nome e Cognome del richiedente;
- PDF del documento d’identità;
- Email di riferimento, che deve appartenere al dominio dell’ente.
La richiesta deve essere inviata all’indirizzo email: registrazione.antea.test@we-com.it
In risposta, verranno forniti:
- Username
- Password
Quest’ultimi potranno essere utilizzati per accedere all’ambiente di test di AnTeA.
Caricamento tramite Interfaccia
Sarà implementata un’interfaccia per il caricamento dei Programmi di controllo tramite la quale sarà possibile inserire e consultare i dati granularmente.
Caricamento Programmi di Controllo
Accedendo al menù laterale alla voce “Programmi di controllo” sarà possibile consultare l’elenco dei Punti di controllo inseriti nella piattaforma AnTeA.
Selezionando il pulsante + in basso a sinistra sarà possibile inserire un nuovo punto di campionamento.
Di seguito alcuni screen delle fasi di inserimento dei dati tramite GUI.
Aggiornamento validità dei Punti di Campionamento
È possibile procedere al rinnovo dei punti di campionamento scaduti seguendo i passaggi descritti di seguito:
-
- Aprire il menu laterale: Accedere al menu laterale e selezionare la voce “Punti di campionamento scaduti”.
- Visualizzazione dei punti scaduti: Verrà visualizzata una pagina contenente una tabella con tutti i punti di campionamento che sono scaduti o non ancora validi.
- Selezione dei punti da aggiornare: Nella parte inferiore della tabella è presente una colonna denominata “Seleziona”. Utilizzare le checkbox per selezionare i punti di campionamento che si desidera aggiornare.
- Modifica della validità: Dopo aver selezionato i punti da aggiornare, cliccare sull’icona con una matita, posizionata in basso a destra. Si aprirà un pannello laterale in cui sarà possibile inserire il nuovo intervallo di validità per i record selezionati.
- Salvataggio delle modifiche: Una volta inserito il nuovo intervallo di validità, cliccare sul pulsante “Salva” per aggiornare i record selezionati.
- Aprire il menu laterale: Accedere al menu laterale e selezionare la voce “Punti di campionamento scaduti”.
Caricamento tramite File Excel
Per facilitare il processo di inserimento dei punti di campionamento, è possibile utilizzare un file Excel per il caricamento automatico all’interno della piattaforma. Questa operazione dovrà essere eseguita attraverso un’interfaccia grafica, progettata per garantire facilità e efficienza nel trasferimento delle informazioni.
Il file Excel deve essere preparato seguendo uno specifico formato, un esempio del quale è disponibile negli allegati al presente documento. È essenziale che la disposizione delle colonne nel file Excel rimanga invariata per assicurare un corretto riconoscimento ed elaborazione dei dati da parte del sistema.
La prima riga del file deve contenere le intestazioni di colonna, essenziali per mappare correttamente i dati ai rispettivi campi nella piattaforma. È importante notare che i parametri definiti come obbligatori nella tabella descrittiva dei campi devono essere presenti nel file Excel, altrimenti il caricamento potrebbe fallire o risultare incompleto.
Il file da caricare deve essere in formato .xlsx.
Aggiormento tramite File Excel
Si fa presente che NON è possibile aggiornare i campi che compongono la chiave del punto: “uuid”, “istatRegione”, “istatComune”, “tipoPuntoCampionamento”, “idPuntoCampionamento”, “idAreraAto”, “idAreraGestore”. Per aggiornare questi dati è necessario inserire un nuovo punto di campionamento
Caricamento Tramite Webservice
Il processo di caricamento attraverso API si conforma agli standard dei webservice REST, incorporando l’autenticazione OPENID per garantire la sicurezza. Questo implica l’uso di chiamate HTTPS, impiegando metodi specifici predefiniti, per ottenere le informazioni desiderate che dettaglieremo di seguito nel documento.
In ogni chiamata illustrata nel documento sarà utilizzata la variabile $API_SERVER$ che andrà sostituita con l’ambiente di riferimento specifico:
Endpoint API
| Ambiente | Link |
|---|---|
| Test | antea.iss.it/test/api/ |
| Produzione | antea.iss.it/api/ |
Tabella 2 Elenco Ambienti
Endpoint IAM
Il webserver IAM sarà incaricato di gestire i token di autenticazione, necessari per accedere e utilizzare le API.
| Ambiente | Link |
|---|---|
| Test | antea.iss.it/test/iam/ |
| Produzione | antea.iss.it/iam/ |
Tabella 3 Elenco Server IAM
Documentazione Online
È reperibile al link https://antea.iss.it/api-per-caricamento-programmi-di-controllo-v2/ la documentazione online in formato OpenAPI che permetterà agli sviluppatori di accedere agevolmente alle API.
Generazione API KEY
Autenticazione
Seguendo lo standard di riferimento OpenID prima di poter accedere al dato è necessario ottenere un Token di sessione al server IAM. Si delineano quindi le due fasi di seguito:
-
-
- Richiesta del Token:l’applicazione deve inviare una richiesta al server IAM per ottenere un token di autenticazione. Questa richiesta deve includere il client_id ed il client_secret ottenuti nella sezione API KEY una volta effettuato l’accesso con le proprie credenziali su AnTeA.
- Uso del Token: una volta ottenuto il token, questo dovrà essere utilizzato per effettuare chiamate autenticate alle API protette, dovrà essere inserito nell’header della richiesta nell’apposito campo Bearer Token.
-
Flusso
Esempio autenticazione
Per ottenere un token di autenticazione, l’applicazione client deve effettuare una richiesta HTTPS POST al server IAM. Di seguito è riportato un esempio di chiamata utilizzando cURL:
curl --location 'https://$IAM_SERVER$/realms/antea/protocol/openid-connect/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'client_id=$CLIENT_ID$' \ --data-urlencode 'client_secret=$CLIENT_SECRET$'
I seguenti valori dovranno essere sostituiti con i valori reali forniti durante la registrazione dell’applicazione con il sistema IAM:
-
-
- $IAM_SERVER$
- $CLIENT_ID$
- $CLIENT_SECRET$
-
Riportiamo di seguito un esempio di risposta alla chiamata precedente.
{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJTZzQxTlkyYkx5WkxXdGNsdC1SMGZad3p6RUxLSlJxZHF3UUVPQXNWZGJrIn0[……]T1r7vWCPOb5xYJcfERI86DB_S3mxJMYxAQ4sYQDa7GzRqtC8swxkl4EnHWTUd8ysPLcXgJCsZc1NBAXBn2juP2AUJnwMKtbjSmP-4i6BWShx8l_yASlw", "expires_in": 36000, "refresh_expires_in": 10800, "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhODUzMjNiZC03MDI1LTRmOTctYjMxYS1jNTkzNDkyNWRiNjMifQ[……]R5pxLwC-utRWzjXQi8QkM0LIOL0Bq9ucgGMJLpC4jjY", "token_type": "Bearer", "not-before-policy": 1666728811, "session_state": "7420a438-a823-4583-b1cb-b7275231246b", "scope": "email profile" }
Il server IAM restituirà un JSON contenente un token di autenticazione (campo access_token ), che dovrà essere utilizzato per effettuare chiamate alle API protette, includendolo nell’header delle richieste HTTP, come Authorization: Bearer <token> .
API disponibili
Nei paragrafi di seguito illustriamo le principali API messe a disposizione per l’interconnessione del sistema con sistemi esterni.
Caricamento Singolo Punto di Campionamento
È possibile utilizzare questa chiamata API per caricare un singolo punto di campionamento nel portale e ricevere una risposta puntuale dell’avvenuto inserimento.
Flusso
-
-
- Preparazione dei Dati: il gestore prepara un JSON contenente i dati del singolo punto di controllo secondo lo schema definito;
- Invio dei Dati: il gestore invia i dati tramite una richiesta POST all’endpoint /puntoCampionamento;
- Ricezione della Risposta: l’API valida i dati inviati e, se corretti, restituirà il codice HTTP 201, insieme a un messaggio di successo. In caso di errore nei dati inseriti sarà indicato l’errore riscontrato.
-
È possibile effettuare più volte la chiamata al fine di inserire tutti i punti di campionamento.
Nella documentazione online sono disponibili anche le chiamate per effettuare le GET e le PUT (aggiornamento) dei punti di campionamento.
Esempio
ACCESS_TOKEN="your_access_token_here" curl -X POST "https://$API_SERVER$/punto-campionamento" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "Content-Type: application/json" \ -d ' { "uuid": "12_058091_SE_213", "istatRegione": 12, "istatComune": 58091, "tipoPuntoCampionamento": "F1", "idPuntoCampionamento": "U001", "idAreraAto": 1124, "idAreraGestore": 1124, "codiceAcquedotto": "A1", "wsz": "SOPRAMONTE", "progressivoLineAcquedottistica": "1", "coordinate": { "epsg": "4326", "lat": 41.92916653825498, "lon": 12.398053271534483, "z": 85.76 }, "previsioneAbitantiServiti": 1500, "previsionePortata": 690, "descrizionePunto": "Scuola via Roma", "note": "rubinetto dietro l’angolo", "numeroCampionamentoAnnuoInternoPrevisto": 0, "numeroCampionamentoAnnuoEsterniPrevisto": 10, "dataInizioValidita": "2024-01-01", "dataFineValidita": "2024-31-12" }'
Caricamento JSON in modalità batch
Il caricamento in modalità batch consente di inviare grandi volumi di dati per l’elaborazione in un’unica operazione, ottimizzando l’efficienza e riducendo la necessità di multiple chiamate API.
Flusso
-
-
- Preparazione del File JSON: viene preparato un file JSON contenente i dati di tutti i punti di campionamento, riportati nel formato specificato che consiste nella concatenazione di più elementi sopra citati singolarmente;
- Invio del File per l’Elaborazione: viene inviato il file JSON codificato in Base64 all’API mediante una chiamata POST;
- Ricezione dell’Identificativo di Batch: dopo l’invio del file, dall’API sarà restituito un identificativo unico per il batch, che potrà essere utilizzato per interrogare lo stato dell’elaborazione;
- Elaborazione dei Dati: il sistema elaborerà i dati contenuti nel file JSON. Questo processo può variare in tempo, a seconda della dimensione del file e della complessità dei dati;
- Interrogazione dello Stato di Elaborazione: asincronamente, l’applicazione esterna può interrogare lo stato dell’elaborazione utilizzando l’identificativo di elaborazione per sapere se la stessa è completata, in corso o se sono stati rilevati errori.
-
Formato File dei Programmi di Controllo
Il file JSON per l’invio dei dati in modalità batch deve essere strutturato in modo da contenere tutti i dati necessari per l’elaborazione. Sarà possibile caricare il file JSON tramite API oppure dalla GUI del programma.
Di seguito è fornito un esempio di come potrebbe essere strutturato il file per l’invio dei Programmi di Controllo contenente 3 punti di controllo distinti:
{ "puntiControllo": [ { "uuid": "12_058091_F1_AU00123", "istatRegione": 12, "istatComune": 58091, "tipoPuntoCampionamento": "F1", "idPuntoCampionamento": "AU00123", "idAreraAto": 1202, "idAreraGestore": 13989, "codiceAcquedotto": "A1", "wsz": "PRIMAVALLE", "progressivoLineAcquedottistica": "1", "coordinate": { "epsg": "4326", "lat": 41.92916653825498, "lon": 12.398053271534483, "z": 85.76 }, "previsioneAbitantiServiti": 1500, "previsionePortata": 690, "descrizionePunto": "Fontanella Piazza Viale Indro Montanelli", "note": "Fontanella Piazza Viale Indro Montanelli, 00168 Roma RM", "numeroCampionamentoAnnuoInternoPrevisto": 0, "numeroCampionamentoAnnuoEsterniPrevisto": 10, "dataInizioValidita": "2024-01-01", "dataFineValidita": "2024-31-12" }, { "uuid": "12_058091_F1_AU00456", "istatRegione": 12, "istatComune": 58091, "tipoPuntoCampionamento": "F1", "idPuntoCampionamento": "AU00456", "idAreraAto": 1202, "idAreraGestore": 13989, "codiceAcquedotto": "A1", "wsz": "PRIMAVALLE", "progressivoLineAcquedottistica": "1", "coordinate": { "epsg": "4326", "lat": 41.92916653825498, "lon": 12.398053271534483, "z": 85.76 }, "previsioneAbitantiServiti": 1500, "previsionePortata": 690, "descrizionePunto": "Fontanella Largo Flanagan Edoardo Giuseppe", "note": "Fontanella Largo Flanagan Edoardo Giuseppe, 00168 Roma RM", "numeroCampionamentoAnnuoInternoPrevisto": 0, "numeroCampionamentoAnnuoEsterniPrevisto": 10, "dataInizioValidita": "2024-01-01", "dataFineValidita": "2024-31-12" }, { "uuid": "12_058091_FA_SC45", "istatRegione": 12, "istatComune": 58091, "tipoPuntoCampionamento": "FA", "idPuntoCampionamento": "SC45", "idAreraAto": 1202, "idAreraGestore": 13989, "codiceAcquedotto": "A1", "wsz": "PRIMAVALLE", "progressivoLineAcquedottistica": "1", "coordinate": { "epsg": "4326", "lat": 41.92916653825498, "lon": 12.398053271534483, "z": 85.76 }, "previsioneAbitantiServiti": 1500, "previsionePortata": 690, "descrizionePunto": "Fontanella Piazza Viale Indro Montanelli", "note": "Fontanella Piazza Viale Indro Montanelli, 00168 Roma RM", "numeroCampionamentoAnnuoInternoPrevisto": 0, "numeroCampionamentoAnnuoEsterniPrevisto": 10, "dataInizioValidita": "2024-01-01", "dataFineValidita": "2024-31-12" } ] }
Esempio invio file
Per inviare il file JSON è necessario prima convertirlo in una stringa codificata in base64. Successivamente, si potrà utilizzare la chiamata API sotto l’endpoint /api/elaborazione-piani-controllo per inviare file al sistema.
Di seguito esempio cURL per l’invio del file dei piani di controllo:
ACCESS_TOKEN="your_access_token_here" BASE64_ENCODED_JSON="base64_encoded_string_here" curl -X POST 'https://$API_SERVER$/elaborazione-piani-controllo' \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H 'Content-Type: application/json' \ -d '{ "type": "application/json", "base64": "${BASE64_ENCODED_JSON}" }'
Come risposta alla chiamata si otterrà l’identificativo dell’elaborazione “ idElaborazione” da utilizzare per le successive chiamate e capire lo stato dell’elaborazione:
{ "idElaborazione": "743c071c-8721-451c-a5ae-b5c8b7964", "uuidFile": "6ecc6aad-823b-42b9-ba45-eda0e2000b1a", "type": "JSON", "content": "PIANI_CONTROLLO", "statoElaborazione": "SALVATO_SU_DATALAKE", "erroreElaborazione": null, "note": null, "error": null }
Interrogazione stato elaborazioni in batch
Una volta inviato il file per l’elaborazione in batch, è possibile verificare lo stato delle elaborazioni per controllare l’avanzamento e identificare eventuali errori.
Esempio
ACCESS_TOKEN="your_access_token_here" curl -X GET "https://$API_SERVER$/elaborazione/743c071c-8721-451c-a5ae-b5c8b7964" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "Content-Type: application/json"
Sostituire ” 743c071c-8721-451c-a5ae-b5c8b7964” con l’identificativo unico del batch ( idElaborazione) di cui si desidera verificare lo stato. La risposta fornirà informazioni dettagliate sullo stato dell’elaborazione, inclusi eventuali errori. Di seguito alcuni esempi di risposta:
Risposta per elaborazione iniziata
{ "idElaborazione": "10dad3c8-5ffd-49b6-b7ce-c31ae1f02bff", "uuidFile": "b8ec8cc7-1a6b-4a44-b243-b6052517d787", "type": "JSON", "content": "PIANI_CONTROLLO", "statoElaborazione": "SALVATO_SU_DATALAKE", "erroreElaborazione": null, "note": null, "error": null }
Risposta per Elaborazione Conclusa con il dettaglio delle risorse inserite
{ "idElaborazione": "10dad3c8-5ffd-49b6-b7ce-c31ae1f02bff", "uuidFile": "b8ec8cc7-1a6b-4a44-b243-b6052517d787", "type": "JSON", "content": "PIANI_CONTROLLO", "statoElaborazione": "ELABORAZIONE_CONCLUSA", "erroreElaborazione": null, "note": "Elaborazione caricamento conclusa: aggiunte 23 entità", "error": null }
Risposta per Elaborazione Conclusa ma andata in errore con il dettaglio delle risorse andate in errore
{ "idElaborazione": "10dad3c8-5ffd-49b6-b7ce-c31ae1f02bff", "uuidFile": "b8ec8cc7-1a6b-4a44-b243-b6052517d787", "type": "JSON", "content": "PIANI_CONTROLLO", "statoElaborazione": "ERRORE", "erroreElaborazione": "ERRORE_SALVATAGGIO_NEL_DATABASE", "note": "(Errore alla riga 2) Punto campionamento già presente su database (PuntoCampionamento con uuid: 8_099013_F1_EZ123Z )", "error": null }
Tipologie dei Punti di Campionamento
In questa tabella sono disponibili i codici delle tipologie di prelievo utilizzabili:
| CARATTERIZZAZIONE PUNTI DI CAMPIONAMENTO | CODICE | NOTE | ||
|---|---|---|---|---|
| A | CAPTAZIONI | SUPERFICIALE – CORSI D’ACQUA NATURALI E/O ARTIFICIALI | AA1 | Captazioni in derivazione da traverse su corsi d’acqua naturali e/o artificiali |
| SUPERFICIALE – LAGHI NATURALI | AA2 | Captazioni attraverso prese idriche poste in laghi naturali | ||
| SUPERFICIALE – INVASO | AA3 | Captazioni attraverso prese idriche poste in laghi artificiali | ||
| SOTTERRANEA – SORGENTI E RISORGIVE | AB1 | Captazioni da sorgenti | ||
| SOTTERRANEA- POZZI, CAMPI POZZI O TRINCEE/GALLERIE DRENANTI | AB2 | Captazioni da pozzi | ||
| ACQUE MARINE E SALMASTRE | AC1 | Captazioni da impianti di dissalazione | ||
| CENTRALE IDROELETTRICA | AD1 | Captazioni subito a valle della centrale | ||
| ALTRO | AAA | |||
| B | TRATTAMENTI | FISICO E DISINFEZIONE | B1 | trattamento fisico semplice e disinfezione (comprende ad es. stacciatura,sedimentazione, filtrazione); |
| FISICO-CHIMICO E DISINFEZIONE | B2 | trattamento fisico e chimico normale e disinfezione (comprende ad es. coagulazione e flocculazione) | ||
| FISICO-CHIMICO SPINTO E DISINFEZIONE | B3 | trattamento fisico e chimico spinto, affinamento e disinfezione (comprende ad es.ozonazione, adsorbimento su carbone attivo, ultrafiltrazione, osmosi) | ||
| ADDIZIONALE AL FISICO-CHIMICO SPINTO | B4 | trattamenti chimici e/o fisici addizionali al trattamento fisico e chimico spinto per rimozione di inquinanti specifici (ferro, manganese, idrogeno solforato, ammoniaca,arsenico, floruri, nitrati,…) | ||
| ALTRO | BA | |||
| C | ADDUZIONE | DI LINEA | C1 | |
| DI CONFLUENZA | C2 | A valle della confluenza di più tubazioni, ad una distanza significativa a rendere l’acqua confluita completamente miscelata | ||
| DI DIRAMAZIONE | C3 | A valle di una diramazione dalla tubazione principale | ||
| POMPAGGIO DI LINEA | C4 | |||
| ALTRO | CA | |||
| D | ACCUMULO | SERBATOIO INTERRATO | D1 | |
| SERBATOIO SEMINTERRATO | D2 | |||
| SERBATOIO SOPRAELEVATO | D3 | |||
| TORRINO PIEZOMETRICO | D4 | |||
| ALTRO | DA | |||
| E | DISTRIBUZIONE | DI LINEA | E1 | |
| DI CONFLUENZA | E2 | |||
| DI DIRAMAZIONE | E3 | |||
| POMPAGGIO DI LINEA | E4 | |||
| Punto di consegna Ingresso casa dell’Acqua | E5 | |||
| ALTRO | EA | |||
| F | PUNTI D’USO | FONTANA PUBBLICA | F1 | |
| punto d’uso presso Strutture prioritarie di Classe A (D.Lgs.18/23, All.VIII) | F2 | |||
| punto d’uso presso Strutture prioritarie di Classe B (D.Lgs.18/23, All.VIII) | F3 | |||
| punto d’uso presso Strutture prioritarie di Classe C1 (D.Lgs.18/23, All.VIII) | F4 | |||
| punto d’uso presso Strutture prioritarie di Classe C2 (D.Lgs.18/23, All.VIII) | F5 | |||
| punto d’uso presso Strutture prioritarie di Classe D (D.Lgs.18/23, All.VIII) | F6 | |||
| ALTRO | FA | |||
Tabella 6 Caratterizzazione Punti di Campionamento
Di seguito alcune definizioni per supportare gli utenti nella definizione della tipologia dei punti di campionamento.
ADDUZIONE
Insieme di condotte che, di norma, non distribuiscono la risorsa agli utenti. Generalmente sono condotte che, più o meno ramificate e difficilmente magliate, partono dalla captazione e arrivano a serbatoi di accumulo/distribuzione. La classificazione di dettaglio è adottata da ogni gestore in funzione dell’articolazione del proprio sistema idrico. In caso di assenza di serbatoi, potrebbero essere presenti sistemi di disconnessione idraulica quali vasche di carico, piezometri, ecc.
In sistemi acquedottistici di modeste dimensioni, l’adduzione potrebbe non essere presente qualora la captazione sia direttamente connessa al serbatoio, vasche di carico, piezometri o, addirittura, alla distribuzione.
DISTRIBUZIONE
Insieme di condotte che, di norma, distribuiscono la risorsa agli utenti. Generalmente sono condotte più o meno ramificate o magliate, che partono da serbatoi o altri sistemi di disconnessione idraulica.
La classificazione di dettaglio è adottata da ogni gestore in funzione dell’articolazione del proprio sistema idrico. In caso di assenza di un sistema articolato di adduzione, la distribuzione coincide con l’intero sistema acquedottistico.
PUNTO DI DIRAMAZIONE
È una sezione terminale di una condotta da cui si dipartano due o più condotte. Il punto di prelievo ad esso connesso deve essere scelto dal gestore a monte dello stesso.
PUNTO DI CONFLUENZA
È una sezione iniziale di una condotta che si parte dalle sezioni terminali di due o più condotte ad essa connessa. Il punto di prelievo ad esso connesso deve essere scelto dal gestore ad una distanza significativamente utile per poter ritenere la completa miscelazione delle risorse veicolate nelle due o più condotte di monte.
Se si sta caratterizzando una rete magliata chiusa, il punto di confluenza e di diramazione viene identificato in funzione del verso dell’acqua all’interno della maglia. Pertanto, l’identificazione dei relativi punti di prelievo dovrà essere scelta dal gestore in funzione del comportamento simulato della rete in condizioni di funzionamento ordinario, salvo diverse motivate scelte del gestore.
Canale di Assistenza e supporto
Per supportare gli enti e i gestori nel caricamento dei dati, è stato istituito un canale di assistenza dedicato. Gli utenti di tutti gli enti possono registrarsi per aprire segnalazioni e richiedere supporto in questi ambiti:
-
-
- Commento RFC: per inviare commenti e feedback sul seguente documento RFC;
- Problema con Sistema Test: per segnalare malfunzionamenti o difficoltà riscontrate durante l’utilizzo del sistema di test;
- Problemi di Accesso: per risolvere eventuali difficoltà di accesso alla piattaforma o ai sistemi correlati;
- Altro: per qualsiasi altra problematica non categorizzata nei punti precedenti;
-
Il sistema di assistenza è progettato per essere intuitivo e facilmente accessibile. Per accedere al servizio, è necessario registrarsi al seguente link:
https://anteawecom.freshdesk.com/support/login
Una volta registrati, gli utenti possono aprire nuove segnalazioni, monitorare lo stato delle richieste in corso, e ricevere aggiornamenti e risposte direttamente dal team di supporto. Questo canale punta a migliorare l’efficienza e la qualità del servizio al fine di supportare gli enti nel trasferimento dei dati su Antea.
Modalità di Commento
Per favorire la partecipazione di tutti gli attori coinvolti nel processo di sviluppo del sistema, è possibile commentare questa RFC. I commenti costruttivi aiuteranno ad identificare eventuali modifiche o precisazioni necessarie.
I commenti possono essere inseriti alla fine della pagina o in corrispondenza dei singoli paragrafi utilizzando l’icona verde di commento. Tutti i commenti saranno moderati per garantire che il processo sia il più costruttivo possibile.
Si richiede inoltre di aprire un ticket sul canale di assistenza per fornire i recapiti di chi commenta, in modo da poter essere eventualmente contattati per ulteriori chiarimenti.
Commenti Ricevuti
Al fine di garantire trasparenza e ottimizzare la modalità partecipativa scelta per il progetto AnTeA, è possibile consultare a questo link https://antea.iss.it/commenti/
tutti i commenti raccolti durante la prima versione delle RFC (Request for Comments), insieme alle relative risposte e chiarimenti forniti. Questo approccio facilita il dialogo continuo tra i partecipanti e i responsabili del progetto, promuovendo una maggiore partecipazione e permettendo una comprensione più chiara delle modifiche e dei miglioramenti apportati sulla base del feedback ricevuto.
Allegati
Di seguito i file allegati al seguente documento:
Buongiorno ma nel caso in cui si abbia solo il trattamento FISICO-CHIMICO SPINTO ma senza disinfezione che codice è opportuno utilizzare? non sarebbe meglio scrivere per i trattamento E/O DISINFEZIONE?
Buongiorno,
a chi spetta assegnare il codice uuid “Codice di riferimento unico”? E’ un codice che viene calcolato automaticamente dal sistema?
Buongiorno, a proposito dei codici relativi ai trattamenti: