Indice del Documento

Contesto di Riferimento

Definizioni e Abbreviazioni

Scopo del Documento

Responsabilità del caricamento Dati

Descrizione del flusso autorizzativo Utenti

Modalità di inserimento di programmi di controllo

Schema concettuale

Modello Entità Relazione (ER)

Descrizione dei parametri richiesti per programmi di controllo

Codice di Riferimento Unico

Ambiente di Test

Caricamento tramite Interfaccia

Caricamento Programmi di Controllo

Caricamento tramite File Excel

Caricamento Tramite Webservice

Endpoint API

Endpoint IAM

Documentazione Online

Generazione API KEY

Autenticazione

Flusso

Esempio autenticazione

API disponibili

Caricamento Singolo Punto di Campionamento

Flusso

Esempio

Caricamento JSON in modalità batch

Flusso

Formato File dei Programmi di Controllo

Esempio invio file

Interrogazione stato elaborazioni in batch

Esempio

Tipologie dei Punti di Campionamento

Canale di Assistenza e supporto

Modalità di Commento

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

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

La gestione delle attività di caricamento dati in AnTeA è conforme a quanto previsto dal D.Lgs.18/2023, che individua nelle “autorità sanitarie delle regioni e province autonome” i soggetti preposti per l’adozione di “opportuni programmi di controllo relativi alle filiere idro-potabili che insistono sul territorio di propria competenza, (…)avvalendosi delle autorità sanitarie locali territorialmente competenti e delle Agenzie del SNPA, coordinandosi con i gestori idro-potabili” (art.12, c.2). L’art.13, comma 2 prevede espressamente che “Le regioni e province autonome provvedono all’inserimento dei risultati dei controlli esterni nel sistema operativo centralizzato AnTeA entro i dodici mesi successivi alla istituzione del suddetto sistema”. È pertanto responsabilità delle Regioni/Provincie autonome il caricamento del programma di controllo e dei risultati dei controlli esterni in AnTeA. Allo stesso modo, per quanto concerne i controlli interni, l’art.14, comma 3 riporta che “i gestori idro-potabili provvedono all’inserimento dei risultati dei controlli interni nel sistema operativo centralizzato AnTeA entro i dodici mesi successivi alla istituzione del suddetto sistema (…)”. Soggetti attuatori del caricamento del programma di controllo e dei dati del controllo esterno ed interno sono dunque, rispettivamente, le Regioni/Provincie Autonome ed i gestori idropotabili. Si rimanda al paragrafo successivo per una descrizione di dettaglio di tale sistema.

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.

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.

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:

1. Aprire il menu laterale: Accedere al menu laterale e selezionare la voce “Punti di campionamento scaduti”.
2. Visualizzazione dei punti scaduti: Verrà visualizzata una pagina contenente una tabella con tutti i punti di campionamento che sono scaduti o non ancora validi.
   
3. 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.

   

4. 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.
   
5. Salvataggio delle modifiche: Una volta inserito il nuovo intervallo di validità, cliccare sul pulsante “Salva” per aggiornare i record selezionati.

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.

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

All’interno della piattaforma AnTeA , nella sezione “API KEY” dedicata agli utenti che hanno ricevuto le autorizzazioni necessarie attraverso un ruolo specifico o una delega, sarà reso disponibile un ambiente in cui sarà possibile generare un identificativo unico per il client (Client_id) e una chiave segreta (Client_Secret). Queste credenziali sono essenziali per l’accesso e l’utilizzo delle API del sistema. Ogni coppia di Client ID e Secret sarà univocamente associata all’utente che le ha generate, garantendo che solo gli utenti autorizzati possano effettuare operazioni tramite le API. È importante notare che tali credenziali dovranno essere inserite accuratamente nei software o applicativi di riferimento che effettueranno connessioni automatizzate con la piattaforma, al fine di stabilire un flusso di trasmissione dei dati efficiente e sicuro tra gli strumenti utilizzati dagli utenti esterni e il sistema AnTeA.

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:

1. 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.
2. 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

1. Preparazione dei Dati: il gestore prepara un JSON contenente i dati del singolo punto di controllo secondo lo schema definito;
2. Invio dei Dati: il gestore invia i dati tramite una richiesta POST all’endpoint /puntoCampionamento;
3. 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

1. 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;
2. Invio del File per l’Elaborazione: viene inviato il file JSON codificato in Base64 all’API mediante una chiamata POST;
3. 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;
4. 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;
5. 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	B1	trattamento fisico semplice e disinfezione (comprende ad es. stacciatura,sedimentazione, filtrazione);
		FISICO-CHIMICO	B2	trattamento fisico e chimico normale e disinfezione (comprende ad es. coagulazione e flocculazione)
		DISINFEZIONE	B3	trattamento fisico e chimico spinto, affinamento e disinfezione (comprende ad es.ozonazione, adsorbimento su carbone attivo, ultrafiltrazione, osmosi)
		XXXXXXXX	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
		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.

 

Allegati

Di seguito i file allegati al seguente documento:

PianoDeiControlli.xlsx

PianoDeiControlliEsempioValorizzato.xlsx

PianoDeiControlli.json

AGGIUNGERE Nuovi FILE