Tabella dei contenuti
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.
Le operazioni a disposizione comprendono:
- La creazione di una nuova configurazione remota
- La modifica di una configurazione remota esistente
- Il recupero delle configurazioni remote definite
- Il recupero di una particolare configurazione definita
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.
post
API "Update"
Questa API ti consente di aggiornare una configurazione esistente, identificata dal configuration_id.
put
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
API di recupero di una configurazione
Con questa API, utilizzando come chiave il configuration_id, puoi recuperare i dati specifici della corrispondente configurazione.
get
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 campo**key**, valore che i tuoi sistemi si attenderanno nell'header con nome "X-API-KEY" indicato nel campo header_key_name)
1curl --location 'https://api.io.pagopa.it/api/v1/messages-sending/remote-contents/configurations' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'Ocp-Apim-Subscription-Key: REDACTED' \
5--data '{
6 "name": "IoRemoteConfig01",
7 "description": "Configurazione contenuti remoti per app IO - Server 1",
8 "disable_lollipop_for": [],
9 "has_precondition": "NEVER",
10 "is_lollipop_enabled": false,
11 "prod_environment": {
12 "base_url": "https://theremotecontentdomain.tld/basepath",
13 "details_authentication": {
14 "header_key_name": "X-API-Key",
15 "key": "ac66427c-584b-4c81-9443-e761a226d33d",
16 "type": "API-KEY"
17 }
18 }
19}'
20Il 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 |
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.
1{
2 "configuration_id": "DFE12CC534E649CD8D63BF1BAA547029"
3}
4Creazione 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" |
1curl --request POST --location 'https://api.io.pagopa.it/api/v1/messages-sending/remote-contents/configurations' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'Ocp-Apim-Subscription-Key: REDACTED' \
5--data '{
6 "name": "IoRemoteConfig01",
7 "description": "Configurazione contenuti remoti per app IO - Server 1",
8 "disable_lollipop_for": [],
9 "has_precondition": "NEVER",
10 "is_lollipop_enabled": false,
11 "test_environment": {
12 "base_url": "https://theremotecontentdomain_test.tld/basepath",
13 "details_authentication": {
14 "header_key_name": "X-API-Key",
15 "key": "78aec1e4-f625-4644-b9d9-0f3fdc8cbe60",
16 "type": "API-KEY"
17 },
18 "test_users": [
19 "HGDZDH64P28G225I",
20 "ZLMYPD56M70L669Y"
21 ]
22 },
23 "prod_environment": {
24 "base_url": "https://theremotecontentdomain.tld/basepath",
25 "details_authentication": {
26 "header_key_name": "X-API-Key",
27 "key": "ac66427c-584b-4c81-9443-e761a226d33d",
28 "type": "API-KEY"
29 }
30 }
31}'
32In 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.
1{
2 "configuration_id": "DFE12CC534E649CD8D63BF1BAA547029"
3}
4Recupero delle configurazioni definite
In questo esempio ti mostriamo come recuperare l'elenco completo delle configurazioni che hai definito nell'ambito della tua sottoscrizione:
1curl --location 'https://api.io.pagopa.it/api/v1/messages-sending/remote-contents/configurations' \
2--header 'Accept: application/json' \
3--header 'Ocp-Apim-Subscription-Key: REDACTED'
41{
2 "rcConfigList": [
3 {
4 "configuration_id": "DFE12CC534E649CD8D63BF1BAA547029",
5 "name": "IoRemoteConfig01",
6 "description": "Configurazione contenuti remoti per app IO - Server 1",
7 "disable_lollipop_for": [],
8 "has_precondition": "NEVER",
9 "is_lollipop_enabled": false,
10 "test_environment": {
11 "base_url": "https://theremotecontentdomain_test.tld/basepath",
12 "details_authentication": {
13 "header_key_name": "X-API-Key",
14 "key": "78aec1e4-f625-4644-b9d9-0f3fdc8cbe60",
15 "type": "API-KEY"
16 },
17 "test_users": [
18 "HGDZDH64P28G225I",
19 "ZLMYPD56M70L669Y"
20 ]
21 },
22 "prod_environment": {
23 "base_url": "https://theremotecontentdomain.tld/basepath",
24 "details_authentication": {
25 "header_key_name": "X-API-Key",
26 "key": "ac66427c-584b-4c81-9443-e761a226d33d",
27 "type": "API-KEY"
28 }
29 }
30 }
31 ]
32}
33Recupero 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:
1curl --location 'https://api.io.pagopa.it/api/v1/messages-sending/remote-contents/configurations/DFE12CC534E649CD8D63BF1BAA547029' \
2--header 'Accept: application/json' \
3--header 'Ocp-Apim-Subscription-Key: REDACTED'
41{
2 "configuration_id": "DFE12CC534E649CD8D63BF1BAA547029",
3 "description": "Configurazione contenuti remoti per app IO - Server 1",
4 "disable_lollipop_for": [],
5 "has_precondition": "NEVER",
6 "is_lollipop_enabled": false,
7 "name": "IoRemoteConfig01",
8 "prod_environment": {
9 "base_url": "https://theremotecontentdomain.tld/basepath",
10 "details_authentication": {
11 "header_key_name": "X-API-Key",
12 "key": "ac66427c-584b-4c81-9443-e761a226d33d",
13 "type": "API-KEY"
14 }
15 }
16}
17Modifica 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:
1curl --location --request PUT 'https://api.io.pagopa.it/api/v1/messages-sending/remote-contents/configurations/DFE12CC534E649CD8D63BF1BAA547029' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'Ocp-Apim-Subscription-Key: REDACTED' \
5--data '{
6 "configuration_id": "DFE12CC534E649CD8D63BF1BAA547029",
7 "description": "***NUOVA*** configurazione contenuti remoti per app IO - Server 1",
8 "disable_lollipop_for": [],
9 "has_precondition": "NEVER",
10 "is_lollipop_enabled": false,
11 "name": "IoRemoteConfig01",
12 "prod_environment": {
13 "base_url": "https://theremotecontentdomain.tld/basepath",
14 "details_authentication": {
15 "header_key_name": "X-API-Key",
16 "key": "ac66427c-584b-4c81-9443-e761a226d33d",
17 "type": "API-KEY"
18 }
19 }
20}'
211204 No content.
2Risorse utili
In questa pagina
Descrizione
API "Create"
API "Update"
API di recupero delle configurazioni definite
API di recupero di una configurazione
Esempi
Creazione di una configurazione remota
Creazione di configurazioni remote distinte per test e produzione
Recupero delle configurazioni definite
Recupero di una specifica configurazione
Modifica di una configurazione esistente
Risorse utili
Hai bisogno di aiuto?
Scrivi un’email in cui descrivi il tuo problema o dubbio all’indirizzo onboarding@io.italia.it
Dicci cosa ne pensi
Per segnalare problemi o dare feedback, lascia un commento nello spazio Github dell'app IO