CRU Configurazioni remote

Descrizione

Questa API consente alla tua Organizzazione di registrarsi presso IO come provider di contenuti remoti e di gestire nel tempo la registrazione.

La registrazione ha come oggetto le configurazioni, ossia l'insieme delle informazioni utili a creare la comunicazione tra IO e le infrastrutture della tua Organizzazione, secondo il protocollo definito nel paragrafo messaggi a contenuto remoto.

Per maggiori informazioni puoi consultare la pagina dedicata nella sezione Setup iniziale

Tutte le API descritte in questa pagina si riferiscono alle attività dell'Ente tramite Area Riservata e si basano sull'ottenimento e l'utilizzo della chiave "manage" che puoi recuperare nell'area di gestione dei Servizi di IO.

Le operazioni a disposizione comprendono:

1. La creazione di una nuova configurazione remota

2. La modifica di una configurazione remota esistente

3. Il recupero delle configurazioni remote definite

4. Il recupero di una particolare configurazione definita

La cancellazione di una configurazione remota non è al momento supportata

Fai riferimento al paragrafo Esempi per maggiori informazioni sull'utilizzo dei campi e sugli scenari d'uso censiti.

API "Create"

Con questa API puoi creare una nuova configurazione per ottenere il configuration_id da utilizzare in tutte le chiamate successive, anche per la creazione dei messaggi a contenuto remoto.

Create a new remote-content configuration

Create a new remote-content configuration using the provided payload

POSThttps://api.io.pagopa.it/api/v1/messages-sending/remote-contents/configurations

Body

application/json

name*string

Configuration name.

description*string

Configuration description.

has_precondition*HasPrecondition (string)

disable_lollipop_for*array of string (FiscalCode)

is_lollipop_enabled*boolean

Flag to check if lollipop is enabled

test_environmentRCConfigurationTestEnvironment (all of)

prod_environmentRCConfigurationProdEnvironment (object)

Response

201400500

Configuration created

Body

application/jsontext/json

name*string

Configuration name.

description*string

Configuration description.

has_precondition*HasPrecondition (string)

disable_lollipop_for*array of string (FiscalCode)

is_lollipop_enabled*boolean

Flag to check if lollipop is enabled

configuration_id*string (Ulid)

Ulid string.

Example: "01ARZ3NDEKTSV4RRFFQ69G5FAV"

test_environmentRCConfigurationTestEnvironment (all of)

prod_environmentRCConfigurationProdEnvironment (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.io.pagopa.it/api/v1/messages-sending/remote-contents/configurations', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "text",
      "description": "text",
      "has_precondition": "text",
      "disable_lollipop_for": [
        "SPNDNL80R13C555X"
      ],
      "is_lollipop_enabled": false
    }),
});
const data = await response.json();

Response

201400500

{
  "name": "text",
  "description": "text",
  "has_precondition": "text",
  "disable_lollipop_for": [
    "SPNDNL80R13C555X"
  ],
  "is_lollipop_enabled": false,
  "configuration_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "test_environment": {
    "base_url": "text",
    "details_authentication": {
      "header_key_name": "text",
      "key": "text",
      "type": "text"
    },
    "test_users": [
      "SPNDNL80R13C555X"
    ]
  },
  "prod_environment": {
    "base_url": "text",
    "details_authentication": {
      "header_key_name": "text",
      "key": "text",
      "type": "text"
    }
  }
}

API "Update"

Questa API ti consente di aggiornare una configurazione esistente, identificata dal configuration_id.

Update an existing remote-content configuration

Update an existing remote-content configuration using the provided payload

PUThttps://api.io.pagopa.it/api/v1/messages-sending/remote-contents/configurations/{configurationId}

Path parameters

configurationId*string (Ulid)

Ulid string.

Body

application/json

name*string

Configuration name.

description*string

Configuration description.

has_precondition*HasPrecondition (string)

disable_lollipop_for*array of string (FiscalCode)

is_lollipop_enabled*boolean

Flag to check if lollipop is enabled

test_environmentRCConfigurationTestEnvironment (all of)

prod_environmentRCConfigurationProdEnvironment (object)

Response

204400403404500

Configuration updated

Request

JavaScriptCurlPython

const response = await fetch('https://api.io.pagopa.it/api/v1/messages-sending/remote-contents/configurations/{configurationId}', {
    method: 'PUT',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "text",
      "description": "text",
      "has_precondition": "text",
      "disable_lollipop_for": [
        "SPNDNL80R13C555X"
      ],
      "is_lollipop_enabled": false
    }),
});
const data = await response.json();

Response

400500

{
  "type": "https://example.com/problem/constraint-violation",
  "title": "text",
  "status": 200,
  "detail": "There was an error processing the request",
  "instance": "https://example.com"
}

Allo scopo di garantire nel tempo la consistenza e il corretto funzionamento in app dei messaggi a contenuto remoto, è onere del mittente adeguare tempestivamente le configurazioni ogni qualvolta si riveli necessario, utilizzando l'API di gestione qui descritta.

API di recupero delle configurazioni definite

Con questa API puoi recuperare le configurazioni definite nell'ambito della sottoscrizione indicata negli header. Ciascun elemento ritornato nell'array rcConfigList riporta il nome, la descrizione, la presenza di precondizioni e i dati tecnici propri della configurazione (URL di base e informazioni di autenticazione).

Get all the owned remote-content configurations

Get all the owned remote-content configurations

GEThttps://api.io.pagopa.it/api/v1/messages-sending/remote-contents/configurations

Response

200400403404500

Return the configurations

Body

application/jsontext/json

rcConfigListarray of RCConfigurationResponse (all of)

Request

JavaScriptCurlPython

const response = await fetch('https://api.io.pagopa.it/api/v1/messages-sending/remote-contents/configurations', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400500

{
  "rcConfigList": [
    {
      "name": "text",
      "description": "text",
      "has_precondition": "text",
      "disable_lollipop_for": [
        "SPNDNL80R13C555X"
      ],
      "is_lollipop_enabled": false,
      "configuration_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "test_environment": {
        "base_url": "text",
        "details_authentication": {
          "header_key_name": "text",
          "key": "text",
          "type": "text"
        },
        "test_users": [
          "SPNDNL80R13C555X"
        ]
      },
      "prod_environment": {
        "base_url": "text",
        "details_authentication": {
          "header_key_name": "text",
          "key": "text",
          "type": "text"
        }
      },
      "user_id": "text"
    }
  ]
}

API di recupero di una configurazione

Con questa API, utilizzando come chiave il configuration_id, puoi recuperare i dati specifici della corrispondente configurazione.

Get the remote-content configuration identified by the configurationId

Get the remote-content configuration using the provided configurationId passed as path param

GEThttps://api.io.pagopa.it/api/v1/messages-sending/remote-contents/configurations/{configurationId}

Path parameters

configurationId*string (Ulid)

Ulid string.

Response

200400403404500

Return the configuration

Body

application/jsontext/json

name*string

Configuration name.

description*string

Configuration description.

has_precondition*HasPrecondition (string)

disable_lollipop_for*array of string (FiscalCode)

is_lollipop_enabled*boolean

Flag to check if lollipop is enabled

configuration_id*string (Ulid)

Ulid string.

Example: "01ARZ3NDEKTSV4RRFFQ69G5FAV"

test_environmentRCConfigurationTestEnvironment (all of)

prod_environmentRCConfigurationProdEnvironment (object)

user_id*string

Request

JavaScriptCurlPython

const response = await fetch('https://api.io.pagopa.it/api/v1/messages-sending/remote-contents/configurations/{configurationId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400500

{
  "name": "text",
  "description": "text",
  "has_precondition": "text",
  "disable_lollipop_for": [
    "SPNDNL80R13C555X"
  ],
  "is_lollipop_enabled": false,
  "configuration_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "test_environment": {
    "base_url": "text",
    "details_authentication": {
      "header_key_name": "text",
      "key": "text",
      "type": "text"
    },
    "test_users": [
      "SPNDNL80R13C555X"
    ]
  },
  "prod_environment": {
    "base_url": "text",
    "details_authentication": {
      "header_key_name": "text",
      "key": "text",
      "type": "text"
    }
  },
  "user_id": "text"
}

Esempi

Creazione di una configurazione remota

Nell'esempio riportato, si richiede la creazione di una nuova configurazione relativa al solo ambiente di produzione, per il quale sono indicati:

• la URL di base nel campo base_url ("https://theremotecontentdomain.tld/basepath")

• la relativa API key con cui si autenticherà su IO ("ac66427c-584b-4c81-9443-e761a226d33d", nel campokey, valore che i tuoi sistemi si attenderanno nell'header con nome "X-API-KEY" indicato nel campo header_key_name)

CURL

curl --location 'https://api.io.pagopa.it/api/v1/messages-sending/remote-contents/configurations' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Ocp-Apim-Subscription-Key: REDACTED' \
--data '{
  "name": "IoRemoteConfig01",
  "description": "Configurazione contenuti remoti per app IO - Server 1",
  "disable_lollipop_for": [],
  "has_precondition": "NEVER",
  "is_lollipop_enabled": false,
  "prod_environment": {
    "base_url": "https://theremotecontentdomain.tld/basepath",
    "details_authentication": {
      "header_key_name": "X-API-Key",
      "key": "ac66427c-584b-4c81-9443-e761a226d33d",
      "type": "API-KEY"
    }
  }
}'

Il campo has_precondition regola l'interpretazione, da parte di IO, del corrispondente campo has_precondition che indicherai in fase di creazione di un messaggio a contenuto remoto, secondo il seguente schema:

[non specificato]	Le precondizioni all'apertura del messaggio saranno mostrate coerentemente con l'impostazione di has_precondition a livello di singolo messaggio
has_precondition: NONE	Se il campo has_precondition non è specifciato a livello di singolo messaggio, questo non avrà precondizioni all'apertura; altrimenti, queste saranno mostrate coerentemente con quel valore
has_precondition: ONCE	Se il campo has_precondition non è specifciato a livello di singolo messaggio, questo avrà precondizioni all'apertura mostrate solo finché il messaggio stesso non sarà stato letto dal destinatario; altrimenti, le precondizioni saranno mostrate coerentemente con il valore indicato per quello specifico messaggio
has_precondition: ALWAYS	Se il campo has_precondition non è specifciato a livello di singolo messaggio, le precondizioni all'apertura saranno mostrate sempre, ad ogni apertura; altrimenti, saranno mostrate coerentemente con il valore indicato per quello specifico messaggio

Ricorda di impostare sempre il valore del campo details_authentication.type con la costante "API-KEY"

In risposta otterrai, nel campo "configuration_id", l'identificativo della configurazione che dovrai usare in tutte le chiamate seguenti, comprese quelle di creazione dei messaggi a contenuto remoto che dovranno essere serviti da essa.

Esempio di risposta attesa

{
    "configuration_id": "DFE12CC534E649CD8D63BF1BAA547029"
}

Creazione di configurazioni remote distinte per test e produzione

In questo secondo esempio, puoi vedere come creare una configurazione relativa agli ambienti di test e produzione.

I due blocchi "prod_environment" e "test_environment" sono utilizzati da IO per contattare la tua infrastruttura secondo il seguente schema:

indichi solo "prod_environment"	IO ti contatterà usando sempre quella configurazione
indichi solo "test_environment"	IO ti contatterà usando sempre quella configurazione
indichi sia "prod_environment" che "test_environment"	IO ti contatterà usando la configurazione indicata in "test_environment" solo se il codice fiscale del destinatario del messaggio è incluso nell'array "test_users", altrimenti lo farà usando la configurazione indicata in "prod_environment"

Nel selezionare i destinatari da indicare in "test_users" ricorda che non è consentito l'invio di messaggi di test all'utenza generale: assicurati di avere il consenso degli interessati e che questi siano a conoscenza del test in corso.

CURL

curl --request POST --location 'https://api.io.pagopa.it/api/v1/messages-sending/remote-contents/configurations' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Ocp-Apim-Subscription-Key: REDACTED' \
--data '{
  "name": "IoRemoteConfig01",
  "description": "Configurazione contenuti remoti per app IO - Server 1",
  "disable_lollipop_for": [],
  "has_precondition": "NEVER",
  "is_lollipop_enabled": false,
  "test_environment": {
    "base_url": "https://theremotecontentdomain_test.tld/basepath",
    "details_authentication": {
      "header_key_name": "X-API-Key",
      "key": "78aec1e4-f625-4644-b9d9-0f3fdc8cbe60",
      "type": "API-KEY"
    },
    "test_users": [
      "HGDZDH64P28G225I",
      "ZLMYPD56M70L669Y"
    ]
  },
  "prod_environment": {
    "base_url": "https://theremotecontentdomain.tld/basepath",
    "details_authentication": {
      "header_key_name": "X-API-Key",
      "key": "ac66427c-584b-4c81-9443-e761a226d33d",
      "type": "API-KEY"
    }
  }
}'

In risposta otterrai, nel campo "configuration_id", l'identificativo della configurazione che dovrai usare in tutte le chiamate seguenti, comprese quelle di creazione dei messaggi a contenuto remoto che dovranno essere serviti da essa.

Esempio di risposta attesa

{
    "configuration_id": "DFE12CC534E649CD8D63BF1BAA547029"
}

Recupero delle configurazioni definite

In questo esempio ti mostriamo come recuperare l'elenco completo delle configurazioni che hai definito nell'ambito della tua sottoscrizione:

CURL

curl --location 'https://api.io.pagopa.it/api/v1/messages-sending/remote-contents/configurations' \
--header 'Accept: application/json' \
--header 'Ocp-Apim-Subscription-Key: REDACTED'

Esempio di risposta attesa

{
  "rcConfigList": [
    {
      "configuration_id": "DFE12CC534E649CD8D63BF1BAA547029",
      "name": "IoRemoteConfig01",
      "description": "Configurazione contenuti remoti per app IO - Server 1",
      "disable_lollipop_for": [],
      "has_precondition": "NEVER",
      "is_lollipop_enabled": false,
      "test_environment": {
        "base_url": "https://theremotecontentdomain_test.tld/basepath",
        "details_authentication": {
          "header_key_name": "X-API-Key",
          "key": "78aec1e4-f625-4644-b9d9-0f3fdc8cbe60",
          "type": "API-KEY"
        },
        "test_users": [
          "HGDZDH64P28G225I",
          "ZLMYPD56M70L669Y"
        ]
      },
      "prod_environment": {
        "base_url": "https://theremotecontentdomain.tld/basepath",
        "details_authentication": {
          "header_key_name": "X-API-Key",
          "key": "ac66427c-584b-4c81-9443-e761a226d33d",
          "type": "API-KEY"
        }
      }
    }
  ]
}

Recupero di una specifica configurazione

In questo esempio puoi vedere come, essendo in possesso di un configuration_id, puoi recuperare tutte le informazioni relative a una configurazione definita in precedenza:

CURL

curl --location 'https://api.io.pagopa.it/api/v1/messages-sending/remote-contents/configurations/DFE12CC534E649CD8D63BF1BAA547029' \
--header 'Accept: application/json' \
--header 'Ocp-Apim-Subscription-Key: REDACTED'

Esempio di risposta attesa

{
    "configuration_id": "DFE12CC534E649CD8D63BF1BAA547029",
    "description": "Configurazione contenuti remoti per app IO - Server 1",
    "disable_lollipop_for": [],
    "has_precondition": "NEVER",
    "is_lollipop_enabled": false,
    "name": "IoRemoteConfig01",
    "prod_environment": {
        "base_url": "https://theremotecontentdomain.tld/basepath",
        "details_authentication": {
          "header_key_name": "X-API-Key",
          "key": "ac66427c-584b-4c81-9443-e761a226d33d",
          "type": "API-KEY"
        }
    }
}

Modifica di una configurazione esistente

In questo esempio ti mostriamo come puoi aggiornare i dati di una configurazione definita in precedenza, nello specifico qui si modifica la sua descrizione:

CURL

curl --location --request PUT 'https://api.io.pagopa.it/api/v1/messages-sending/remote-contents/configurations/DFE12CC534E649CD8D63BF1BAA547029' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Ocp-Apim-Subscription-Key: REDACTED' \
--data '{
    "configuration_id": "DFE12CC534E649CD8D63BF1BAA547029",
    "description": "***NUOVA*** configurazione contenuti remoti per app IO - Server 1",
    "disable_lollipop_for": [],
    "has_precondition": "NEVER",
    "is_lollipop_enabled": false,
    "name": "IoRemoteConfig01",
    "prod_environment": {
        "base_url": "https://theremotecontentdomain.tld/basepath",
        "details_authentication": {
          "header_key_name": "X-API-Key",
          "key": "ac66427c-584b-4c81-9443-e761a226d33d",
          "type": "API-KEY"
        }
    }
}'

Risposta attesa

204 No content.

Allo scopo di garantire nel tempo la consistenza e il corretto funzionamento in app dei messaggi a contenuto remoto, è responsabilità del mittente adeguare tempestivamente le configurazioni ogni qualvolta si riveli necessario, utilizzando l'API di gestione qui descritta.

Risorse utili

https://developer.io.italia.it/openapi.html#tag/remote-content