OpenAPI endpoint di recupero dei contenuti remotizzati
Leggi questa pagina per saperne di più sui messaggi a contenuto remoto.
Prima di poter inviare messaggi a contenuto remoto è necessario seguire la procedura illustrata in Condivisione configurazione remota
Nello scenario di invio tradizionale di un messaggio su IO, l'Ente richiama l'API esposta per la creazione del messaggio e IO procede alla sua gestione completa in app:
Nel diagramma che segue ti mostriamo la sequenza di eventi che vede coinvolti il suo sistema e quello di IO nello scambio di informazioni col destinatario di un messaggio a contenuto remoto:
Endpoint di recupero delle precondizioni all'apertura del messaggio
Se in fase di #creazione-del-messaggio-con-contenuto-remoto avevi incluso il flag has_precondition, al momento della richiesta di visualizzazione in app da parte del destinatario IO dovrà recuperare titolo e testo delle precondizioni da mostrare prima di procedere con l'apertura vera e propria del messaggio; lo farà con una chiamata GET
con cui passerà ai tuoi sistemi:
l'
id
di correlazione remota che avevi indicato nel blocco third_party_data in fase di invio del messaggio;il codice fiscale del destinatario (come header).
Il tuo sistema potrà quindi recuperare e trasmettere a IO il contenuto delle precondizioni verificando al contempo che la richiesta pervenuta sia relativa proprio a quel destinatario.
IO utilizzerà la base_url
, che avevi comunicato in fase di impostazione delle informazioni di configurazione remota, e l'identificativo di correlazione, che avevi specificato nel blocco third_party_data in fase di invio del messaggio, per comporre una chiamata GET nella forma {base_url}/messages/{id}/precondition:
Per maggiori informazioni sul significato dei singoli campi , fai riferimento a Inviare un messaggio a contenuto remoto.
Endpoint di recupero dei dettagli del messaggio
Se in fase di #creazione-del-messaggio-con-contenuto-remoto avevi incluso il flag has_remote_content o, essendo un Ente Premium, il flag has_attachments, IO dovrà recuperare il contenuto del messaggio dai tuoi sistemi al momento della sua visualizzazione in app, e userà l'API qui descritta; lo farà con una chiamata GET
con cui ti restituirà:
l'
id
di correlazione remota che avevi indicato nel blocco third_party_data in fase di invio del messaggio;il codice fiscale del destinatario (come header).
Il tuo sistema potrà quindi recuperare il contenuto del messaggio verificando al contempo che la richiesta pervenuta sia relativa proprio a quel destinatario.
IO utilizzerà la base_url
, che avevi comunicato al team di IO in fase di impostazione delle informazioni di configurazione remota, e l'identificativo di correlazione, che avevi specificato nel blocco third_party_data in fase di invio del messaggio, per comporre una chiamata GET nella forma {base_url}/messages/{id}:
Per maggiori informazioni sul significato dei singoli campi, fai riferimento a Inviare un messaggio a contenuto remoto.
Esempio di risposta attesa da IO
A seconda dei flag che avevi specificato in third_party_data al momento della #creazione-del-messaggio-con-contenuto-remoto, in risposta all'API dovrai includere:
Se [flag]=true | Struttura da inserire | Cos'è |
---|---|---|
|
| Il messaggio ha contenuti remoti (titolo e corpo) |
|
| Solo per Enti Premium: il messaggio contiene allegati |
Fai attenzione a rispettare i flag che dichiari: IO effettua un controllo di coerenza tra i flag che avevi indicato alla creazione del messaggio e le strutture presenti nella risposta dell'API di dettaglio al momento della sua fruizione in app
Struttura details
: titolo e corpo del messaggio
details
: titolo e corpo del messaggioDi seguito, un esempio di cosa puoi tornare nella struttura details
in caso di messaggio a contenuto remoto se avevi specificato has_remote_content=true
:
Ecco come apparirà in app il messaggio così impostato:
Il titolo mostrato nel messaggio con contenuto remoto può essere differente da quello che avevi indicato al momento della sua creazione (il campo subject
in Submit a Message passing the user fiscal_code in the request body): quest'ultimo, infatti, è utilizzato come titolo nell'elenco dei messaggi in app ed è statico.
⚠️Ti ricordiamo che ai sensi delle Linee Guida IO non deve includere informazioni sensibili nel titolo del messaggio, e ove necessarie nel corpo dovranno rispettare il principio di minimizzazione.
Quando componi e trasmetti il testo del messaggio in formato markdown ricorda di impostare il charset UTF-8
(per garantire la corretta visualizzazione dei caratteri accentati) e utilizza la sequenza "\n\n
" per mandare a capo il testo creando un nuovo paragrafo.
Puoi usare i seguenti tag di formattazione del testo:
#
,##
(seguiti da uno spazio) per le intestazioni* per il corsivo
** per il grassetto
[Lorem Ipsum](https://mio.sito) per i link
Struttura attachments
: allegati PDF
attachments
: allegati PDFSe la tua organizzazione ha sottoscritto l'accordo Premium, ecco un esempio di cosa puoi indicare se nella struttura details
avevi specificato has_remote_content=true
:
Nella tabella puoi trovare il significato di ciascun campo:
Campo | Formato ammesso | Note |
---|---|---|
| stringa | IO richiede che il campo L'esempio riporta, a titolo esemplificativo, l'utilizzo di una GUID. |
| stringa enumerata | Deve contenere il valore " |
| stringa (terminata in ".pdf") | Deve contenere il nome dell'allegato come comparirà nel messaggio, all'interno della sezione "Allegati": sceglilo con cura in modo da comunicare correttamente con il tuo destinatario. ⚠️ È obbligatorio aggiungere sempre la desinenza ".pdf". |
| stringa (in formato URL parziale) | Deve contenere il percorso relativo per il download dell’allegato. Questo perché IO scarica gli allegati tramite una richiesta
|
| stringa enumerata | Deve contenere il valore |
Endpoint di recupero dei byte del singolo allegato
Se hai sottoscritto l'Accordo Premium e nella risposta all'API di dettaglio illustrata nel capitolo precedente hai incluso i metadati di uno o più allegati, quando il destinatario del messaggio vorrà visualizzarli, IO recuperà il contenuto presso i tuoi sistemi componendo la URL di una chiamata GET
nel formato {baseUrl}/{id}/{url}
, dove:
baseUrl
è la parte comune (iniziale) degli endpoint che hai comunicato al team di IO in fase di impostazione delle informazioni di configurazione remota;{id}
è l'identificativo che avevi specificato nel blocco third_party_data in fase di invio del messaggio;{url}
è il completamento dellabaseUrl
specifico per l'allegato in questione, come restituito nei metadati con l'API di dettaglio.
Fai attenzione: in questo caso l'identificativo univoco è l'id
di correlazione remota che avevi indicato in third_party_data in occasione dell'invio del messaggio.
L'API deve restituire lo stream di byte del file allegato in formato application/octet-stream
binario.
Autorizzazioni
API Key
IO garantisce che il codice fiscale nella request corrisponda a quello dell'utente che sta provando a recuperare i dati del messaggio. Il codice fiscale viene inviato attraverso l'header fiscal_code
.
È responsabilità dell'Ente individuare correttamente il codice fiscale dell'utente.
Nota sugli header "Lollipop"
Tutte le API qui descritte prevedono opzionalmente una serie di header denominati "x-pagopa-lollipop-...
" e due header di "signature
": tali header sono riservati per l'utilizzo di un sistema di certificazione del dispositivo del destinatario di prossima introduzione, per il quale riceverai opportuna comunicazione e documentazione.
Per il momento, puoi ignorarne la presenza nelle specifiche ma ti raccomandiamo di non impedirne esplicitamente la ricezione da parte di IO.