Modello di integrazione con l'area personale (DRAFT)
Questo documento descrive gli aspetti tecnici dell'importazione delle Pratiche Lite, uno strumento che permette di integrare le pratiche provenienti da altri gestionale.
Last updated
Questo documento descrive gli aspetti tecnici dell'importazione delle Pratiche Lite, uno strumento che permette di integrare le pratiche provenienti da altri gestionale.
Last updated
Il documento è in fase di stesura, le informazioni in esso contenuto, i protocolli e i jsonSchema possono subire variazioni anche importanti.
La nostra piattaforma permette al cittadino di interagire sia con le pratiche generate sulla piattaforma stessa sia con pratiche generate su altri gestionali. Cittadini e Operatori potranno, da un'unica interfaccia, interagire con un elenco uniforme di pratiche.
Per realizzare questa integrazione è stato ideato il concetto di Pratiche Lite, che rappresenta una pratica con un set minimo di dati, necessari a visualizzare e interagire correttamente l'elenco delle pratiche agli utenti a differenza delle Pratiche che nascono all'interno della piattaforma che contengono tutti i dati delle pratiche. Ma non solo, è possibile visualizzare anche informazioni relative ai documenti correlati alla pratica e i pagamenti.
Sarà necessario fornirci un elenco di Pratiche Lite per esporle sulla nostra piattaforma. Questi dati potranno essere forniti tramite API ReST in formato JSON, oppure mediante file CSV.
Integrare le pratiche generare da altri gestionali nell'area personale permette al cittadino di:
consultare in un unico posto tutte le pratiche relative a un cittadino, anche se generate da altri sistemi;
seguire l'iter della pratica
consultare i dati essenziali di una pratica, come il richiedente e il beneficiario;
consultare i documenti associati alla pratica e lo stato della protocollazione;
consultare i pagamenti associati alla pratica;
dialogare con gli operatori mediante la funzione messaggi dell'Area personale.
Ma l'area personale non è solo consultazione, il cittadino, se l'integrazione lo prevede, potrà comunque interagire con le pratiche, anche se generate da sistemi esterni. Operazioni come la visualizzazione completa della pratica, la modifica, l'integrazione dei documenti o l'annullamento della richiesta, saranno eseguite direttamente sul gestionale esterno, invocando gli opportuni endpoint HTTP corrispondenti alle azioni da eseguire. Questi endpoint verranno specificati pratica per pratica all'atto dell'importazione, se non specificati
Questa è una rappresentazione schematica dei dati che è possibile inviare:
Pratica: titolo e stato della pratica
Richiedente: nome, cognome, codice fiscale e contatti del richiedente
Beneficiario : nome, cognome, codice fiscale e contatti del beneficiario
Servizio: servizio collegato alla pratica
Endpoint delle azioni: endpoint http delle azioni eseguibili sulla pratica
Documenti: documenti collegati alla pratica e stato di protocollazione
Pagamenti: pagamenti collegati alla pratica
Nei capitoli seguente verranno mostrati i tracciati dettagliati di import.
Il seguente diagramma mostra i possibili stati in cui può trovarsi una pratica:
Bozza: in questo stato la pratica non è considerata ancora completamente compilata e può essere modificabile
Inviata: la pratica è stata compilata in ogni sua parte da cittadino e definitivamente inviata. In questo stato non è più possibile modificare i dati delle pratica
Presa in carico: la pratica è stata presa in carico da un Operatore, il quale effettuerà le normali operazioni d'ufficio necessarie a gestirla
In attesa di integrazione: l'operatore ha richiesto di integrare la pratica con informazioni e/o documenti mancanti. La pratica resta in questo stato fino a quando non si ottiene una risposta dal Cittadino
Rifiutata: la pratica non è stata accettata dall'operatore che l'ha gestita
Ritirata: la pratica è stata ritirata dal cittadino prima che l'ufficio si sia pronunciata
Annullata: quando l'ufficio definisce che non si procederà ulteriormente con la pratica e non si pronuncerà su ulteriore approvazione o rifiuto
Supportiamo tre modalità di integrazione:
Modalità push tramite API: è possibile inviarci tramite apposita API i dati delle pratiche per inserire nuove pratiche o per aggiornarne lo stato. Questa modalità di aggiornamento è utile per mantenere costantemente aggiornati i dati delle pratiche tra due sistemi, avendo quindi modifiche immediate per il cittadino. Questa modalità garantisce la possibilità di creare un dialogo col cittadino.
Modalità di invio massivo (batch): permette di importare una grande quantità di dati ad ogni invocazione ma non garantisce l'esecuzione in tempo reale. È utile sopratutto per le prime importazioni, o in tutti quei casi in cui non ho necessità di avere uno stato aggiornato in tempo reale. È possibile fornire i dati nei formati CSV o JSON.
Modalità polling: il sistema esterno espone un API da invocare a scadenza regolare che permette al nostro sistema di recuperare gli aggiornamenti. Fondamentale che API dia la possibilità di recuperare gli aggiornamenti incorsi in un intervallo di tempo
aggiornamento del dato per il cittadino
in tempo reale
latenza di ore
a intervalli di tempo (minuti/ore)
gestione degli errori latenza per correggere un errore
errori gestiti in tempo reale
errori gestiti alla fine del batch
errore gestito alla fine dell'intervallo
Per effettuare un'importazione è necessario autenticarsi ed ottenere un token di autenticazione
È possibile seguire questa guida per le istruzioni di autenticazione https://docs.opencityitalia.it/developers/integrazioni/integrazioni-con-il-flusso-delle-pratiche/api-rest
Autenticazione standard nel modello 1 e 2
Modello 3: basic auth, client certificate, api key
Questa è la rotta per effettuar il singolo import di Pratica, Documenti e Pagamenti
Come è possibile vedere dal tracciato riportato nel paragrafo successivo, è possibile inviare in un solo colpo i dati relativi a pratiche, documenti e pagamenti. Questi tre elementi si considerano correlati tra di loro, quindi, documenti e pagamenti, si intendono relativi alla pratica inviata e verranno relazionati a essa.
Le pratiche verranno identificate in maniera univoca dal campo external_id che rappresenta un identificativo del sistema sorgente, se non presente, verrà creata con i dati passati.
La riconciliazione di richiedente e beneficiario (applicant e beneficiary) verrà effettuata basandosi sul codice fiscale (tax_code). Se nel sistema esiste già un utente con quel codice fiscale, verranno utilizzati i dati già presente nel database ignorando i dati di nome, cognome e contatti che vengono passati. Al contrario, se non presenti, verrà importato un nuovo utente con i dati specificati.
Lo stato della pratica segue il flusso definito nei capitoli precedenti, tuttavia non è stato implementato un controllo stringente sul flusso della pratica, in controllo dello stato della pratica è demandato al sistema sorgente.
Lo stato della pratica regola però le azioni che il cittadino potrà effettuare. Nella sezione links è possibile specificare le azioni permesse sulla pratica è l'URL da invocare al click del cittadino. Se una specifica azione non è specificata non verrà proposta al cittadino. Le azioni verranno proposte al cittadino anche in base allo stato della pratica, per esempio, una pratica in stato inviata non può più essere modificata, quindi, anche se indicata l'azione MODIFY, non verrà comunque proposta.
Il seguente endpoint serve per il cambio di stato di una pratica lite. Permette opzionalmente di inviare un messaggio al richiedente contestualmente al cambio stato