The Italian version constitutes the only official and legally binding version of the document. The English-language version of this document is provided solely as a courtesy to facilitate consultation by users. In the event of any discrepancies, interpretive differences, or inconsistencies between the Italian-language version and any translated version, the Italian text alone shall prevail and be deemed authoritative.

CRUs, remote configurations

Description

This API allows your Organization to register with IO as a remote content provider and manage the registration over time.

Registration has as its object the configurations, that is, the set of information useful to create communication between IO and your Organization's infrastructure, according to the protocol defined in the paragraph remote-content messages.

For more information you can consult the [dedicated page](../../initial-setup/remote-configuration.md) in the **Initial setup section**

All the APIs described on this page refer to the activities of the Institution via the [Reserved Area](https://app.gitbook.com/s/axttcUGV65V2IVRggmvR/) and are based on obtaining and using the ["manage” key](../../function/publish-a-service/manage-key/manage-key.md) which you can [retrieve](../../function/publish-a-service/manage-key/manage-key.md#recupera-la-manage-key) in the IO Services management area.

The available operations include:

The creation of a new remote configuration
The modification of an existing remote configuration
The retrieval of the defined remote configurations
The retrieval of a particular defined configuration

The deletion of a remote configuration is not currently supported

Refer to the paragraph [#examples](cru-remote-configurations.md#esempi "mention") for more information on field usage and the surveyed usage scenarios.

“Create” API

With this API you can create a new configuration to obtain the configuration_id for use in all subsequent calls, including the creation of remote-content messages.

post

Parameters

https://raw.githubusercontent.com/pagopa/io-functions-service-messages/master/openapi/index_external.yaml

“Update” API

This API allows you to update an existing configuration, identified by the configuration_id.

put

Parameters

https://raw.githubusercontent.com/pagopa/io-functions-service-messages/master/openapi/index_external.yaml

In order to ensure consistency and proper in-app operation of remote-content messages over time, the onus is on the sender **to promptly adjust the configurations** whenever necessary, using the management API described here.

Defined configurations retrieval API

With this API you can retrieve the configurations defined as part of the subscription indicated in the headers. Each element returned in the array rcConfigList bears the configuration's own name, description, whether there are any preconditions, and technical data (base URL and authentication information).

get

Parameters

https://raw.githubusercontent.com/pagopa/io-functions-service-messages/master/openapi/index_external.yaml

API for retrieving a configuration

With this API, using the configuration_id as a key, you can retrieve data specific to the corresponding configuration.

get

Parameters

https://raw.githubusercontent.com/pagopa/io-functions-service-messages/master/openapi/index_external.yaml

Examples

Creation of a remote configuration

In the example given, you are requested to create a new configuration related only to the production environment, for which the following are indicated:

the base URL in the field base_url ("https://theremotecontentdomain.tld/basepath")
the related API key with which it will authenticate on IO ("ac66427c-584b-4c81-9443-e761a226d33d" in the field**key**, value that your systems will expect in the header with the name "X-API-KEY" indicated in the field 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}'
20

The field has_precondition regulates the interpretation, by IO, of the corresponding field Has_precondition which will indicate in the creation phase of a remote-content message, according to the pattern:


[not specified]	The preconditions when opening the message will be shown consistently with the setting of has_precondition at the individual message level
has_precondition: NONE	If the field has_precondition is not specified at the individual message level, this will not have preconditions to its opening; otherwise these will be displayed consistently with that value
has_precondition: ONCE	If the field has_precondition is not specified at the individual message level, this will have preconditions to its opening, displayed only until the message itself is read by the recipient; otherwise, the preconditions will be displayed consistently with the value indicated for that specific message.
has_precondition: ALWAYS	If the field has_precondition is not specified at the individual message level, the preconditions to its opening will always be displayed at every opening, consistently with the value indicated for that specific message.

Remember to always set the value of the field **`details_authentication.type`** with the constant `"API-KEY`"

In response you will obtain, in the field "configuration_id", the identifier of the configuration that you should use in all following calls, including those for thecreation of remote-content messages which need to be served by it.

1{
2    "configuration_id": "DFE12CC534E649CD8D63BF1BAA547029"
3}
4

Creating separate remote configurations for tests and production

In this second example, you can see how to create a configuration related to tests and production.

The two blocks "prod_environment" and "test_environment" are used by IO to contact your infrastructure according to the following pattern:


you only indicate "prod_environment"	IO will contact you always using that configuration
you only indicate "test_environment"	IO will contact you always using that configuration
you only indicate both "prod_environment" and "test_environment"	IO will only contact you using the configuration indicated in "test_environment" if the message recipient’s fiscal code is included in the array "test_users", otherwise it will do so using the configuration indicated in "prod_environment"

When selecting the recipients to be indicated in `"test_users`" remember that **test messages cannot be sent to general users**: ensure that you have the consent of those concerned and that they are aware of the test in progress.

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": "Remote content configuration for IO app - 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}'
32

1{
2    "configuration_id": "DFE12CC534E649CD8D63BF1BAA547029"
3}
4

Retrieval of defined configurations

In this example we show you how to retrieve the complete list of configurations you have defined as part of your subscription:

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'
4

1{
2  "rcConfigList": [
3    {
4      "configuration_id": "DFE12CC534E649CD8D63BF1BAA547029",
5      "name": "IoRemoteConfig01",
6      "description": "Remote content configuration for IO app - 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}
33

Retrieving a specific configuration

In this example you can see how, being in possession of a configuration_id, you can retrieve all the information about a previously defined configuration:

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'
4

1{
2    "configuration_id": "DFE12CC534E649CD8D63BF1BAA547029",
3    "description": "Remote content configuration for IO app - 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}
17

Modification of an existing configuration

In this example we show you how you can update the data of a previously defined configuration, specifically here you edit its description:

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}'
21

1204 No content.
2

In order to ensure consistency and proper in-app operation of remote-content messages over time, the sender is responsible for **promptly adjusting the configurations** whenever necessary, using the management API described here.

Useful resources

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

On this page

Description

“Create” API

“Update” API

Defined configurations retrieval API

API for retrieving a configuration

Examples

Creation of a remote configuration

Creating separate remote configurations for tests and production

Retrieval of defined configurations

Retrieving a specific configuration

Modification of an existing configuration

Useful resources

Haven't completed onboarding yet and need help?

Write an email describing your problem or question to the address areariservata@assistenza.pagopa.it.

Need help with APIs and Integration?

Write an email describing your problem or question to the address:

io-service-management@pagopa.it

Tell us what you think

To report problems or give feedback, leave a comment in the GitHub space of the IO app

IO, the public services app

Table of contents

CRUs, remote configurations

Description

“Create” API

“Update” API

Defined configurations retrieval API

API for retrieving a configuration

Examples

Creation of a remote configuration

Creating separate remote configurations for tests and production

Retrieval of defined configurations

Retrieving a specific configuration

Modification of an existing configuration

Useful resources

Haven't completed onboarding yet and need help?

Need help with APIs and Integration?

Tell us what you think