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 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
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).
I tuoi sistemi dovranno verificare che il codice fiscale inviato in input corrisponda esattamente al destinatario inteso e in caso di esito positivo, verrà trasmesso ad IO il contenuto delle precondizioni.
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
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
Se [flag]=true | Struttura da inserire | Descrizione |
---|---|---|
|
| Completa titolo e corpo del messaggio. Per maggiori informazioni fai riferimento a Struttura details: titolo e corpo del messaggio |
|
| Solo per Enti Premium: compila i metadati degli allegati al messaggio. Per maggiori informazioni fai riferimento a Struttura attachments: allegati PDF |
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 un 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
Tutte le API qui descritte prevedono una serie di header opzionali denominati "x-pagopa-lollipop-...
" e due header di "signature
", che non devono essere valorizzati, ma di cui ti chiediamo di non escludere la ricezione.
Risorse utili
https://raw.githubusercontent.com/pagopa/io-backend/master/openapi/consumed/api-third-party.yaml
Last updated