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.
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.
.jpg)
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:
- 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.
Il risultato che vogliamo ottenere in questo esempio è che il Cittadino riceva un Messaggio IO simile a quello mostrato di seguito:
Esempio di Messaggio con Allegati
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.
Request
1curl --location --request
2POST 'https://api.io.pagopa.it/api/v1/messages' \
3--header 'Ocp-Apim-Subscription-Key: 217d66f7a83642578111d733e1741813' \
4--header 'Content-Type: application/json' \
5--data-raw ' { "feature_level_type": "ADVANCED", "time_to_live": 3600, "content":
6{ "subject": "Partecipazione Evento", "markdown": "Gentile Mario Rossi,\n\r\n\r
7abbiamo accettato la tua richiesta di partecipazione all'\''evento e ti inviamo
8in allegato la ricevuta del pagamento della tua quota e la brochure con tutte
9le informazioni utili.\n\rA Ti aspettiamo!\n\rL'\''Amministrazione Comunale di Ipazia.", "third_party_data": { "id": "000003", "has_attachments": true } },
10"fiscal_code": "RSRNOU70S54S000L" }'
11- 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:
- 1.id è il L'identificativo {third_party_data.id}
- 2.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.
.jpg)
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
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.
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