Aggiungere allegati

Questa funzionalità è riservata agli enti che hanno sottoscritto il programma Premium.

Cosa sono gli allegati

Sono documenti in formato PDF, mostrati in calce al contenuto del messaggio. Questi allegati vengono recuperati dai sistemi dell'ente mittente ogni volta che l'utente accede alla risorsa nell'app IO.

Quando l'utente apre un messaggio vengono recuperati, oltre ai metadati del contenuto del messaggio, anche quelli relativi ai metadati (endpoint 1). Il recupero del file vero e proprio avviene tramite l'endpoint 2, ovvero con una GET all'indirizzo {baseUrl}/messages/{id}/{url}

Per garantire l'accessibilità e la sicurezza dei documenti, devi utilizzare allegati in formato PDF/A-2a: assicurati di rispettare tale specifica.

Come funziona?

Step 0 - Esponi gli endpoint di recupero degli allegati

Per permettere a IO di recuperare il contenuto di un messaggio e dei suoi allegati, devi mettere a disposizione un REST web service conforme alla relativa OpenAPI.

Per maggiori informazioni, leggi le OpenAPI endpoint di recupero dei contenuti remotizzati.

Per includere gli allegati in un messaggio, oltre agli step indicati in Inviare un messaggio, devi seguire questi step:

Step 1 - Includi il blocco third_party_data

Includi il blocco third_party_data specificando l'id di correlazione remota, che IO ti restituirà quando ti chiederà i metadati e, successivamente, i byte degli allegati al particolare messaggio che stai inviando.

Step 2 - Specifica il valore TRUE nel campo has_attachments

Specifica il valore TRUE nel campo has_attachments presente nel blocco third_party_data.

Step 3 - Specifica il valore ADVANCED nel campo feature_level_type

Specifica il valore ADVANCED nel campo feature_level_type presente nella request.

Esempi

Esempio di chiamata per l’invio di un messaggio con allegati:

curl --location --request POST 'https://api.io.pagopa.it/api/v1/messages' \
--header 'Ocp-Apim-Subscription-Key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "content": {
    "subject": "Messaggio con allegati",
    "markdown": "# Titolo\n\nTesto del messaggio: contiene **allegati**!",
    "third_party_data": {
      "id": "c7832d5f-5946-48a3-ba9d-2d1e3aa3f7e5", 
      "has_attachments": true
    }
  },
  "feature_level_type": "ADVANCED",
  "fiscal_code": "<validFiscalCode>",
}'

Esempio di risposta positiva:

{
  "id": "01BX9NSMKVXXS5PSP2FATZMYYY"
}

Nota che non stai effettivamente inviando gli allegati al momento della creazione del messaggio: lo farai successivamente, quando il destinatario vorrà visualizzarli in app e IO invocherà l'API da te esposta allo scopo