Submit a Message passing the user fiscal_code in the request body

Descrizione

Questa API consente l’invio di messaggi verso un cittadino identificato tramite Codice Fiscale. Prima di inviare un messaggio, dovrai verificare che il cittadino sia iscritto a IO e che il servizio possa inviare comunicazioni al cittadino stesso.

Per utilizzare questa API devi aggiungere alla chiamata l'header Ocp-Apim-Subscription-Key contenente la chiave "use" primaria o secondaria del servizio scelto per l'invio del messaggio

Submit a Message passing the user fiscal_code in the request body

Submits a message to a user with STANDARD or ADVANCED features based on feature_level_type value. On error, the reason is returned in the response payload. In order to call submitMessageforUser, before sending any message, the sender MUST call getProfile and check that the profile exists (for the specified fiscal code) and that the sender_allowed field of the user's profile it set to true.

POSThttps://api.io.pagopa.it/api/v1/messages

Authorization

SubscriptionKey

Body

application/json

time_to_liveTimeToLiveSeconds (integer)

This parameter specifies for how long (in seconds) the system will try to deliver the message to the channels configured by the user.

Example: 3600

content*MessageContent (all of)

default_addressesobject

Default addresses for notifying the recipient of the message in case no address for the related channel is set in his profile.

fiscal_codeFiscalCode (string (FiscalCode))

User's fiscal code.

Example: "SPNDNL80R13C555X"

feature_level_typeFeatureLevelType (string)

Example: "STANDARD"

Response

201400401403429500

Message created.

Headers

Body

application/json

idstring

The identifier of the created message.

Request

JavaScriptCurlPython

const response = await fetch('https://api.io.pagopa.it/api/v1/messages', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "content": {
        "subject": "Welcome new user !",
        "markdown": "# This is a markdown header\n\nto show how easily markdown can be converted to **HTML**\n\nRemember: this has to be a long text."
      }
    }),
});
const data = await response.json();

Response

201400500

{
  "id": "text"
}

fiscal_code*

Descrizione	Codice fiscale del destinatario del messaggio
Obbligatorio	Sì
Tipo	Stringa
Esempio	AAAAAA00A00A000A

time_to_live

Questo parametro è deprecato.

Descrizione	Tempo espresso in secondi che specifica il tempo di retry di delivery del messaggio da parte di IO; passato tale tempo, non viene prodotta alcuna notifica push né email di inoltro
Obbligatorio	No
Default	3600
Tipo	Intero
Esempio	3600

feature_level_type

Descrizione	Indica se il messaggio è inviato nell'ambito di una sottoscrizione Premium, o se è da considerarsi un messaggio standard
Obbligatorio	No
Default	STANDARD
Tipo	Stringa enumerata
Valori Accettati	STANDARD -> il messaggio è da considerarsi un normale messaggio IO ADVANCED -> al messaggio sono correlate informazioni aggiuntive avanzate. È possibile specificare questo valore solo se si è titolari di una sottoscrizione Premium.
Esempio	ADVANCED

content *

subject *

Descrizione	Titolo del messaggio, la cui lunghezza deve essere compresa tra 10 e 120 caratteri
Obbligatorio	Sì
Tipo	Stringa
Esempio	Rinnova la tua carta d'identità

Se stai inviando un messaggio con contenuti remoti, fai riferimento a #informazioni-importanti-circa-il-titolo-subject-del-messaggio

Ricorda che, ai sensi dell'art. 7.3 delle Linee Guida AgID, il titolo del messaggio non può contenere dati personali e ne va assicurata la minimizzazione all'interno del markdown *

markdown *

Descrizione	Testo del messaggio in formato markdown la cui lunghezza deve essere compresa tra 80 e 10000 caratteri
Obbligatorio	Sì
Tipo	Stringa
Esempio	Gentile Mario,\n\nsiamo lieti di comunicarti che la tua **Carta di Identità** è disponibile per il ritiro presso i nostri sportelli. \nPuoi consultare gli orari sul [Portale del servizio](https://www.miosito.it/).\n\n*Lo Staff*

Se stai inviando un messaggio con contenuti remoti, fai riferimento a per i dettagli su come valorizzare questo campo.

Quando componi e trasmetti il testo del messaggio in formato markdown, ricorda di impostare il charset UTF-8, così da garantire la corretta visualizzazione dei caratteri accentati.

Puoi formattare il testo e attivare funzioni speciali nei tuoi messaggi usando la sintassi Markdown.

require_secure_channels

Descrizione	Indica che il messaggio contiene informazioni sensibili e/o riservate; se impostato a true saranno prodotte notifiche push anonimizzate e non saranno inoltrate copie email dei messaggi
Obbligatorio	No
Default	Se non includi questo campo, il fallback è sulla configurazione del servizio (fai riferimento a require_secure_channels)
Tipo	Booleano
Esempio	true

due_date

Descrizione	Permette di associare al messaggio un promemoria. Il formato data deve essere ISO-8601 e fuso orario UTC
Obbligatorio	No
Tipo	Stringa
Esempio	2018-10-13T00:00:00.000Z

Fai attenzione al fuso orario! La data deve essere espressa nel fuso orario UTC (Z). In Italia si usa il fuso UTC+1 quando è in vigore l'ora solare, mentre si usa il fuso UTC+2 quando è in vigore l'ora legale.

Esempio:

2022-09-30T22:00:00Z --> In Italia è la mezzanotte del 1° ottobre 2022

2022-11-30T23:00:00Z --> In Italia è la mezzanotte del 1° novembre 2022

Fai attenzione all'orario! Se la data di scadenza non prevede un orario specifico, solitamente si fa riferimento alla fine della giornata. Inserisci correttamente l'orario per evitare di mostrare una data di scadenza errata.

Esempio:

✅ 12 gennaio (23:59:59) --> L'utente può pagare entro la giornata del 12 gennaio

❌ 12 gennaio (00:00:01) --> L'utente può pagare entro la giornata dell'11 gennaio

La data di scadenza del messaggio è separata rispetto a quella dell'eventuale posizione debitoria associata e può essere specificata anche a in assenza di di quest'ultima

Se hai sottoscritto l'accordo Premium, IO genererà per te promemoria di lettura o di pagamento in prossimità della data di scadenza indicata: i promemoria saranno inviati al dispositivo del destinatario sotto forma di notifiche push

payment_data

Per l’invio degli avvisi di pagamento è necessario richiedere specifica l’abilitazione.

amount *

Descrizione	Importo in centesimi di euro dell’avviso di pagamento emesso su piattaforma pagoPA
Obbligatorio	Sì, per pagamenti pagoPA
Tipo	Intero
Esempio	100

notice_number *

Descrizione	Codice avviso di un avviso di pagamento emesso su piattaforma pagoPA
Obbligatorio	Sì, per i pagamenti pagoPA
Tipo	Stringa
Esempio	301011100007347557

È importante che il codice fiscale del servizio mittente corrisponda al codice fiscale dell’ente creditore che emette l’avviso pagoPA.

invalid_after_due_date

Descrizione	In app visualizza il pagamento come scaduto se la data attuale è successiva a due_date
Obbligatorio	No
Default	false
Tipo	Booleano
Esempio	false

payee

Questa funzionalità è riservata agli enti che hanno concordato con PagoPA l'abilitazione alla separazione tra i codici fiscali del mittente e del beneficiario della posizione debitoria.

third_party_data

configuration_id *

Descrizione	identificativo univoco, ritornato dall'API descritta in CRU Configurazioni remote, che indica la configurazione remota (third party) di riferimento per il messaggio
Obbligatorio	Sì
Tipo	Stringa
Esempio	0e9852ccb8a04128bd637c807b9d80d3

Per maggiori informazioni fai riferimento alla sezione Configurazione remota

id *

Descrizione	identificativo third party univoco, generato dall'ente, necessario per poter associare il messaggio ai suoi contenuti remoti
Obbligatorio	Sì
Tipo	Stringa
Esempio	2d5e0bcf-7ac3-4afc-a8bd-ac3c27582b91

has_precondition

Descrizione	Indica la presenza di precondizioni all'apertura del messaggio; il contenuto delle precondizioni dovrà essere servito dall'ente esponendo la corrispondente API descritta in Endpoint di recupero delle precondizioni all'apertura del messaggio
Obbligatorio	No
Default	NONE
Tipo	Stringa enumerata
Valori Accettati	NONE -> il messaggio non ha precondizioni ONCE -> le precondizioni sono mostrate prima dell'apertura in app solo finché il messaggio non viene letto dal destinatario ALWAYS -> le precondizioni sono mostrate prima di ogni apertura del messaggio in app
Esempio	ONCE

Se popolato, il valore di questo campo ridefinisce, per il messaggio corrente, il comportamento di default indicato in fase di configurazione (per maggiori informazioni fai riferimento a Configurazione remota)

has_remote_content

Descrizione	Indica che subject e markdown del messaggio sono remotizzati; il contenuto di tali campi dovrà essere servito dall'ente esponendo la corrispondente API descritta in Endpoint di recupero dei dettagli del messaggio
Obbligatorio	No
Default	false
Tipo	Booleano
Esempio	true

has_attachments

Descrizione	Indica la presenza di allegati relativi al messaggio; i metadati degli allegati dovranno essere serviti dall'ente esponendo la corrispondente API descritta in Endpoint di recupero dei dettagli del messaggio, mentre i byte dei singoli allegati esponendo l'API descritta in Endpoint di recupero dei byte del singolo allegato
Obbligatorio	No
Default	false
Tipo	Booleano
Esempio	false

🚧 Campi riservati per utilizzi futuri

original_sender

original_receipt_date

summary

prescription_data

Questa funzionalità è in sperimentazione interna.

eu_covid_cert

Questa funzionalità è riservata ai soggetti autorizzati.

legal_data

Questa funzionalità è in sperimentazione interna.

Esempi

Messaggio non remotizzato (statico)

### REQUEST
curl --location --request POST 'https://api.io.pagopa.it/api/v1/messages' \
--header 'Content-Type: application/json' \
--header 'Ocp-Apim-Subscription-Key: __YOUR_API_KEY__' \
--data-raw '{
"content": {
"subject": "Welcome new user !",
"markdown": "# This is a markdown header\n\nto show how easily markdown can be converted to **HTML**\n\nRemember: this has to be a long text."
},
“feature_level_type”: “STANDARD”,
"fiscal_code": "AAAAAA00A00A000A"
}'

Messaggio con titolo e corpo remoti

Contenuto della richiesta

{
     "content": {
        "subject": "Titolo del messaggio mostrato in inbox",
        "markdown": "Questo testo sarà sostituito con il markdown remoto specificato al momento della fruizione del messaggio",
        "third_party_data": {
            "id": "2d5e0bcf-7ac3-4afc-a8bd-ac3c27582b91",
            //-----------------------------------------------------
            "configuration_id": "0e9852ccb8a04128bd637c807b9d80d3",
            "has_remote_content": true
            //-----------------------------------------------------
        }
    },
    "fiscal_code": "AAAAAA00A00A000A"
}

Messaggio con precondizioni

Contenuto della richiesta

{
     "content": {
        "subject": "Titolo del messaggio",
        "markdown": "Testo del messaggio lungo almeno ottanta caratteri nel rispetto delle specifiche di integrazione con IO",
        "third_party_data": {
            "id": "2d5e0bcf-7ac3-4afc-a8bd-ac3c27582b91",
            "configuration_id": "0e9852ccb8a04128bd637c807b9d80d3",
            //----------------------
            "has_precondition": true
            //----------------------
        }
    },
    "fiscal_code": "AAAAAA00A00A000A"
}

Messaggio remotizzato con allegati

Contenuto della richiesta

{
     "content": {
        "subject": "Titolo del messaggio",
        "markdown": "Testo del messaggio lungo almeno ottanta caratteri nel rispetto delle specifiche di integrazione con IO",
        "third_party_data": {
            "id": "2d5e0bcf-7ac3-4afc-a8bd-ac3c27582b91",
            "configuration_id": "0e9852ccb8a04128bd637c807b9d80d3",
            //---------------------
            "has_attachments": true
            //---------------------
        }
    },
    "fiscal_code": "AAAAAA00A00A000A"
}

Nel blocco third_party_data è possibile specificare più combinazioni dei flag has_precondition, has_remote_content e has_attachments (quest'ultimo solo se hai sottoscritto l'Accordo relativo alle Funzionalità Premium), come nell'esempio:

Contenuto della richiesta

{
     "content": {
        "subject": "Titolo del messaggio",
        "markdown": "Testo del messaggio lungo almeno ottanta caratteri nel rispetto delle specifiche di integrazione con IO",
        "third_party_data": {
            "id": "2d5e0bcf-7ac3-4afc-a8bd-ac3c27582b91",
            "configuration_id": "0e9852ccb8a04128bd637c807b9d80d3",
            //-------------------------
            "has_precondition": true,
            "has_remote_content": true,
            "has_attachments": true
            //-------------------------
        }
    },
    "fiscal_code": "AAAAAA00A00A000A"
}

IO effettua controlli di coerenza tra i flag indicati in questa fase e quanto ritornato coi dettagli del messaggio remoto; come esempio, se indichi "has_attachments": true ma in fase di recupero dei dettagli del messaggio non includi la struttura "attachments", il tuo destinatario riceverà un errore e non potrà visualizzare il messaggio.

Per maggiori dettagli fai riferimento a OpenAPI endpoint di recupero dei contenuti remotizzati

Risposta attesa

In tutti i casi sopra descritti, IO ritorna l'identificativo del messaggio che puoi usare per interrogarne lo stato tramite l'API Get Message.

Contenuto della risposta

{
    "id": "01EM6X4JB9VSZTQ8H16KMQFCEJ"
}

Se hai sottoscritto l'accordo Premium, oltre a sapere se sia stato correttamente inviato potrai conoscerne lo stato di lettura e, se presente, di pagamento della posizione debitoria associata.

💡 È importante che i tuoi sistemi siano istruiti a conservare gli identificativi dei messaggi spediti tramite IO, mantenendone la correlazione coi rispettivi destinatari e le eventuali informazioni di contesto remoto.

Risorse utili

https://developer.io.italia.it/openapi.html#operation/submitMessageforUserWithFiscalCodeInBody