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:

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

  • 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.

Endpoint di recupero dei dettagli 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.

Per maggiori informazioni sul significato dei singoli campi, fai riferimento a Inviare un messaggio a contenuto remoto.

Esempio di risposta attesa da IO

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

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:

{
  "details":
  {
    "subject": "Questo è il titolo del messaggio",
    "markdown": "Questo è il corpo del messaggio in formato **markdown**"
  }
}

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.

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

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:

{
  "attachments": [
    {
      "id": "7de61a5a-6829-4f76-9e37-dfd229cd3d62",
      "content_type": "application/pdf",
      "name": "Allegato 1.pdf",
      "url": "/io_attachments/410034f7-6cfd-43ef-b58b-2da1375ee218",
      "category": "DOCUMENT"
    },
    {
      "id": "1d9e3a59-2eed-496c-84dd-1fb9682d24eb",
      "content_type": "application/pdf",
      "name": "Allegato 2.pdf",
      "url": "/io_attachments/0004b1f5-7414-4db8-b9e0-1e38a7730fca",
      "category": "DOCUMENT"
    }
  ]
}

Nella tabella puoi trovare il significato di ciascun campo:

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;

  • {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.

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