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.
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 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*
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
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° 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: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
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
Descrizione
In app visualizza il pagamento come scaduto se la data attuale è successiva a due_date
Obbligatorio
No
Default
false
Tipo
Booleano
Esempio
false
third_party_data
configuration_id
*
Descrizione
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
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
has_remote_content
Descrizione
Obbligatorio
No
Default
false
Tipo
Booleano
Esempio
true
has_attachments
Descrizione
Obbligatorio
No
Default
false
Tipo
Booleano
Esempio
false
prescription_data
eu_covid_cert
legal_data
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
In tutti i casi sopra descritti, IO ritorna l'identificativo del messaggio che puoi usare per interrogarne lo stato tramite l'API Get Message.
https://developer.io.italia.it/openapi.html#operation/submitMessageforUserWithFiscalCodeInBody
Se stai inviando un messaggio con contenuti remoti, fai riferimento a
Se stai inviando un messaggio con contenuti remoti, fai riferimento a per i dettagli su come valorizzare questo campo.
Se non includi questo campo, il fallback è sulla configurazione del servizio (fai riferimento a )
identificativo univoco, ritornato dall'API descritta in , che indica la configurazione remota (third party) di riferimento per il messaggio
Indica la presenza di precondizioni all'apertura del messaggio; il contenuto delle precondizioni dovrà essere servito dall'ente esponendo la corrispondente API descritta in
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
Indica la presenza di allegati relativi al messaggio; i metadati degli allegati dovranno essere serviti dall'ente esponendo la corrispondente API descritta in , mentre i byte dei singoli allegati esponendo l'API descritta in
È 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.
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
.
This parameter specifies for how long (in seconds) the system will try to deliver the message to the channels configured by the user.
3600
Default addresses for notifying the recipient of the message in case no address for the related channel is set in his profile.
User's fiscal code.
SPNDNL80R13C555X
STANDARD