Contesto di Riferimento

Le “zone di fornitura idro-potabile” o “Water Supply Zones (WSZ)” rappresentano le aree geografiche specifiche “all’interno della quale le acque destinate al consumo umano provengono da una o varie fonti e la loro qualità può essere considerata ragionevolmente omogenea, sulla base di evidenze oggettive.” (D.Lgs.18/23, art.2, c.1, lett. ii).
Il monitoraggio della qualità dell’acqua in tali zone è essenziale per assicurare il rispetto degli standard normativi e la tutela della salute pubblica. L’analisi di campioni di acqua destinata al consumo umano prelevati nei punti di campionamento delle WSZ rappresenta quindi un’attività fondamentale al fine di garantire la sicurezza e la qualità dell’acqua destinata al consumo umano distribuita alla popolazione.

Il D.Lgs.18/2023, recepimento della Direttiva Europea 2020/2184, definisce e norma nel dettaglio le attività di monitoraggio e controllo delle acque destinate al consumo umano agli artt. 12, 13 e 14 ed agli allegati I, II e III.
Tale attività di monitoraggio analitico permette di individuare eventuali criticità, ottimizzare le strategie di controllo e migliorare la gestione delle risorse idriche. Inoltre, una corretta pianificazione di tali attività consente di intervenire tempestivamente in caso di anomalie, minimizzando i rischi per la popolazione e garantendo il rispetto delle normative vigenti. La selezione dei punti di campionamento è ponderata su diversi fattori, tra cui la rappresentatività della rete di distribuzione nelle diverse WSZ, la vicinanza a fonti potenziali di contaminazione, la distribuzione geografica e la densità abitativa ed infine la variabilità stagionale e l’impatto ambientale.
Al fine di armonizzare i descrittori delle WSZ alle normative vigenti a livello comunitario è stata sviluppata una tipologia di codice identificativo INSPIRE specifico per le WSZ. Tale codice è univoco ed assegnato a ciascuna zona di approvvigionamento idrico in linea con la direttiva INSPIRE (Infrastructure for Spatial Information in the European Community), al fine di rendere tali dati geospaziali compatibili con i sistemi informativi geografici ad oggi in uso a livello comunitario.
Di seguito, in breve, sono indicate le caratteristiche del codice INSPIRE della WSZ:

• Univocità – ogni WSZ ha un codice identificativo unico che consente di identificarla univocamente nel sistema informativo geografico europeo;
• Standardizzazione – il codice segue un formato definito dalla direttiva INSPIRE per garantire coerenza nei dati spaziali a livello europeo;
• Interoperabilità – il codice permette l’integrazione delle informazioni sulla qualità dell’acqua nei sistemi geografici nazionali ed europei;
• Tracciabilità – il codice agevola il monitoraggio e la gestione delle zone di approvvigionamento idrico da parte delle autorità competenti.

Documentazione API (Swagger UI)

Per la consultazione degli endpoint e dei modelli utilizzati nel caricamento massivo delle Water Supply Zones (WSZ), è disponibile la seguente documentazione tecnica: Accedi allo Swagger

Definizioni e Abbreviazioni

Scopo del Documento

Il presente documento ha l’obiettivo di fornire le linee guida per il caricamento delle WSZ all’interno della piattaforma AnTeA. Tale operazione è necessaria per garantire la corretta gestione e reportistica delle WSZ in conformità con la Direttiva Acque Potabili 2020/2184/EC e le relative disposizioni europee in materia di dati georeferenziati, secondo quanto richiesto dal WISE e dallo standard INSPIRE.

Il documento descrive i requisiti tecnici e operativi per il caricamento delle WSZ, incluse le modalità di identificazione, delimitazioni, caricamento dei poligoni e codifica, nonché i metadati obbligatori e la gestione delle eventuali sovrapposizioni.

Responsabilità del caricamento Dati

Il caricamento delle WSZ all’interno della piattaforma AnTeA è responsabilità esclusiva dei Gestori Idropotabili competenti per ciascun territorio. I gestori sono tenuti a garantire l’accuratezza e la completezza delle informazioni fornite, assicurando che i dati georeferenziati delle WSZ siano conformi a quanto previsto in merito dal D.Lgs.18/2023.

I gestori idropotabili dovranno:

• Identificare e delimitare le WSZ secondo i criteri definiti dalle normative vigenti.
• Assegnare un nome a ciascuna WSZ, utile al gestore per ricercare ls WSZ.
• Caricare i dati nella piattaforma AnTeA.
• Verificare e confermare la corretta assegnazione territoriale delle WSZ all’interno del sistema.
• Rispondere di eventuali sovrapposizioni con altre WSZ, in conformità con le regole di risoluzione previste dalla piattaforma.

Eventuali inesattezze o omissioni nei dati caricati potranno compromettere l’affidabilità delle informazioni e influire negativamente sulla reportistica ufficiale. È pertanto fondamentale che ogni gestore operi con la massima attenzione e nel rispetto delle procedure descritte nel presente documento.

Descrizione del flusso autorizzativo Utenti

L’accesso e l’autorizzazione degli utenti relativi ai gestori idropotabili sulla piattaforma AnTeA seguiranno le specifiche tecniche stabilite dalle RFC di riferimento per la trasmissione dei risultati dei controlli esterni.

Il sistema di autenticazione garantirà che solo gli utenti debitamente autorizzati possano accedere alle funzionalità di caricamento, modifica e validazione delle WSZ. Le autorizzazioni saranno gestite secondo un modello a ruoli, che permetterà di differenziare i livelli di accesso in base alle responsabilità dell’utente.

Per i dettagli tecnici relativi al flusso autorizzativo, ai protocolli di autenticazione e ai livelli di permessi assegnabili, si rimanda alla documentazione ufficiale delle RFC di riferimento di seguito il link:

• https://antea.iss.it/specifiche-per-la-trasmissione-dei-risultati-dei-controlli-interni-ed-esterni-v2/

Ambiente di Test

Di seguito il link per gli ambienti di test dove provare il caricamento delle WSZ all’interno di Antea.

• https://antea.iss.it/test/portal/water-supply-zone/lista

Per la richiesta di credenziali di accesso al sistema di test segue la specifica delle RFC di riferimento per la trasmissione dei risultati dei controlli esterni. di seguito il link:

• https://antea.iss.it/specifiche-per-la-trasmissione-dei-risultati-dei-controlli-interni-ed-esterni-v2/

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:

• Supporto Caricamento WSZ: supporto nel caricamento dei dati in piattaforma;
• 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.

Per accedere al servizio, è necessario registrarsi al seguente link:

• https://anteawecom.freshdesk.com/support/login

Modalità di Trasmissione delle WSZ

Il processo di caricamento delle WSZ su AnTeA segue una sequenza strutturata per garantire la corretta registrazione e identificazione delle WSZ da parte dei gestori idropotabili.

1. Caricamento delle WSZ su AnTeA

I gestori idropotabili sono responsabili del caricamento delle WSZ all’interno della piattaforma AnTeA. Il sistema offre tre modalità di inserimento:

• Caricamento di un file georeferenziato: il gestore può caricare un file in formato compatibile (Shapefile e GeoJSON) contenente il poligono della WSZ.
• Caricamento da Dominio geografico Esistente
  • Selezione da liste predefinite: il gestore può selezionare la WSZ tra poligoni territoriali già disponibili nel sistema (es. comuni, aree subcomunali, località ISTAT).
  • Composizione della WSZ con più poligoni: nel caso in cui una WSZ sia composta da più unità territoriali (ad esempio, frazioni di un comune), il gestore potrà selezionare e combinare più poligoni.

Dopo il caricamento, il sistema AnTeA Mostrerà nella mappa sul portale la proiezione su mappa della WSZ caricata per permettere all’utente che carica di verificare che i poligoni caricati siano corretti e coerenti con i dati territoriali su mappa.

2. Validazione e Assegnazione del Codice WSZ

Una volta caricata, la WSZ viene sottoposta a un processo di validazione, da parte del sistema, che include:

• Controllo della coerenza territoriale con i dati geospaziali esistenti.
• Verifica delle sovrapposizioni con altre WSZ già presenti nel sistema.

Se la WSZ rispetta i criteri richiesti, il sistema assegna un codice univoco nel formato ITWSZ000000, che identifica in modo permanente la WSZ nel sistema.

Questo codice sarà il riferimento ufficiale per tutte le operazioni future relative alla WSZ, come aggiornamenti, modifiche o trasmissioni ai sistemi di reportistica.

Se la WSZ presenta incongruenze, il gestore riceverà una segnalazione con le eventuali correzioni necessarie prima della finalizzazione del processo.

Caricamento tramite Interfaccia

Attraverso il menu laterale sarà possibile selezionare la tipologia di caricamento prescelta.

Caricamento Tramite File

Nella schermata di caricamento cliccare su “Aggiungi Coordinate”

Sarà quindi aperto una finestra modale dove andrà selezionata la tipologia di file da caricare.

Nel caso di ShapeFile E File GeoJSON selezionare il file File e dopodichè Cliccare su “Mostra sulla Mappa” 

Il file di riferimento potrà essere caricato in Shapefile (compresso tramite zip) o in formato GeoJson.

Il sistema di riferimento del file dovrà essere WGS84 – EPSG:4326

nel caso di GeoJSON incollare nella Textarea il contenuto del JSON da caricare dopodiché cliccare su “Mostra sulla Mappa”

Una volta caricati i dati sarà possibile visualizzare la preview delle wsz sulla mappa.

A seguito del caricamento, nella schermata successiva, i file aggiunti sono visibili in Elenco file caricati.

E’ necessario inserire il nome della WSZ all’interno della sezione Metadati. 

Una volta cliccato su “Salva” è possibile visualizzare il codice della WSZ generato dal sistema.

Caricamento da Dominio geografico Esistente

Selezionando la voce  “Caricamento da Dominio Geografico Esistente” sarà possibile definire un WSZ partendo da uno o più layer geografici precaricati nel sistema.

Nelle barre di ricerca sulla sinistra è possibile ricercare per il nome del comune. Una volta selezionato un comune nella tendina le altre voci Aree SubComunali, Località e Zona saranno filtrate sulla base del comune selezionato. Se invece la WSZ deve corrispondere all’intero comune cliccare il tasto “Mostra sulla Mappa” e il comune interessato sarà caricata sulla mappa; è possibile ricercare Aree SubComunali, Località e Zona Censuarie che al click saranno caricate sulla Mappa.

Successivamente inserire il “Nome” tra i metadati della WSZ e sarà possibile procedere al salvataggio attraverso il tasto “Salva”

Una volta salvato è possibile visualizzare il codice della WSZ generato dal sistema.

Codice WSZ

Al termine del processo di caricamento e validazione, il sistema assegnerà un codice univoco a ciascuna WSZ. Tale codice seguirà il formato standard: ITWSZ000000

Dove:

• ITWSZ rappresenta il prefisso identificativo per le WSZ in Italia.
• 000000 è un numero progressivo univoco assegnato dal sistema.

Il codice WSZ sarà restituito automaticamente all’utente al termine della procedura di invio dei dati su AnTeA e rappresenterà il riferimento ufficiale per la specifica WSZ in tutte le operazioni future, incluse modifiche, aggiornamenti e trasmissioni ai sistemi di reportistica europei come WISE.

Modifica di una WSZ

Accedendo alla schermata di una WSZ già esistente selezionando la matitina in alto a destra è possibile procedere alla modifica dei punti che delimitano il layer geografico.

Trascinare i punti sulla mappa per modificare il Layer.

Cliccando su “Trasmetti” è possibile salvare le modifiche effettuate.

Sovrapposizioni

In caso di sovrapposizioni con altre WSZ precaricate il sistema riporterà un messaggio di errore e sulla mappa saranno mostrate le altre WSZ che intersecano con quella caricata. Sarà quindi compito del gestore andare a modificare i WSZ correggendo i punti di sovrapposizione.

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

Endpoint IAM

Il webserver IAM sarà incaricato di gestire i token di autenticazione, necessari per accedere e utilizzare le 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. 1. 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:

1. 1. • $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> .

Caricamento Massivo delle WSZ

Il sistema consente il caricamento massivo delle WSZ tramite apposite API. Le operazioni di caricamento, monitoraggio ed eliminazione vengono eseguite attraverso richieste REST, seguendo le specifiche descritte nelle sezioni seguenti.

1. Caricamento delle WSZ

Il caricamento massivo consente di inviare più WSZ in un’unica operazione. Il file contenente le WSZ deve essere in formato GeoJSON, codificato in Base64 e inviato nel body della richiesta.

È possibile utilizzare encoder online gratuiti per convertire file GeoJSON in formato Base64. Per il dettaglio completo degli endpoint, dei parametri accettati e dei formati di risposta, è possibile consultare la Swagger UI.

2. Struttura del file GeoJSON

Il file GeoJSON deve rispettare lo standard internazionale. Ogni WSZ deve essere definita come una ‘Feature’ all’interno di una ‘FeatureCollection’. Di seguito sono elencati i campi obbligatori e un esempio rappresentativo.

• Il campo “type” deve essere valorizzato con “FeatureCollection”.
• Ogni elemento dell’array “features” deve contenere il campo “type”: “Feature”.
• Ogni feature deve avere un campo “properties” (Oggetto) con le seguenti proprietà obbligatorie:

1. “NOME” (maiuscolo): testo (max 32 caratteri), univoco a livello nazionale.
2. “ID_ARERA_GESTORE” (maiuscolo): numero identificativo del gestore.

• Ogni feature deve avere un campo “geometry” (Oggetto) con:

1. “type”: “MultiPolygon”
2. “coordinates”: coordinate della WSZ (formato EPSG:4326).

Esempio GeoJSON rappresentativo:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "NOME": "TEST1",
        "ID_ARERA_GESTORE": 3045

      },
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [[[ [10.14078, 44.57989] , [10.14079, 44.57990] ]]]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "NOME": "TEST2",
        "ID_ARERA_GESTORE": 3045
      },
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [[[ [10.14078, 44.57989] , [10.14079, 44.57990] ]]]
      }
    }
  ]
}

3. Risposta dell’API di caricamento

A seguito dell’invio della richiesta, il sistema restituisce un oggetto JSON contenente informazioni sull’elaborazione avviata. Il processo può richiedere da pochi secondi fino a diversi minuti, a seconda del numero di WSZ.

{
  "createdAt": "2025-11-12T14:56:55.863113",
    "lastUpdateAt": "2025-11-12T14:56:55.887966",
    "deletedAt": null,
    "createdBy": "nome_utente",
    "updatedBy": null,
    "isActive": true,
    "uuid": "d93c693c-8333-441f-bf79-6303a98bd7f1",
    "status": "IN_CORSO",
    "wszSaved": 0,
    "errore": null,
    "elaborazioneIdAreraGestore": [
        {
            "idAreraGestore": id_arera_gestore dell’utente
        },
        {
            "idAreraGestore": id_arera_gestore dell’utente
        },
        {
            "idAreraGestore": id_arera_gestore dell’utente
        }
    ],
    "active": true
}

• uuid : identificativo univoco dell’elaborazione
• elaborazioneIdAreraGestore : vengono dedotti automaticamente dagli idAreraGestore (nel caso fossero più di uno) cui l’utente che ha lanciato l’elaborazione ha diritto
• status: stato in cui si trova l’elaborazione. Può essere:
  1. IN_CORSO (elaborazione in ancora in corso)
  2. CONCLUSA_CON_ERRORI (elaborazione terminata ma con almeno una wsz in errore)
  3. CONCLUSA_SENZA_ERRORI (elaborazione terminata con tutte wsz salvate)
  4. NON_CONCLUSA (elaborazione in errore. File non valido o GeoJson non valido.
• wszSaved : wsz salvate dall’elaborazione

Durante l’elaborazione è sconsigliato effettuare ulteriori caricamenti, sia singoli che massivi.

4. Monitoraggio dello stato di elaborazione

Per verificare l’avanzamento delle elaborazioni, è possibile utilizzare l’API di monitoraggio.
L’API restituisce esclusivamente le elaborazioni avviate dall’utente autenticato, consentendo così un controllo puntuale delle attività da lui generate.

Di seguito i dettagli tecnici dell’endpoint:

Funzionamento dei parametri opzionali

• status: Permette di filtrare l’elenco delle elaborazioni in base al loro stato di avanzamento (consentiti: “IN_CORSO”, “CONCLUSA “,  “NON_CONCLUSA “)
• uuid: Se valorizzato con un identificativo valido, la risposta restituisce un’unica elaborazione corrispondente all’UUID specificato.

Logica di utilizzo dell’API

Questa API può essere utilizzata per monitorare lo stato di un caricamento massivo.
Quando lo stato di un’elaborazione risulta:

• IN_CORSO
• CONCLUSA_CON_ERRORI
• CONCLUSA_SENZA_ERRORI (elaborazione terminata con tutte wsz salvate)
• NON_CONCLUSA

è possibile procedere con ulteriori operazioni di inserimento.

Nel caso di stato CONCLUSA_CON_ERRORI, significa che almeno una WSZ non è stata caricata correttamente durante l’elaborazione.

Nel caso di stato NON_CONCLUSA, il processo non è iniziato e nessuna Wsz è stata caricata (probabile errore formattazione nel GeoJson)

5. Download degli errori

In caso di errori, l’API dedicata consente di scaricare il dettaglio delle WSZ non caricate. Il risultato può essere restituito come JSON o file .txt contenente lo stesso contenuto.

[
   {
        "elemNum": 18,
        "nome": "TEST18",
        "descrizione": "L'utente è abilitato SOLAMENTE per i seguenti idAreraGestore: [13397, 3045, 14151]. La wsz ha invece idAreraGestore [42391]"
    },
    {
        "elemNum": 19,
        "nome": "TEST19",
        "descrizione": "Nome: TEST19 già presente su db"
    }
]

In questo esempio, l’elaborazione è andata in errore agli elementi numero 18 e 19 (elemNum) del GeoJson. La descrizione fornisce un’indicazione della motivazione.

Una volta corretti gli errori, si può procedere ad un nuovo caricamento massivo.

Si può caricare anche lo stesso GeoJson “sanato” degli errori. Il sistema impedisce infatti il caricamento di Wsz che hanno lo stesso nome. In alternativa si può formare un nuovo GeoJson con meno elementi ma contenente solamente le Wsz sanate.

6. Eliminazione di un’elaborazione

È possibile eliminare un’elaborazione e tutte le WSZ caricate con essa. L’operazione è irreversibile e può essere eseguita solo dall’utente che ha avviato il processo.

Trasmissione WISE

La piattaforma AnTeA si occuperà della trasmissione dei dati relativi alle WSZ al sistema WISE, in conformità con le direttive europee di riferimento. Una volta che i gestori idropotabili avranno completato il caricamento e la validazione delle WSZ su AnTeA, il sistema procederà in un secondo momento con:

• L’elaborazione e il consolidamento dei dati, assicurando che le informazioni siano strutturate secondo i requisiti di WISE.
• L’assegnazione e la formattazione dei metadati, in conformità con gli standard INSPIRE e ISO 19139, garantendo la corretta interoperabilità con i sistemi europei.
• L’invio periodico dei dati a WISE, secondo le scadenze stabilite dalle autorità competenti, assicurando l’aggiornamento continuo delle informazioni georeferenziate sulle WSZ.
• La gestione di eventuali segnalazioni di errore o incongruenze, con la possibilità per i gestori di correggere i dati direttamente su AnTeA prima della successiva trasmissione.

Grazie a questo processo, AnTeA garantirà il rispetto delle normative europee sulla qualità e sulla sicurezza dell’acqua potabile, semplificando il flusso di informazioni tra i gestori idropotabili e le istituzioni preposte al monitoraggio e alla reportistica ufficiale.

Allegati

• file_esempio_JSON