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:

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:

Retrieve the precondition of a Remote Content message

get

Returns the precondition associated to the Remote Content message with the provided message ID. User's fiscal code is required as header parameter.

Path parameters

idstring · min: 1Required

ID of the Remote Content message.

Header parameters

fiscal_codestring · min: 16 · max: 16Required

The fiscal code of the user, all upper case.

Pattern: [A-Z]{6}[0-9LMNPQRSTUV]{2}[ABCDEHLMPRST][0-9LMNPQRSTUV]{2}[A-Z][0-9LMNPQRSTUV]{3}[A-Z]

x-pagopa-lollipop-original-methodstring · enumOptional

The method of the endpoint called by IO app

Possible values:

x-pagopa-lollipop-original-urlstringOptional

The url of the endpoint called by IO app

Pattern: ^https://

signature-inputstringOptional

The signature input, needed to verify the signature header

Pattern: ^(?:sig\d+=[^,]*)(?:,\s*(?:sig\d+=[^,]*))*$

signaturestringOptional

The signature of the HTTP request, signed by the client with its private key.

Pattern: ^((sig[0-9]+)=:[A-Za-z0-9+/=]*:(, ?)?)+$

x-pagopa-lollipop-assertion-refone ofOptional

stringOptionalPattern: ^(sha256-[A-Za-z0-9-_=]{1,44})$

or

stringOptionalPattern: ^(sha384-[A-Za-z0-9-_=]{1,66})$

or

stringOptionalPattern: ^(sha512-[A-Za-z0-9-_=]{1,88})$

x-pagopa-lollipop-assertion-typestring · enumOptionalPossible values:

x-pagopa-lollipop-auth-jwtstring · min: 1Optional

x-pagopa-lollipop-public-keystring · min: 1Optional

represents a Base64url encode of a JWK Public Key

x-pagopa-lollipop-user-idstring · min: 16 · max: 16Optional

The user's fiscal code, all upper case.

Pattern: ^[A-Z]{6}[0-9LMNPQRSTUV]{2}[ABCDEHLMPRST][0-9LMNPQRSTUV]{2}[A-Z][0-9LMNPQRSTUV]{3}[A-Z]$

Responses

200

OK

*/*

400

Bad Request

*/*

401

Unauthorized

403

Forbidden

404

No message or precondition found for the provided ID.

*/*

429

Too Many Requests

500

Internal Server Error

*/*

get

HTTPcURLJavaScriptPython

GET /{id}/precondition HTTP/1.1
Host: messages
fiscal_code: text
Accept: */*

{
  "title": "text",
  "markdown": "text"
}

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}:

Retrieve a Remote Content message

get

Returns the Remote Content message with the provided message ID. User's fiscal code is required as header parameter.

Path parameters

idstring · min: 1Required

ID of the Remote Content message.

Header parameters

fiscal_codestring · min: 16 · max: 16Required

The fiscal code of the user, all upper case.

Pattern: [A-Z]{6}[0-9LMNPQRSTUV]{2}[ABCDEHLMPRST][0-9LMNPQRSTUV]{2}[A-Z][0-9LMNPQRSTUV]{3}[A-Z]

x-pagopa-lollipop-original-methodstring · enumOptional

The method of the endpoint called by IO app

Possible values:

x-pagopa-lollipop-original-urlstringOptional

The url of the endpoint called by IO app

Pattern: ^https://

signature-inputstringOptional

The signature input, needed to verify the signature header

Pattern: ^(?:sig\d+=[^,]*)(?:,\s*(?:sig\d+=[^,]*))*$

signaturestringOptional

The signature of the HTTP request, signed by the client with its private key.

Pattern: ^((sig[0-9]+)=:[A-Za-z0-9+/=]*:(, ?)?)+$

x-pagopa-lollipop-assertion-refone ofOptional

stringOptionalPattern: ^(sha256-[A-Za-z0-9-_=]{1,44})$

or

stringOptionalPattern: ^(sha384-[A-Za-z0-9-_=]{1,66})$

or

stringOptionalPattern: ^(sha512-[A-Za-z0-9-_=]{1,88})$

x-pagopa-lollipop-assertion-typestring · enumOptionalPossible values:

x-pagopa-lollipop-auth-jwtstring · min: 1Optional

x-pagopa-lollipop-public-keystring · min: 1Optional

represents a Base64url encode of a JWK Public Key

x-pagopa-lollipop-user-idstring · min: 16 · max: 16Optional

The user's fiscal code, all upper case.

Pattern: ^[A-Z]{6}[0-9LMNPQRSTUV]{2}[ABCDEHLMPRST][0-9LMNPQRSTUV]{2}[A-Z][0-9LMNPQRSTUV]{3}[A-Z]$

Responses

200

Found

application/jsontext/json

400

Bad Request

application/json

401

Unauthorized

403

Forbidden

404

No message found for the provided ID.

application/json

429

Too Many Requests

500

Internal Server Error

application/json

get

HTTPcURLJavaScriptPython

GET /{id} HTTP/1.1
Host: messages
fiscal_code: text
Accept: */*

{
  "attachments": [
    {
      "id": "text",
      "content_type": "text",
      "name": "text",
      "url": "text",
      "category": "text"
    }
  ],
  "details": {
    "markdown": "# This is a markdown header\nto show how easily markdown can be converted to **HTML**\nRemember: this has to be a long text.",
    "subject": "Welcome new user !"
  }
}

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'è
has_remote_content	details	Il messaggio ha contenuti remoti (titolo e corpo)
has_attachments	attachments	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

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:

Come l'esempio apparirà in app

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

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": "410034f7-6cfd-43ef-b58b-2da1375ee218",
      "content_type": "application/pdf",
      "name": "Allegato 1.pdf",
      "url": "/io_attachments/410034f7-6cfd-43ef-b58b-2da1375ee218",
      "category": "DOCUMENT"
    },
    {
      "id": "0004b1f5-7414-4db8-b9e0-1e38a7730fca",
      "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:

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: baseUrl è la parte comune comune (iniziale) degli endpoint che hai comunicato al team di IO in fase di condivisione delle informazioni di configurazione remota; id è l'identificativo di correlazione remota che avevi specificato nel blocco third_party_data in fase di invio del messaggio
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.

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.

Retrieve an attachment of a Remote Content message

get

Returns the Remote Content message with the provided message ID. User's fiscal code is required as header parameter.

Path parameters

idstring · min: 1Required

ID of the Remote Content message.

attachment_urlstring · min: 1Required

Header parameters

fiscal_codestring · min: 16 · max: 16Required

The fiscal code of the user, all upper case.

Pattern: [A-Z]{6}[0-9LMNPQRSTUV]{2}[ABCDEHLMPRST][0-9LMNPQRSTUV]{2}[A-Z][0-9LMNPQRSTUV]{3}[A-Z]

x-pagopa-lollipop-original-methodstring · enumOptional

The method of the endpoint called by IO app

Possible values:

x-pagopa-lollipop-original-urlstringOptional

The url of the endpoint called by IO app

Pattern: ^https://

signature-inputstringOptional

The signature input, needed to verify the signature header

Pattern: ^(?:sig\d+=[^,]*)(?:,\s*(?:sig\d+=[^,]*))*$

signaturestringOptional

The signature of the HTTP request, signed by the client with its private key.

Pattern: ^((sig[0-9]+)=:[A-Za-z0-9+/=]*:(, ?)?)+$

x-pagopa-lollipop-assertion-refone ofOptional

stringOptionalPattern: ^(sha256-[A-Za-z0-9-_=]{1,44})$

or

stringOptionalPattern: ^(sha384-[A-Za-z0-9-_=]{1,66})$

or

stringOptionalPattern: ^(sha512-[A-Za-z0-9-_=]{1,88})$

x-pagopa-lollipop-assertion-typestring · enumOptionalPossible values:

x-pagopa-lollipop-auth-jwtstring · min: 1Optional

x-pagopa-lollipop-public-keystring · min: 1Optional

represents a Base64url encode of a JWK Public Key

x-pagopa-lollipop-user-idstring · min: 16 · max: 16Optional

The user's fiscal code, all upper case.

Pattern: ^[A-Z]{6}[0-9LMNPQRSTUV]{2}[ABCDEHLMPRST][0-9LMNPQRSTUV]{2}[A-Z][0-9LMNPQRSTUV]{3}[A-Z]$

Responses

200

Success

application/octet-stream

Responsestring · binary

400

Bad Request

application/json

401

Unauthorized

403

Forbidden

404

No message found for the provided ID or no attachment found at the provided url.

application/json

429

Too Many Requests

500

Internal Server Error

application/json

503

Service Unavailable, check the Retry-After header to retry

application/json

get

HTTPcURLJavaScriptPython

GET /{id}/{attachment_url} HTTP/1.1
Host: messages
fiscal_code: text
Accept: */*

binary

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.