Tabella dei contenuti
Indice dei contenuti
Video tutorial
Video tutorial - Parte 1
Video tutorial - Parte 2
Panoramica
Nell'ambito dell'integrazione con la piattaforma IO, la funzionalità Premium relativa agli allegati è offerta secondo un modello che prevede che i file risiedano presso i sistemi della tua Organizzazione; App IO preleverà i file portandoli sul dispositivo del Cittadino e il trasferimento avviene solo quando il Cittadino decide di aprire un Allegato dal dettaglio del relativo Messaggio.
Per consentire questo scambio di dati dovrai fornire alcune informazioni in sede di onboarding ed esporre un'API REST che sarà richiamata da IO (callback). Il diagramma che segue riporta la sequenza delle operazioni coinvolte nell'integrazione tra la tua Organizzazione e IO per il supporto agli Allegati.
.png)
Integrazione: sequenza degli eventi
Nel diagramma, le frecce in colore blu rappresentano le chiamate che IO fa al backend della tua Organizzazione e corrispondono alle API di callback che dovrai esporre; le frecce in colore verde rappresentano il momento in cui i byte dei tuoi allegati sono trasmessi al Cittadino.
I dati di configurazione
Dopo aver definito il Servizio che userai per spedire i tuoi Messaggi, per abilitarlo all'invio di Allegati dovrai comunicare a IO alcuni dati chiave:
- serviceId: è l'identificativo del Servizio IO, puoi recuperarlo accedendo alla sezione Servizi dell'Area Riservata\
.png)
Dove puoi trovare il serviceId - baseUrl: IO necessita di richiamare il tuo backend per ottenere le informazioni sugli allegati al tuo Messaggio. La URL che IO utilizzerà per questo scopo è costituita da una parte fissa, baseUrl, e una variabile a seconda dello scenario e del messaggio. Esempio di baseUrl: https://integrazione.mioente.it/io
- API Key: è la chiave di autenticazione che IO utilizzerà per richiamare i tuoi endpoint di callback
- :warning: Fai attenzione, non si tratta di una delle chiavi, primaria o secondaria, del tuo Servizio!
- :information_source: Puoi concordare con IO il nome del header che veicolerà la API Key
IO memorizzerà queste informazioni e le utilizzerà successivamente nel colloquio con la tua Organizzazione.
L'identificativo {third_party_data.id}
Quando invierai un Messaggio che contiene allegati, seguendo quanto riportato nella Guida Tecnica, dovrai indicare a IO la presenza dei file associati stabilendo un identificativo (third_party_data.id) che consentirà il successivo colloquio tra il backend di IO e quello della tua Organizzazione.
Trasmetterai l'identificativo nella richiesta di invio del messaggio e sarà poi utilizzato nell'intero colloquio tra la tua Organizzazione e IO, come riportato nella sequenza illustrata in Panoramica.
Esposizione callback
Come accennato nella Panoramica, la tua Organizzazione dovrà esporre delle callback (endpoint REST) alle quali l'infrastruttura di IO potrà far capo nel momento in cui dovrà recuperare determinate informazioni relative agli allegati.
In particolare, gli endpoint previsti dal protocollo sono due:
- quello per il recupero dei metadati che descrivono gli allegati a un Messaggio IO: è invocato quando il Cittadino richiede l'apertura di un Messaggio in app e IO si aspetta di ricevere un elenco di entità ciascuna delle quali descrive un Allegato (id univoco, nome e URL relativa)
- quello per il recupero dei dati binari di un determinato allegato a un Messaggio IO: è invocato quando il Cittadino richiede l'apertura di un Allegato dal dettaglio del Messaggio e IO si aspetta di ricevere i byte del file fisico ospitato sui sistemi della tua Organizzazione
Entrambi saranno protetti da autenticazione con API Key, come illustrato in I dati di configurazione.
Nelle chiamate a entrambi gli endpoint IO aggiungerà l'header fiscal_code riportante il codice fiscale del Cittadino destinatario del Messaggio per cui sta richiedendo gli Allegati. Questo ti dà l'opportunità di verificare che il cittadino sia il reale destinatario degli allegati.
Caso d'uso (esempio)
Il risultato che vogliamo ottenere in questo esempio è che il Cittadino riceva un Messaggio IO simile a quello mostrato di seguito:
.png)
Esempio di Messaggio con Allegati
Nota la presenza della sezione "Allegati" con l'elenco dei documenti che accompagnano il messaggio.
Step 1 - Preparazione degli Allegati
Come prima cosa, una volta implementata l'integrazione tra i sistemi della tua Organizzazione e quelli di IO come riportato in Panoramica, dovrai assicurarti che i file dei tuoi allegati siano a disposizione degli endpoint che avrai esposto verso IO: quando IO ti invocherà utilizzando Lidentificativo third_party_data.id che avrai comunicato in sede di invio del Messaggio, i tuoi sistemi dovranno individuare il set di allegati corrispondente e tornare le relative informazioni secondo il protocollo stabilito.
In questo tutorial, gli esempi prevedono che a fronte di un third_party_data.id con valore 000003 i tuoi sistemi "sappiano" che gli allegati per questo Messaggio sono due:
- un documento con nome "ricevuta.pdf"
- un documento con nome "evento.pdf"
Step 2 - Invio del Messaggio
Request
- Il valore del header Ocp-Apim-Subscription-Key è la chiave (primaria o secondaria) del tuo Servizio IO: puoi recuperarla accedendo all'Area Riservata e cercando la scheda del tuo Servizio nella pagina "Servizi"\
.png)
- Il valore "ADVANCED" per feature_level_type identifica un Messaggio Premium: impostalo così per poter aggiungere Allegati al tuo Messaggio
- Componi il tuo messaggio (subject, markdown) seguendo i consigli riportati nel Manuale dei Servizi di IO
- La presenza della struttura third_party_data indica a IO che il tuo Messaggio veicola uno o più Allegati:
- has_attachments va obbligatoriamente impostato a true
- fiscal_code è il Codice Fiscale del destinatario del Messaggio
Response
1{
2 "id": "01GS8744E24EZDG3XD5ECXB9RG"
3}
4Step 3 - Visualizzazione del Messaggio in App
In seguito alla richiesta di invio del Messaggio, come visto in Step 2 invio del messaggio, l'App IO del destinatario lo riceverà segnalandone la presenza con una notifica "push" (se abilitata sul dispositivo specifico).
Toccando la notifica, oppure aprendo manualmente App IO e toccando il nuovo messaggio nell'elenco dei messaggi ricevuti, l'utente accederà al dettaglio: se tutto sarà andato come previsto, IO avrà contattato i tuoi sistemi per recuperare i metadati degli allegati (numero, nomi e URL relative), potendo così costruire la pagina da mostrarti: nota la sezione Allegati con l'elenco dei tuoi file.
.png)
A livello di integrazione il backend di IO avrà effettuato una richiesta GET all'indirizzo https://integrazione.mioente.it/io/messages/000003, che avrà costruito come segue (come previsto dalle relative specifiche OpenAPI):
- https://integrazione.mioente.it/io --> URL di base comunicata all'onboarding (vedi I dati di configurazione)
- /messages/ --> percorso costante
- 000003 --> Lidentificativo third_party_data.id
L'endpoint avrà risposto con questi dati:
1{
2 "attachments": [
3 {
4 "id": "1",
5 "url": "attachments/ricevuta.pdf",
6 "content_type": "application/pdf",
7 "name": "ricevuta.pdf"
8 },
9 {
10 "id": "2",
11 "url": "attachments/evento.pdf",
12 "content_type": "application/pdf",
13 "name": "evento.pdf"
14 }
15 ]
16}
17- il campo id sarà usato da IO in evoluzioni future. Per il momento è richiesto solo che sia valorizzato in modo univoco, ad esempio puoi usare una nuova GUIDgenerata allo scopo
- Il campo url deve contenere il percorso relativo per il download dell’allegato, come vedremo meglio in dettaglio tra poco in Step 4 visualizzazione di un allegato
- Il campo content_type deve necessariamente contenere il valore “application/pdf”, in quanto IO supporta unicamente allegati in formato PDF/A (consigliamo ai Mittenti di adottare il formato PDF/A-1a, che garantisce la massima sicurezza e accessibilità per i propri documenti)
- Il campo name sarà mostrato come nome dell’allegato nell’elenco in App: sceglilo con cura per comunicare correttamente col tuo utente finale! Deve essere, come nell’esempio, il nome del file che l’utente si ritroverà sul proprio dispositivo se sceglierà di scaricarlo dopo averlo visualizzato: puoi dunque usare un nome del tipo "Ricevuta Evento.pdf" o semplicemente "ricevuta.pdf", la cosa importante è includere l'estensione ".pdf" per consentire all'app e al sistema operativo del dispositivo di trattare correttamente il file eventualmente scaricato dal destinatario
Step 4 - Visualizzazione di un Allegato
Toccando uno dei file allegati al tuo Messaggio, il destinatario avvierà il processo per cui IO richiederà alla tua Organizzazione i byte del file corrispondente utilizzando l'apposito endpoint che avrai esposto (Esposizione callback).
Dopo alcuni secondi, necessari affinché il file sia trasferito dai tuoi sistemi a IO e quindi all'App di destinazione, all'utente sarà mostrato il visualizzatore di PDF integrato in App IO:
.png)
Potrà quindi utilizzare i gesti di zoom e spostamento per esaminare l'allegato più in dettaglio, così come potrà scegliere di:
- condividere l'allegato utilizzando una delle app installate sul suo dispositivo
- salvare il file sul suo dispositivo (viene selezionata automaticamente la cartella dei "download")
- aprire l'allegato con una delle app installate che supporti i documenti in formato PDF
A livello di integrazione il backend di IO avrà effettuato una richiesta GET all'indirizzo https://integrazione.mioente.it/io/messages/000003/attachments/evento.pdf, che avrà costruito come segue (nel rispetto delle specifiche OpenAPI):
- https://integrazione.mioente.it/io --> URL di base comunicata all'onboarding (vedi I dati di configurazione)
- /messages/ --> percorso costante
- 000003 --> Lidentificativo third_party_data.id
- / --> costante
- /attachments/evento.pdf --> valore del campo url prelevato dalla response del primo endpoint
L'endpoint avrà risposto con lo stream di byte in formato binario del documento evento.pdf, al quale avrà aggiunto l'header content-type col valore application/pdf.
In questa pagina
Indice dei contenuti
Video tutorial
Panoramica
I dati di configurazione
L'identificativo {third_party_data.id}
Esposizione callback
Caso d'uso (esempio)
Step 1 - Preparazione degli Allegati
Step 2 - Invio del Messaggio
Step 3 - Visualizzazione del Messaggio in App
Step 4 - Visualizzazione di un Allegato
Hai bisogno di aiuto?
Scrivi un’email in cui descrivi il tuo problema o dubbio all’indirizzo onboarding@io.italia.it
Dicci cosa ne pensi
Per segnalare problemi o dare feedback, lascia un commento nello spazio Github dell'app IO