Tabella dei contenuti
OpenAPI endpoint di recupero dei contenuti remotizzati
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:
.png)
Messaggi a contenuto remoto: sequenza di alto livello
Diagramma dettagliato
Segue, con maggiore livello di dettaglio, la sequenza degli eventi che costituiscono il ciclo di vita di un messaggio a contenuto remoto:
Nei capitoli successivi troverai le sequenze di dettaglio di ciascuna fase.
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:
get
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}:
get
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'è |
|---|---|---|
| has_remote_content | details | Il messaggio ha contenuti remoti (titolo e corpo) |
| has_attachments | attachments | Solo per Enti Premium: il messaggio contiene allegati |
Struttura details: titolo e corpo del messaggio
Di seguito, un esempio di cosa puoi tornare nella struttura details in caso di messaggio a contenuto remoto se avevi specificato has_remote_content=true:
1{
2 "details":
3 {
4 "subject": "Questo è il titolo del messaggio",
5 "markdown": "Questo è il corpo del messaggio in formato **markdown**"
6 }
7}
8Ecco come apparirà in app il messaggio così impostato:
.png)
Come l'esempio apparirà in app
Struttura attachments: allegati PDF
Se 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:
1{
2 "attachments": [
3 {
4 "id": "410034f7-6cfd-43ef-b58b-2da1375ee218",
5 "content_type": "application/pdf",
6 "name": "Allegato 1.pdf",
7 "url": "/io_attachments/410034f7-6cfd-43ef-b58b-2da1375ee218",
8 "category": "DOCUMENT"
9 },
10 {
11 "id": "0004b1f5-7414-4db8-b9e0-1e38a7730fca",
12 "content_type": "application/pdf",
13 "name": "Allegato 2.pdf",
14 "url": "/io_attachments/0004b1f5-7414-4db8-b9e0-1e38a7730fca",
15 "category": "DOCUMENT"
16 }
17 ]
18}
19Nella tabella puoi trovare il significato di ciascun campo:
| Campo | Formato ammesso | Note |
|---|---|---|
| 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 una 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:
|
| category | stringa enumerata | Deve contenere il valore "DOCUMENT" |
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 della baseUrl specifico per l'allegato in questione, come restituito nei metadati con l'API di dettaglio.
get
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.
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.
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