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
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à |
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
Markdownmarkdown *
| |
---|
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* |
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
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.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🕛️00Z --> In Italia è la mezzanotte del 1° ottobre 2022
2022-11-30T23🕛️00Z --> In Italia è la mezzanotte del 1° dicembre 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🕛️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
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
Questa funzionalità è riservata agli enti che hanno concordato con PagoPA l'abilitazione alla separazione tra i codici fiscali del mittente del messaggio 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 |
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 allapertura del messaggio |
Obbligatorio | No |
Default | NEVER |
Tipo | Stringa enumerata |
Valori Accettati | NEVER -> 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
has_attachments
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)
1### REQUEST
2curl --location --request POST 'https://api.io.pagopa.it/api/v1/messages' \
3--header 'Content-Type: application/json' \
4--header 'Ocp-Apim-Subscription-Key: __YOUR_API_KEY__' \
5--data-raw '{
6"content": {
7"subject": "Welcome new user !",
8"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."
9},
10“feature_level_type”: “STANDARD”,
11"fiscal_code": "AAAAAA00A00A000A"
12}'
13
Messaggio con titolo e corpo remoti
1{
2 "content": {
3 "subject": "Titolo del messaggio mostrato in inbox",
4 "markdown": "Questo testo sarà sostituito con il markdown remoto specificato al momento della fruizione del messaggio",
5 "third_party_data": {
6 "id": "2d5e0bcf-7ac3-4afc-a8bd-ac3c27582b91",
7 //-----------------------------------------------------
8 "configuration_id": "0e9852ccb8a04128bd637c807b9d80d3",
9 "has_remote_content": true
10 //-----------------------------------------------------
11 }
12 },
13 "fiscal_code": "AAAAAA00A00A000A"
14}
15
Messaggio con precondizioni
1{
2 "content": {
3 "subject": "Titolo del messaggio",
4 "markdown": "Testo del messaggio lungo almeno ottanta caratteri nel rispetto delle specifiche di integrazione con IO",
5 "third_party_data": {
6 "id": "2d5e0bcf-7ac3-4afc-a8bd-ac3c27582b91",
7 "configuration_id": "0e9852ccb8a04128bd637c807b9d80d3",
8 //----------------------
9 "has_precondition": true
10 //----------------------
11 }
12 },
13 "fiscal_code": "AAAAAA00A00A000A"
14}
15
Messaggio remotizzato con allegati
1{
2 "content": {
3 "subject": "Titolo del messaggio",
4 "markdown": "Testo del messaggio lungo almeno ottanta caratteri nel rispetto delle specifiche di integrazione con IO",
5 "third_party_data": {
6 "id": "2d5e0bcf-7ac3-4afc-a8bd-ac3c27582b91",
7 "configuration_id": "0e9852ccb8a04128bd637c807b9d80d3",
8 //---------------------
9 "has_attachments": true
10 //---------------------
11 }
12 },
13 "fiscal_code": "AAAAAA00A00A000A"
14}
15
1{
2 "content": {
3 "subject": "Titolo del messaggio",
4 "markdown": "Testo del messaggio lungo almeno ottanta caratteri nel rispetto delle specifiche di integrazione con IO",
5 "third_party_data": {
6 "id": "2d5e0bcf-7ac3-4afc-a8bd-ac3c27582b91",
7 "configuration_id": "0e9852ccb8a04128bd637c807b9d80d3",
8 //-------------------------
9 "has_precondition": true,
10 "has_remote_content": true,
11 "has_attachments": true
12 //-------------------------
13 }
14 },
15 "fiscal_code": "AAAAAA00A00A000A"
16}
17
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.
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.
1{
2 "id": "01EM6X4JB9VSZTQ8H16KMQFCEJ"
3}
4
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