OpenAPI endpoint di recupero dei contenuti remotizzati
Last updated
Last updated
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:
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.
Per maggiori informazioni sul significato dei singoli campi , fai riferimento a Inviare un messaggio a contenuto remoto.
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.
Per maggiori informazioni sul significato dei singoli campi, fai riferimento a Inviare un messaggio a contenuto remoto.
has_remote_content
details
Completa titolo e corpo del messaggio. Per maggiori informazioni fai riferimento a Struttura details: titolo e corpo del messaggio
has_attachments
attachments
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
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
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:
id
stringa
IO richiede che il campo id
debba contenere un identificativo del singolo allegato che sia univoco all'interno del messaggio: è tua responsabilità definire questo campo e garantirne l'univocità presso i tuoi sistemi.
L'esempio riporta, a titolo esemplificativo, l'utilizzo di un GUID.
content_type
stringa enumerata
Deve contenere il valore "application/pdf
" in quanto IO accetta unicamente allegati in formato PDF conformi allo standard PDF/A-2a.
name
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".
url
stringa (in formato URL parziale)
Deve contenere il percorso relativo per il download dell’allegato. Questo perché IO scarica gli allegati tramite una richiesta GET
all'indirizzo {baseUrl}/messages/{id}/{url}
, dove:
baseUrl
è la parte comune (iniziale) degli endpoint che hai comunicato al team di IO in fase di condivisione delle informazioni di configurazione remota;
category
stringa enumerata
Deve contenere il valore "DOCUMENT"
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;
{url}
è il completamento della baseUrl
specifico per l'allegato in questione, come restituito nei metadati con l'API di dettaglio.
L'API deve restituire lo stream di byte del file allegato in formato application/octet-stream
binario.
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.
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.
https://raw.githubusercontent.com/pagopa/io-backend/master/openapi/consumed/api-third-party.yaml
Se in fase di #creazione-del-messaggio-con-contenuto-remoto hai valorizzato il campo (o se l'avevi indicato in fase di Configurazione remota), al momento dell'apertura del messaggio da parte del destinatario, IO recupererà le precondizioni attraverso una chiamata GET
ai tuoi sistemi, contenente in input i seguenti parametri:
l'id
di correlazione remota che avevi indicato nel blocco in fase di invio del messaggio;
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 in fase di invio del messaggio, per comporre una chiamata GET nella forma {base_url}/messages/{id}/precondition:
Se in fase di #creazione-del-messaggio-con-contenuto-remoto avevi incluso il flag o, essendo un Ente Premium, il flag , 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 in fase di invio del messaggio;
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 in fase di invio del messaggio, per comporre una chiamata GET nella forma {base_url}/messages/{id}:
A seconda dei flag che avevi specificato in al momento della #creazione-del-messaggio-con-contenuto-remoto, in risposta all'API dovrai includere:
id
è l'identificativo di correlazione remota che avevi specificato nel blocco in fase di invio del messaggio
{id}
è l'identificativo che avevi specificato nel blocco in fase di invio del messaggio;
Fai attenzione: in questo caso l'identificativo univoco è l'id
di correlazione remota che avevi indicato in in occasione dell'invio del messaggio.
Returns the precondition associated to the Remote Content message with the provided message ID. User's fiscal code is required as header parameter.
ID of the Remote Content message.
OK
The title to be rendered in App
The markdown content to be rendered in App
Returns the Remote Content message with the provided message ID. User's fiscal code is required as header parameter.
ID of the Remote Content message.
Success
Returns the Remote Content message with the provided message ID. User's fiscal code is required as header parameter.
ID of the Remote Content message.
Found