In questo tutorial ti mostriamo come spedire documenti allegati ai tuoi Messaggi Premium su IO
Last updated
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.
I file degli Allegati non sono trasmessi al momento dell'invio del Messaggio, né sono memorizzati sui sistemi di IO
È compito della tua Organizzazione garantire la presenza nel tempo, nei propri sistemi, degli Allegati dichiarati in un Messaggio: in caso contrario, il Cittadino visualizzerà un messaggio di errore al posto dell'elenco dei file
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.
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.
Dopo aver definito il Servizio che userai per spedire i tuoi Messaggi, per abilitarlo all'invio di Allegati dovrai creare o selezionare una configurazione remota allo scopo di ottenere o recuperare il configuration_id necessario a IO per sapere come recuperare i dati dei tuoi file.
{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.
Sei tu a decidere il valore di third_party_data.id, ma tieni presente che deve essere univoco all'interno dell'insieme dei tuoi Servizi IO che condividono il medesimobaseUrl comunicato in fase di onboarding.
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.
{third_party_data.has_attachments}Per indicare a IO che il tuo messaggio conterrà degli allegati, devi impostare il flag third_party_data.has_attachments a true: questo predisporrà l'app IO a mostrare un'apposita sezione nel dettaglio del messaggio e a recuperare i dati dei file dai tuoi sistemi, quando l'utente li richiederà.
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.
Trovi tutte le informazioni di dettaglio circa gli endpoint di callback nella Guida Tecnica.
Il risultato che vogliamo ottenere in questo esempio è che il Cittadino riceva un Messaggio IO simile a quello mostrato di seguito:
Nota la presenza della sezione "Allegati" con l'elenco dei documenti che accompagnano il messaggio.
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 L'identificativo {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"
È responsabilità della tua Organizzazione persistere i file degli allegati ai suoi Messaggi IO; il processo di integrazione con IO si limita al consentire il recupero fisico dei file in app.
È compito della tua Organizzazione garantire che determinati allegati siano diretti a un determinato Cittadino/utente, nel rispetto dell'Accordo Premium siglato con PagoPA e delle vigenti normative sulla riservatezza dei dati.
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"
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 e le specifiche del formato Markdown supportato da IO
La presenza della struttura third_party_data indica a IO che il tuo Messaggio veicola uno o più Allegati:
configuration_id è l'identificativo della configurazione remota scelta per la gestione degli allegati di questo messaggio: lo ottieni seguendo il processo indicato nella Guida Tecnica
has_attachments va obbligatoriamente impostato a true
fiscal_code è il Codice Fiscale del destinatario del Messaggio
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.
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 --> L'identificativo {third_party_data.id}
L'endpoint avrà risposto con questi dati:
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
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:
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 --> L'identificativo {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.
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 GUID generata allo scopo
