Come allegare documenti a un Messaggio

Gli enti che hanno sottoscritto il programma Premium possono includere allegati in formato PDF nei messaggi che inviano. In questo tutorial ti spiegheremo come fare.

Il modello della funzionalità Premium relativa all’invio degli allegati, prevede che i file risiedano presso i sistemi della tua organizzazione. App IO preleverà i file portandoli sul dispositivo del Cittadino e il trasferimento avverrà solo quando il Cittadino deciderà 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 comunicare a IO alcuni dati chiave:

• serviceId: è l'identificativo del Servizio IO, puoi recuperarlo accedendo alla sezione Servizi dell'Area Riservata

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
• 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.

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.

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:

1. 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)
2. 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:

1. Un documento con nome "ricevuta.pdf"
2. 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.

Request

curl --location --request 
POST 'https://api.io.pagopa.it/api/v1/messages' \ 
--header 'Ocp-Apim-Subscription-Key: 217d66f7a83642578111d733e1741813' \ 
--header 'Content-Type: application/json' \ 
--data-raw ' { "feature_level_type": "ADVANCED", "time_to_live": 3600, "content": 
{ "subject": "Partecipazione Evento", "markdown": "Gentile Mario Rossi,\n\r\n\r
abbiamo accettato la tua richiesta di partecipazione all'\''evento e ti inviamo 
in allegato la ricevuta del pagamento della tua quota e la brochure con tutte 
le informazioni utili.\n\rA Ti aspettiamo!\n\rL'\''Amministrazione Comunale di Ipazia.", "third_party_data": { "id": "000003", "has_attachments": true } }, 
"fiscal_code": "RSRNOU70S54S000L" }'

• 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​
• La presenza della struttura third_party_data indica a IO che il tuo Messaggio veicola uno o più Allegati:
  • id è il L'identificativo {third_party_data.id}​
  • has_attachments va obbligatoriamente impostato a true
• 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

{ "id": "01GS8744E24EZDG3XD5ECXB9RG" }

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.

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:

{ "attachments": [ { "id": "1", "url": "attachments/ricevuta.pdf", "content_type": "application/pdf", "name": "ricevuta.pdf" }, { "id": "2", "url": "attachments/evento.pdf", "content_type": "application/pdf", "name": "evento.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​

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:

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.