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.
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
.
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"
Message created.
The identifier of the created message.
fiscal_code
*
fiscal_code
*
Descrizione | Codice fiscale del destinatario del messaggio |
Obbligatorio | Sì |
Tipo | Stringa |
Esempio |
|
time_to_live
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 |
|
Tipo | Intero |
Esempio |
|
feature_level_type
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 |
|
Tipo | Stringa enumerata |
Valori Accettati |
|
Esempio |
|
content
*
content
*
subject
*
subject
*
Descrizione | Titolo del messaggio, la cui lunghezza deve essere compresa tra 10 e 120 caratteri |
Obbligatorio | Sì |
Tipo | Stringa |
Esempio |
|
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 |
|
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 usando la sintassi Markdown.
Per andare a capo, utilizza la sequenza \n\n
.
require_secure_channels
require_secure_channels
Descrizione | Indica che il messaggio contiene informazioni sensibili e/o riservate; se impostato a |
Obbligatorio | No |
Default | Se non includi questo campo, il fallback è sulla configurazione del servizio (fai riferimento a require_secure_channels) |
Tipo | Booleano |
Esempio |
|
due_date
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 |
|
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
payment_data
Per l’invio degli avvisi di pagamento è necessario richiedere specifica l’abilitazione.
amount
*
amount
*
Descrizione | Importo in centesimi di euro dell’avviso di pagamento emesso su piattaforma pagoPA |
Obbligatorio | Sì, per pagamenti pagoPA |
Tipo | Intero |
Esempio |
|
notice_number
*
notice_number
*
Descrizione | Codice avviso di un avviso di pagamento emesso su piattaforma pagoPA |
Obbligatorio | Sì, per i pagamenti pagoPA |
Tipo | Stringa |
Esempio |
|
È importante che il codice fiscale del servizio mittente corrisponda al codice fiscale dell’ente creditore che emette l’avviso pagoPA.
invalid_after_due_date
invalid_after_due_date
Descrizione | In app visualizza il pagamento come scaduto se la data attuale è successiva a |
Obbligatorio | No |
Default |
|
Tipo | Booleano |
Esempio |
|
payee
payee
Questa funzionalità è in sperimentazione interna.
third_party_data
third_party_data
id
*
id
*
Descrizione | identificativo third party univoco, generato dall'ente, necessario per poter aggregare il messaggio coi suoi contenuti remoti |
Obbligatorio | Sì |
Tipo | Stringa |
Esempio |
|
has_precondition
has_precondition
Descrizione | Indica la presenza di precondizioni all'apertura del messaggio |
Obbligatorio | No |
Default |
|
Tipo | Stringa enumerata |
Valori Accettati |
|
Esempio |
|
has_remote_content
has_remote_content
Descrizione | Indica che |
Obbligatorio | No |
Default |
|
Tipo | Booleano |
Esempio |
|
has_attachments
has_attachments
Descrizione | Indica la presenza di allegati relativi al messaggio |
Obbligatorio | No |
Default |
|
Tipo | Booleano |
Esempio |
|
prescription_data
prescription_data
Questa funzionalità è in sperimentazione interna.
eu_covid_cert
eu_covid_cert
Questa funzionalità è riservata ai soggetti autorizzati.
legal_data
legal_data
Questa funzionalità è in sperimentazione interna.
Esempi
Messaggio non remotizzato (statico)
Messaggio con titolo e corpo remoti
Messaggio con precondizioni
Messaggio remotizzato con allegati
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:
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.
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.
Risorse utili
https://developer.io.italia.it/openapi.html#operation/submitMessageforUserWithFiscalCodeInBody