🎥Come allegare documenti a un Messaggio (Funzionalità Premium)
In questo tutorial ti mostriamo come spedire documenti allegati ai tuoi Messaggi Premium su IO
Indice dei contenuti
Video tutorial
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.
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.
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 RiservatabaseUrl
: 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 dibaseUrl
:https://integrazione.mioente.it/io
API Key
: è la chiave di autenticazione che IO utilizzerà per richiamare i tuoi endpoint di callback⚠️ Fai attenzione, non si tratta di una delle chiavi, primaria o secondaria, del tuo Servizio!
ℹ️ 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}
{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.
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.
Trovi tutte le informazioni di dettaglio circa gli endpoint di callback nella Guida Tecnica.
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:
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 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.
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"Il valore
"ADVANCED"
perfeature_level_type
identifica un Messaggio Premium: impostalo così per poter aggiungere Allegati al tuo MessaggioComponi il tuo messaggio (
subject
,markdown
) seguendo i consigli riportati nel Manuale dei Servizi di IOLa presenza della struttura
third_party_data
indica a IO che il tuo Messaggio veicola uno o più Allegati:has_attachments
va obbligatoriamente impostato atrue
fiscal_code
è il Codice Fiscale del destinatario del Messaggio
Se il Servizio IO che stai utilizzando non è pubblicato, dovrai chiederci di abilitarlo all'invio di messaggi verso uno o più codici fiscali specifici. Queste persone, che non dovranno essere cittadini/utenti finali ma membri della tua Organizzazione o comunque incaricati dei test, riceveranno i messaggi che invierai direttamente sulla loro App IO.
Se il Servizio è pubblicato, non sarà necessaria alcuna procedura autorizzativa e potrai inviare messaggi a qualsiasi codice fiscale destinatario. Poni la massima attenzione a questo scenario!
Response
Prendi sempre nota dell'identificativo del messaggio ritornato in fase di invio: ti servirà successivamente per recuperarne lo stato e le informazioni di lettura e pagamento.
Step 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.
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 costante000003
--> 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 AllegatoIl 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:
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 costante000003
--> L'identificativo {third_party_data.id}/
--> costante/attachments/evento.pdf
--> valore del campourl
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
.
Last updated