Modello di integrazione con l'area personale
Questo documento descrive gli aspetti tecnici dell'importazione delle Pratiche Lite, uno strumento che permette di integrare le pratiche provenienti da altri gestionali.
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 interagire da un'unica interfaccia 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, utili per permettere al Cittadino di visualizzarle e interagire con esse in maniera uniforme a quanto accade con le Pratiche generate direttamente nel nostro sistema. 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.
I vantaggi dell'integrazione con l'area personale
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, come previsto dal modello del sito comunale del dipartimento;
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;
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.
Modello della Pratica Lite
Per permettere un'integrazione basilare è necessario inviare solo:
titolo e stato della pratica
nome, cognome e codice fiscale del richiedente
un link per raggiungere la pagina di dettaglio della pratica
Ma è comunque possibile aggiungere ulteriori dati per rendere l'esperienza utente piÚ completa:
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
Nel capitolo Flusso di import delle Applications Lite vengono riportati i tracciati dettagliati per una corretta importazione.
Stati della Pratica Lite
Il seguente diagramma mostra i possibili stati in cui può trovarsi una pratica e un possibile flusso di gestione. Come specificato piÚ avanti, le transizioni da uno stato all'altro sono solo indicative, il controllo sui cambi di stato resta al gestionale eterno.
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
ModalitĂ di integrazione
L'invio dei dati al nostro sistema avviene in modalità push tramite API: è possibile inviarci tramite apposita API REST 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.
Ă comunque possibile valutare altre modalitĂ di integrazione, per maggiori dettagli visiona il capitolo Progetti di integrazione ad-hoc con area personale
Autenticazione
Il dialogo tra l'Area personale e il gestionale esterno è bidirezionale: il gestionale importa costantemente sull'area personale i dati aggiornati; il Cittadino, agendo su una Application Lite dall'Area personale, atterra su una pagina del gestionale. I due casi prevedono due autenticazioni differenti.
Il primo caso rappresenta una comunicazione server-to-server che avviene mediante token JWT. Verranno fornite delle credenziali di autenticazione che permetteranno di ottenere un token; il token verrĂ utilizzato per effettuare le richieste successive. Ă possibile seguire questa guida per le istruzioni di autenticazione https://docs.opencityitalia.it/developers/integrazioni/integrazioni-con-il-flusso-delle-pratiche/api-rest
Il secondo caso è piÚ complesso del primo perchÊ bisogna garantire che l'utente effettui un solo login anche qualora passi dall'area personale al gestionale. Per questo mettiamo a disposizione un server OAuth2 che permette al Cittadino di avere una sessione attiva su tutti i client autorizzati.
Import di una pratica tramite API
Questa è la rotta per effettuar il singolo import di Pratica, Documenti e Pagamenti
POST /api/application-lite/import
Content-Type: application/json
Authorization: Bearer {{auth_token}}
{ vedi tracciato di import }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.
Flusso di import delle Applications Lite
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.
Tracciato di import
{
"application": {
"external_id": "EXT123456",
"subject": "Richiesta Contributo Startup",
"applicant": {
"given_name": "Mario",
"family_name": "Rossi",
"identifiers": {
"tax_code": "RSSMRA85M01H501Z"
},
"contacts": {
"mobile": "+393331234567",
"email": "mario.rossi@example.com",
"pec": "mario.rossi@pec.example.com"
}
},
"beneficiary": {
"given_name": "Luca",
"family_name": "Bianchi",
"identifiers": {
"tax_code": "BNCGLC85M01H501Z"
},
"contacts": {
"phone": "+390612345678",
"email": "luca.bianchi@example.com"
}
},
"status": 2000,
"service": {
"id": "123e4567-e89b-12d3-a456-426614174000"
},
"actions": [
{
"action": "view",
"url": "https://sitoweb/other-path?do=view"
},
{
"action": "request_integration",
"url": "https://sitoweb/other-path?do=request_integration"
}
]
},
"documents": [
{
"external_id": "00000000-1111-2222-3333-0334ecfb527d",
"title": "Richiesta: REALIZZAZIONE TETTOIA DEPOSITO-GARAGE, PERMESSO DI COSTRUIRE",
"description": "REALIZZAZIONE TETTOIA DEPOSITO-GARAGE, PERMESSO DI COSTRUIRE",
"short_description": "REALIZZAZIONE TETTOIA DEPOSITO-GARAGE, PERMESSO DI COSTRUIRE",
"folder": "Comunicazione Inizio Lavori-Saverio MMMSSS98D29H123T",
"has_organization": null,
"main_document": "https://localhost/comune-di-bugliano/lang/api/applications/00000000-1111-2222-3333-b167c5038be3/attachments/00000000-1111-2222-3333-50413d60ff4e?version=1",
"registration_data": {
"date": "2024-10-04T14:35:15+02:00",
"document_number": "298O/520/25"
},
"type": "application-request",
"valid_from": null,
"valid_to": null
}
]
}
Gestione dello stato
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
POST /api/application-lite/{id}/status
Content-Type: application/json
Authorization: Bearer {{auth_token}}
{
"new_status": 3000,
"message": "Messaggio da inviare al richiedente al relativo al cambio stato"
}Progetti di integrazione ad-hoc con area personale
La modalità push tramite API REST e json rappresenta un modo standard e diffuso di interazione tra sistemi, tuttavia, non sempre è possibile implementarlo. In questi casi possiamo valutare altre modalità di integrazione mediante un progetto personalizzato. Di seguito vengono riportate a scopo esplicativo due modalità di integrazione alternative che è possibile valutare:
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
Confronto tra le possibili modalitĂ :
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
Last updated
Was this helpful?