Istruzioni: come aderire e portare i servizi di un Ente su IO
Istruzioni: come aderire e portare i servizi di un Ente su IO
v1.1 - 25.07.2022
1. Adesione al progetto
Il contratto di adesione è l’accordo tra una pubblica amministrazione e PagoPA S.p.A. (“PagoPA”), che definisce la volontà dell’ente di aderire alla piattaforma IO (il punto di accesso telematico di cui all’art. 64-bis del CAD) al fine di offrire i propri servizi in rete in qualità di soggetti erogatori. L’accordo contiene i termini e le condizioni per l’utilizzo e l’esposizione dei servizi sulla piattaforma IO da parte delle PA aderenti.
1.1 Firma dell’accordo
L’accordo deve essere compilato in digitale e sottoscritto con firma digitale da un legale rappresentante dell’ente, o altra figura con potere di firma.
Nell’accordo è richiesta l’identificazione di uno o più delegati, in particolare:
- di almeno un delegato amministrativo, quale responsabile dell’accordo e dunque punto unico di contatto tra il soggetto erogatore e PagoPA, e al quale verranno inviate tutte le comunicazioni inerenti il rapporto di adesione;
- di uno o più delegati tecnici, da indicare nell’allegato 4, incaricati dal soggetto erogatore ad operare sul back-office e svolgere tutte le attività necessarie per l’integrazione tecnologica. Il delegato amministrativo può anche operare come delegato tecnico; in ogni caso tali funzioni tecniche possono essere svolte da soggetti diversi dal soggetto erogatore, ad esempio, una società in-house o un partner tecnologico.
Per ciascun delegato (amministrativo e/o tecnico) è necessario indicare i seguenti dati identificativi: nome e cognome, codice fiscale, ente o società di appartenenza, qualifica/posizione, e-mail e PEC.
L’indirizzo e-mail del delegato indicato nell’accordo di adesione costituisce il recapito e l’identificativo ufficiale con cui il delegato sarà autorizzato ad operare nel back-office dell’App IO: se la mail indicata nell’accordo e quella registrata nel back-office non corrispondono, PagoPA non potrà procedere all’attivazione dei servizi in produzione, per ragioni di sicurezza.
L’accordo compilato e sottoscritto digitalmente deve essere inviato dall’ente, tramite PEC all’indirizzo xxxxxxxx-xx@xxx.xxxxxx.xx: a partire dalla ricezione da parte di PagoPA dell’accordo sottoscritto può iniziare la procedura di abilitazione del delegato e attivazione dell’ente su App IO, come descritto nei paragrafi successivi 2 (Integrazione Tecnologica) e 3 (Pubblicazione dei servizi).
Riassunto attori-ruoli
Cosa fa il Legale Rappresentante dell’ente? Cosa fa il Delegato dell’ente?
● Firma l’atto di adesione con firma digitale
● Definisce uno o più Delegati per la gestione dei servizi su app IO
● Riceve l’incarico da parte del Legale Rappresentante
● Si registra nel back-office (2.1)
● Predispone i servizi dell’ente (3.1 e 3.2)
● Gestisce le chiavi API per l’integrazione tecnologica (3.3)
Importante!
Il delegato è una persona fisica. Non si può delegare una persona giuridica (es. la
software-house che offre il servizio di integrazione), ma dovrà essere indicata la persona di riferimento presso quella società.
Le credenziali del delegato per l’accesso ai servizi su app IO nonchè le relative chiavi API dovranno essere conservate con la massima cura e riservatezza.
1.2 Variazioni dei delegati
Se l’ente ha necessità di aggiungere o rimuovere dei delegati, o modificarne i dati identificativi (ad esempio, l’indirizzo e-mail) comunica la variazione a PagoPA, compilando nuovamente l’allegato 4 del contratto di adesione con i
dati aggiornati, sottoscrivendolo digitalmente e inviandolo tramite PEC all’indirizzo all’indirizzo xxxxxxxx-xx@xxx.xxxxxx.xx, indicando nell’oggetto della PEC “ADESIONE IO - VARIAZIONE DELEGATI ” i nuovi delegati o i dati dei delegati da rimuovere.
1.3 Enti aggregatori
Gli enti possono aderire a IO in qualità di aggregatori di altri soggetti erogatori. Il rapporto di aggregazione tra i soggetti erogatori è regolato dagli accordi (compresi gli accordi di cooperazione di cui all’art. 15 della L. 241/1990) e dagli atti amministrativi necessari a conferire al soggetto aggregante i poteri e le attribuzioni necessarie a sottoscrivere il rapporto di adesione anche per conto e a beneficio dei soggetti aggregati, assumendo il rispetto degli obblighi ivi contenuti da parte dei soggetti aggregati stessi.
L’ente aggregatore in questo modo garantisce il rispetto degli obblighi contenuti nel contratto di adesione da parte dei soggetti aggregati.
Esempio: una Regione aderisce a IO aggregando il rapporto di adesione per tutti gli enti locali del territorio di riferimento, mettendo a disposizione la società in-house regionale per gestire l’integrazione tecnologica di tutti gli enti locali.
Gli enti aggregatori devono elencare tutti gli enti che rappresentano ai fini dell’adesione a IO, tramite l’allegato 3 del contratto di adesione, dove devono comunicare la lista completa degli enti tramite indicazione di: denominazione dell’ente rappresentato, sede, codice fiscale/p. iva e codice IPA.
Importante!
Qualora un ente volesse sottoscrivere autonomamente altri servizi (in aggiunta a quelli resi disponibili tramite l’ente aggregatore) dovrà seguire la procedura completa di onboarding sottoscrivendo l’accordo di adesione.
L’ente aggregatore può operare solo per i servizi per cui ha ricevuto l’incarico dall’ente aggregato, ma non può sostituirsi all’ente rispetto ai servizi per cui non ha ricevuto mandato.
2. Integrazione tecnologica
L’integrazione tecnologica prevede che il delegato dell’ente si registri al back-office e utilizzi le API-keys di IO per predisporre l’integrazione con i sistemi e gestionali attualmente in uso. L’integrazione deve essere fatta in modo automatizzato, tramite API-keys: anche se il portale mette a disposizione funzioni di invio manuale di messaggi tramite file csv, questa funzione è utilizzabile solo a scopo dimostrativo e di test, per simulare l’esperienza desiderata. Maggiori dettagli sulle API e il loro utilizzo sono pubblicati nella documentazione tecnica.
2.1 Iscrizione al back-office
Nel momento in cui un delegato viene incaricato ufficialmente da un ente tramite il contratto di adesione, può operare nel back-office per conto dell’ente. A tal fine, il delegato si deve iscrivere al back-office inserendo:
● nome e cognome;
● l’indirizzo mail ufficiale indicato nell’accordo di adesione.
NB: Se il delegato ha già una registrazione nel back-office con un altro account che utilizza per attività di test, è tenuto a effettuare una nuova registrazione con la sua mail ufficiale e utilizzare questa nuova registrazione per le attività di produzione;
● un numero di telefono ove ricevere un codice di conferma OTP per l’ingresso nel portale back-office per l’autenticazione a due fattori.
È fondamentale compilare correttamente i campi in fase di registrazione, indicando i riferimenti personali della figura di delegato esplicitati nel contratto di adesione.
I permessi ad operare sul back-office, infatti, vengono conferiti sulla base dell’indirizzo e-mail e non possono essere modificati, pertanto in caso di mancata corrispondenza, dovuta a errore nella compilazione, o in caso di variazione di qualsiasi dato riferito ai delegati sarà necessario comunicare il dato aggiornato tramite la procedura di variazione dei delegati e procedere alla creazione di un nuovo account su cui ricevere le nuove autorizzazioni.
Gli account che riportano nomi generici (es. il nome del Comune anziché nome e cognome del Delegato) o che contengono indirizzi mail diversi da quelli riportati nel contratto di adesione, non potranno essere chiaramente identificati e quindi insigniti dei permessi per il passaggio in produzione.
2.2 Gestione dei permessi
Tutti gli account possono svolgere attività di test tramite invio di messaggi al codice fiscale fittizio riportato nel portale. Questi messaggi generano una mail verso l’indirizzo email associato all’utente che ha generato quelle specifiche chiavi API.
Se un ente vuole svolgere dei test d’integrazione completi e visualizzare i messaggi inviati direttamente in app, può indicare uno o più codici fiscali reali a cui vorrebbe mandare messaggi di prova. Questi codici fiscali vanno trasmessi via mail a xxxxxxxxxx@xx.xxxxxx.xx: i tecnici di PagoPA procederanno con l’abilitazione previa verifica che quei codici fiscali corrispondano a utenti reali di test (tramite invio di codici di verifica su app IO). Resta inteso che ciascun ente erogatore rimane obbligato a fornire idonea informativa privacy e a raccogliere il necessario consenso delle persone fisiche il cui codice fiscale viene trasmesso per le predette finalità di test.
In caso l’ente voglia svolgere test d’integrazione di messaggi che contengono un avviso di pagamento e permettono di svolgere il pagamento direttamente in app, è necessario richiedere l’autorizzazione per testare messaggi con una somma associata (max_allowed_amount). Anche in questo caso l’abilitazione a inviare messaggi di pagamento per finalità di test va richiesta a xxxxxxxxxx@xx.xxxxxx.xx.
Quando viene fatta la richiesta di pubblicazione di un servizio, l’utente che ha creato quel servizio (corrispondente al soggetto delegato nel contratto di adesione) riceverà da PagoPA i permessi per la produzione e da quel momento, le chiavi API associate a quel servizio potranno inviare messaggi ai codici fiscali individuati dall’ente quali utenti finali di ciascun servizio.
3. Pubblicazione dei servizi
Un servizio è considerato attivo su App IO quando:
● ha ricevuto i permessi per andare in produzione, ovvero l’autorizzazione a inviare messaggi a codici fiscali individuati dall’ente quali utenti finali di ciascun servizio; e
● è stato reso visibile in app, ovvero compare nella tab “Servizi”, con possibilità di opt-in/opt-out da parte dell’utenza.
Da quel momento, il servizio può inviare notifiche e messaggi all’utenza, utilizzando IO come canale di comunicazione. Qui di seguito sono elencati i passaggi necessari per pubblicare i servizi su App IO e tenerli aggiornati nel tempo.
3.1 Cos’è un servizio
Un servizio su App IO è una risorsa che comunica proattivamente all’utenza tramite invio di notifiche, messaggi, promemoria e avvisi di pagamento.
I messaggi sono sempre comunicazioni di carattere personale, in quanto indirizzate a uno specifico utente. I servizi possono interrogare il back-end rispetto a uno specifico codice fiscale di un utente, di cui sono a conoscenza e a cui hanno qualcosa di personale da comunicare e, se il CF risulta presente tra gli utenti di App IO e ha il servizio attivo, sono autorizzati a procedere e inviare la propria comunicazione. Ne consegue che è escluso sia l’invio di comunicazioni massive alla totalità dell’utenza di IO (e.g. non sono ammessi messaggi c.d. broadcast) sia l’invio a utenti che non siano destinatari diretti degli specifici servizi erogati dagli enti.
Ciascun utente può consultare maggiori dettagli sul servizio accedendo alla relativa “scheda” descrittiva, che spiega in modo chiaro l’oggetto del servizio su App IO, contiene i riferimenti di contatto del soggetto erogatore nonché l’informativa privacy relativa al trattamento dei dati personali degli utenti IO da
parte dei soggetti erogatori. I dati inseriti nella scheda servizio, dunque, servono ad informare in modo chiaro e trasparente all’utenza cosa può aspettarsi dalla fruizione di quel servizio e dalle comunicazioni di quell’ente, per supportare la sua decisione di attivarlo o disattivarlo, nonché per offrirgli la possibilità di comunicare (tramite contatto telefonico, mail, assistenza o altro canale indicato nella scheda servizio) con l’ente, ad esempio per chiedere chiarimenti rispetto a una specifica comunicazione che non ha compreso. Per questo è estremamente importante che gli enti si attengano alle indicazioni che seguono.
3.2 Progettazione dei servizi in IO
Al momento App IO può essere utilizzata per l’invio di:
● semplici notifiche (messaggi di testo, possono riguardare un aggiornamento relativo ad esempio ad un nuovo documento disponibile o un’istanza presentata presso l’ente)
● promemoria (messaggi che contengono una data di scadenza o da ricordare, come il reminder della scadenza di un documento da rinnovare o la data entro cui iscriversi a un servizio) - per questo tipo di messaggi è necessario utilizzare il campo due_date nel payload del messaggio.
● avvisi di pagamento (messaggi che contengono le informazioni relative a una posizione debitoria, con il promemoria della data di scadenza entro cui effettuare il pagamento e la funziona “paga” per poter procedere al pagamento) per questo tipo di messaggi è necessario inserire i campi relativi al payment_data (IUV, importo da pagare, data di scadenza).
Per facilitare l’ente nell’elaborare i testi dei propri messaggi e configurare i servizi su app IO è possibile far riferimento a questo template, che può essere utilizzato come linea-guida per:
tab 1) definire una lista di servizi che l’ente è interessato a offrire tramite App IO;
tab 2) definire una serie di messaggi che possono essere utilizzati per comunicare all’utenza, a seconda delle necessità di ciascun servizio; tab 3) preparare i dati di descrizione di ciascun servizio, come illustrato in questa guida alla voce Compilazione delle schede.
La lista dei servizi, il contenuto dei messaggi e le informazioni riportate nella scheda servizio sono compilati in autonomia e sotto responsabilità, che si impegna a rispettare gli standard e le istruzioni offerte da PagoPA. Non è necessario trasmettere queste informazioni alla stessa PagoPA, ma è consigliato riferirsi ai canali di contatto dedicati agli enti in caso di dubbio, tenendo presente che il template costituisce una semplice guida da utilizzare come spunto e riferimento per la compilazione di messaggi e schede.
Importante!
Ogni servizio generato nel back-office (e relativa chiave API) corrisponde a un servizio su app IO, supportato da relativa scheda servizio (es. servizi scolastici, servizio tributi, servizio anagrafe, ecc.). Ogni servizio può inviare più tipologie di messaggi e comunicazioni a seconda delle necessità (es. un servizio anagrafe può inviare dei promemoria per la scadenza del proprio documento d’identità, l’avviso di pagamento per una specifica prestazione, il reminder dell’appuntamento per la richiesta della CIE, ecc,). Ogni servizio corrisponde a un ente specifico che lo eroga (che compare in app IO come mittente del messaggio). Ne consegue che non è necessario creare un nuovo servizio distinto per ciascun messaggio/categoria di comunicazione che si intende inviare.
Memo
In ogni funzione di supporto e comunicazione all’utenza, App IO dà del “tu” e utilizza un linguaggio gender neutral, vale a dire che, ove possibile, evita appellativi e aggettivi riferiti all’utenza che sono specifici di un genere (es. “Ti diamo il benvenuto” invece di “Xxxxxxxxx”]),. Gli enti che utilizzano IO come canale sono invitati ad adeguare la propria comunicazione dal “lei” al “tu”, e adottare un tono di voce e stile di comunicazione semplice, chiaro, diretto e neutrale, limitando il più possibile l’utilizzo di acronimi, linguaggio tecnico.
3.3 Compilazione delle schede
Le schede servizio contengono la descrizione dello specifico servizio offerto dall’ente e i dati di contatto a disposizione dell’utenza per approfondire il contenuto del servizio o inoltrare specifiche domande. La scheda servizio può essere compilata per ciascun servizio all’interno del back-office, nei campi associati a ciascun servizio-chiave API.
Di seguito un ESEMPIO di scheda servizio:
Campi obbligatori
Di seguito vengono elencati i campi obbligatori per la compilazione della scheda servizio, e alcune regole per la compilazione:
1.1. service_name:
il nome del servizio, che indica agli utenti a quale ambito fanno riferimento le comunicazioni che riceve in app (es. tributi). Il nome del servizio viene mostrato come mittente del messaggio (insieme al nome dell’ente).
1.2. organization_name:
il nome dell’ente che offre il servizio. Deve riportare il nome completo della pubblica amministrazione aderente, ad esempio “Comune di Varese” (non “Varese”).
1.3. organization_fiscal_code:
il codice fiscale dell’ente che eroga il servizio.
1.4. privacy_url:
l’indirizzo web ove è pubblicata l’informativa privacy del servizio.
1.5. description:
1.6. contatti:
almeno uno o più canali di contatto diretto a cui un utente può chiedere assistenza, a scelta tra: phone, mail, pec, support_url
1.7. service_logo e/o organization_logo :
l’immagine in formato png 300x300 pixel (fondo bianco o trasparente) del logo del servizio e del logo dell’ente. Il logo dell’ente è obbligatorio, mentre il logo del servizio è di default uguale al logo dell’ente, ma può essere aggiunto come logo indipendente nei casi in cui il servizio abbia un logo diverso da quello dell’ente.
1.8. service_scope:
l’area geografica di riferimento di un servizio può essere locale
(local) o nazionale (national). Tutti gli enti che servono un territorio delimitato (regione, comune, distretto,...) - non corrispondente all’intera nazione - devono impostare i propri servizi con lo scope “local”.
1.9. authorized_cidrs:
uno o più indirizzi IP separati da ; da cui provengono le chiamate al back-end di IO, per le relative chiavi API/servizio (ad esempio 000.000.00.00/00;000.00.00.00/00). Questo è un blocco di sicurezza che inibisce le chiamate provenienti da altri indirizzi IP, che cercano di operare per quei servizi.
Campi facoltativi
In aggiunta ai campi obbligatori, sono disponibili alcuni campi aggiuntivi
facoltativi:
1.10. tos_url:
l’indirizzo web a cui l’utenza può rivolgersi per consultare i termini e condizioni del servizio (se pubblicati);
1.11. address:
l’indirizzo fisico dell’ufficio di riferimento per il servizio, utile se un utente ha necessità di chiedere maggiori informazioni recandosi presso uno sportello o inviando delle comunicazioni in formato analogico;
1.12. app_ios e app_android:
il link all’eventuale app che l’ente mette a disposizione su Apple Store e Google Play per offrire la stessa funzione o lo stesso servizio offerto tramite App IO
1.13. web_url:
l’indirizzo web a cui l’ente mette a disposizione il medesimo servizio o maggiori informazioni relative al servizio.
Importante!
Se il tuo servizio è stato già pubblicato ma non presenta tutti i campi obbligatori qui citati, lo troverai etichettato nel back-office con la scritta “dati incompleti o incorretti”: dovrai procedere all’inserimento dei campi mancanti per poter inoltrare la richiesta di pubblicazione del servizio.
Importante!
App IO può essere un’ottima vetrina dei servizi digitali già messi a disposizione dall’ente e aiutare la pubblica amministrazione a far conoscere sito e app esistenti, compilando in modo completo la scheda servizio: questi dati di contatto saranno infatti associati a ogni relativo messaggio, portando facilmente l’utenza a “scoprire di più”.
3.4 Regole generali di formattazione
I nomi degli enti e nomi dei servizi devono essere riportati in minuscolo: il maiuscolo è consentito solo per le iniziali e eventuali sigle (es. TARI). Non è consentito indicare tutto il nome del servizio in maiuscolo (es. SERVIZI SCOLASTICI). Non si possono utilizzare caratteri maiuscoli per la descrizione del servizio e tutti i metadati.
I nomi dei servizi devono essere rappresentativi di ciò che il servizio eroga all’utenza tramite IO, nel formato di un sostantivo e non di un verbo/azione: es. “Prenotazione sale comunali” indica un servizio che consente non solo di prenotare, ma anche di seguire lo stato della prenotazione, dunque fornisce un’informazione più completa rispetto a un eventuale titolo “ “Prenota sale comunali”.
3.5 Passaggio in produzione
Affinché il servizio sia autorizzato al passaggio in produzione, la relativa scheda servizi deve essere completa dei campi di descrizione obbligatori indicati sopra.
Quando tutte le operazioni di integrazione tecnologica e compilazione della scheda servizio sono state effettuate, l’ente può sottomettere la richiesta di rendere visibile in app il servizio (per ottenere il passaggio in produzione), cliccando sul bottone “pubblica il servizio” esposto nel back-office nella pagina di dettaglio di ciascun servizio.
Il team di PagoPA verifica che tutta la procedura sia stata eseguita correttamente e:
- in caso positivo, procede con l’attivazione, per cui il servizio diventa visibile in app e riceve i permessi per inviare messaggi all’utenza; oppure
- qualora il servizio per cui è stata richiesta l’attivazione presenti delle incompletezze o delle incongruenze, PagoPA contatterà l’ente con una richiesta di modifica.
In ogni momento a partire dalla richiesta di pubblicazione, l’ente potrà verificare all’interno del back-office il relativo esito. Il servizio può trovarsi in uno dei seguenti stati:
● servizio attivo: il servizio è visibile in app ed è possibile inviare messaggi all’utenza;
● in review: il servizio è in corso di revisione da parte di PagoPA in seguito alla richiesta di pubblicazione da parte dell’ente;
● dati incompleti o incorretti: la richiesta di pubblicazione del servizio è stata rifiutata o non è possibile darvi seguito per una delle seguenti ragioni:
- PagoPA non ha ricevuto il contratto di adesione (via PEC);
- l’account che ha generato i servizi non corrisponde a un delegato indicato nel contratto di adesione o tramite aggiornamenti via PEC;
- i servizi non presentano tutti i metadati obbligatori nella scheda servizio;
- i servizi presentano dei campi non compilati correttamente (es. descrizione incompleta del servizio).
Qualora la richiesta si trovi nello stato “dati incompleti o incorretti” l’ente potrà modificare la scheda servizio e rinviare la richiesta di pubblicazione.
3.6 Aggiornamento dei servizi
I servizi possono essere aggiornati in ogni momento, sempre nel rispetto delle regole di adeguatezza, esattezza e legalità dei contenuti, modificando l’apposita scheda nel back-office e salvando nuovamente i dati.
Importante!
In questa fase non è possibile spostare autonomamente i servizi da un account all’altro nel back-office o gestire i servizi in modo condiviso tra più account: se emerge la necessità di modificare la persona di riferimento (delegato) che gestisce i servizi, è necessario che l’ente lo comunichi via PEC seguendo la procedura di variazione dei delegati questo passaggio verrà gestito con la collaborazione di PagoPA per la disattivazione dei servizi attualmente in produzione, la creazione di una nuova sottoscrizione nel back-office e la nuova registrazione i dei servizi che saranno pubblicati.
PagoPA sta evolvendo questo processo, e nei prossimi mesi sarà possibile per una pluralità di delegati operare sugli stessi servizi, e di transitare i permessi da un ruolo all’altro. Per essere sempre aggiornato sulle novità dedicate alle Pubbliche Amministrazioni rispetto al progetto IO, è possibile consultare il sito ufficiale del progetto all’indirizzo xx.xxxxxx.xx oppure iscriversi alla newsletter di IO, sempre disponibile sul sito ufficiale.