Specifiche degli 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.

Il servizio deve esporre due endpoint, che il backend di IO richiamerà quando necessario.

Una volta pronti, comunica al team di IO gli endpoint (baseUrl) e la relativa API Key.

Per comunicare col team di IO puoi usare l'indirizzo email [e-mail]

Endpoint di recupero dell'elenco dei metadati degli allegati

Lo schema che riassume la sequenza delle operazioni coinvolte nel recupero dei dati da parte di IO.

Retrieve a Third Party message

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

GET//messages/{id}

Path parameters

id*string

ID of the Third Party message.

Header parameters

Response

200400401403404429500

Found

Body

application/jsontext/json

attachmentsarray of ThirdPartyAttachment (object)

detailsobject

Request

JavaScriptCurlPython

const response = await fetch('//messages/{id}', {
    method: 'GET',
    headers: {
      "fiscal_code": "text"
    },
});
const data = await response.json();

Response

200400404500

{
  "attachments": [
    {
      "id": "text",
      "content_type": "text",
      "name": "text",
      "url": "text",
      "category": "DOCUMENT"
    }
  ]
}

L'identificativo {id} che riceverai in questa chiamata corrisponderà a quello che avevi specificato nel blocco third_party_data in fase di invio del messaggio.

Esempio di risposta attesa

{
  "attachments": [
    {
      "id": "123456789",
      "content_type": "application/pdf",
      "name": "Allegato 1.pdf",
      "url": "<percorso relativo dell'allegato>"
    },
    {
      "id": "4815162342",
      "content_type": "application/pdf",
      "name": "Allegato 2.pdf",
      "url": "<percorso relativo dell'allegato 2>"
    }
  ]
}

Il campo content_type deve contenere il valore "application/pdf" in quanto IO accetta unicamente allegati in formato PDF conformi allo standard PDF/A.

Il campo url 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 è l'endpoint che hai comunicato al team di IO in fase di onboarding

• id è l'identificativo che avevi specificato nel blocco in fase di invio del messaggio

La composizione delle varie parti costituisce la URL completa di download del singolo allegato nell'ambito del servizio REST che esponi, come illustrato nel capitolo seguente.

Il campo name deve contenere il nome dell'allegato così come comparirà nel messaggio, all'interno della sezione "Allegati": sceglilo con cura in modo da comunicare correttamente con il tuo destinatario.

Aggiungi sempre l'estensione .pdf nei campi name per consentire al sistema operativo di destinazione una corretta gestione del file eventualmente scaricato sul dispositivo.

Endpoint di recupero dei byte del singolo allegato

Lo schema che riassume la sequenza delle operazioni coinvolte nel recupero dei byte del singolo allegato.

Retrieve an attachment of a Third Party message

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

GET//messages/{id}/{attachment_url}

Path parameters

id*string

ID of the Third Party message.

attachment_url*string

Header parameters

Response

200400401403404429500503

Success

Body

application/octet-stream

string (binary)

Request

JavaScriptCurlPython

const response = await fetch('//messages/{id}/{attachment_url}', {
    method: 'GET',
    headers: {
      "fiscal_code": "text"
    },
});
const data = await response.json();

Response

200400404500503

binary

Autorizzazioni

API Key

IO garantisce che il codice fiscale nella request corrisponda a quello dell'utente che sta provando a recuperare gli allegati. Il codice fiscale viene inviato attraverso l'header fiscal_code.

L'ente deve verificare che il Codice Fiscale dell’utente sia autorizzato ad accedere al dato richiesto.

In futuro, verranno aggiunti ulteriori metodi di autenticazione (Bearer Token, OAuth Token etc.)