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.

Endpoint di recupero dell'elenco dei metadati degli allegati

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

Retrieve a Third Party message

get

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

Path parameters
idstring · min: 1Required

ID of the Third Party 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
get
GET /{id} HTTP/1.1
Host: messages
fiscal_code: text
Accept: */*

{
  "attachments": [
    {
      "id": "text",
      "content_type": "text",
      "name": "text",
      "url": "text",
      "category": "text"
    }
  ],
  "details": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

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": "Nome dell'allegato",
      "url": "<percorso relativo dell'allegato>"
    },
    {
      "id": "4815162342",
      "content_type": "application/pdf",
      "name": "Nome dell'allegato 2",
      "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}/{url}, dove baseUrl è l'endpoint comunicato al team di IO.

Endpoint di recupero dei byte del singolo allegato

chema che riassume la sequenza delle operazioni coinvolte nel 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

get

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

Path parameters
idstring · min: 1Required

ID of the Third Party 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
get
GET /{id}/{attachment_url} HTTP/1.1
Host: messages
fiscal_code: text
Accept: */*

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

PreviousAggiungere allegati (Premium)NextOpenAPI

Last updated