LogoLogo
v5.0
v5.0
  • 🏠Guida tecnica
  • 🕗Changelog
  • 🔢Setup iniziale
    • Adesione tramite l'Area Riservata
    • Iscrizione al Developer Portal
    • Condivisione configurazione remota
  • Funzionalità
    • 📦Pubblicare un servizio
      • Creare un servizio
      • Provare un servizio in test
      • Revisione del servizio
      • Visibilità del servizio
      • Importare servizi nell'Area Riservata
      • Dati obbligatori
        • Attributi
        • Service Metadata
      • Informazioni sensibili
      • Argomento del servizio
      • Stato del servizio
      • Chiave manage
    • ✉️Inviare un messaggio
      • Messaggi di test
      • Inviare un messaggio tradizionale
      • Inviare un messaggio a contenuto remoto
      • Aggiungere allegati
  • API e specifiche
    • 📐OpenAPI
    • API Servizi
      • Manage Service: Get
      • Manage Service: Get keys
      • Manage Service: Get User Services
      • Manage Service: Create
      • Manage Service: Delete
      • Manage Service: Update
      • Manage Service: Request Review
      • Manage Service: Release
      • Manage Service: Get Released
      • Manage Service: Unpublish
      • Manage Service: Regenerate api key
      • Manage Service: Upload service logo
      • Upload organization logo
      • Service Topics: Get all service topics
    • API Messaggi
      • Get a User Profile using POST
      • Submit a Message passing the user fiscal_code in the request body
      • Get Message
      • Get Subscriptions Feed
      • ⚠️Get a User Profile
      • ⚠️Submit a Message passing the user fiscal_code as path parameter
    • Errori comuni
    • Specifiche API
    • OpenAPI endpoint di recupero dei contenuti remotizzati
  • 🔑Abilitazioni
    • Test con Codici Fiscali reali
    • Test invio avvisi pagoPA
    • Invio messaggi massivo
    • Subscription feed
    • Gestione dei servizi
    • Funzionalità Premium
  • Risorse Utili
    • ❓Supporto agli Enti (tutorial, FAQ)
    • 📘Glossario
Powered by GitBook
On this page
  1. API e specifiche
  2. API Messaggi

Submit a Message passing the user fiscal_code in the request body

PreviousGet a User Profile using POSTNextGet Message

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.

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à

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\n\n\nsiamo lieti di comunicarti che la tua **Carta di Identità** è disponibile per il ritiro presso i nostri sportelli.\n\nPuoi consultare gli orari sul [Portale del servizio](https://www.miosito.it/).\n\n\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.

Per andare a capo, utilizza la sequenza \n\n .

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° 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

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

payee

Questa funzionalità è in sperimentazione interna.

third_party_data

id *

Descrizione

identificativo third party univoco, generato dall'ente, necessario per poter aggregare il messaggio coi 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

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

has_remote_content

Descrizione

Indica che subject e markdown del messaggio sono remotizzati

Obbligatorio

No

Default

false

Tipo

Booleano

Esempio

true

has_attachments

Descrizione

Indica la presenza di allegati relativi al messaggio

Obbligatorio

No

Default

false

Tipo

Booleano

Esempio

false

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",
            //------------------------
            "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",
            //----------------------
            "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",
            //---------------------
            "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",
            //-------------------------
            "has_precondition": true,
            "has_remote_content": true,
            "has_attachments": true
            //-------------------------
        }
    },
    "fiscal_code": "AAAAAA00A00A000A"
}

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.

Risorse utili

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.

Puoi formattare il testo usando.

Se non includi questo campo, il fallback è sulla configurazione del servizio (fai riferimento a )

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

Per l’invio degli avvisi di pagamento è necessario richiedere

Campi riservati per utilizzi futuri

original_sender

original_receipt_date

summary

È importante che i tuoi sistemi siano istruiti a conservare gli identificativi dei messaggi spediti tramite IO, mantenendone la correlazione coi rispettivi destinatari.

🚧
💡
la sintassi Markdown
di lettura
di pagamento
specifica l’abilitazione.
https://developer.io.italia.it/openapi.html#operation/submitMessageforUserWithFiscalCodeInBody
  • Descrizione
  • POSTSubmit a Message passing the user fiscal_code in the request body
  • fiscal_code*
  • time_to_live
  • feature_level_type
  • content *
  • subject *
  • markdown *
  • require_secure_channels
  • due_date
  • payment_data
  • third_party_data
  • prescription_data
  • eu_covid_cert
  • legal_data
  • Esempi
  • Messaggio non remotizzato (statico)
  • Messaggio con titolo e corpo remoti
  • Messaggio con precondizioni
  • Messaggio remotizzato con allegati
  • Risposta attesa
  • Risorse utili

Submit a Message passing the user fiscal_code in the request body

post

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.

Authorizations
Body
time_to_liveinteger · min: 3600 · max: 604800Optional

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

Default: 3600Example: 3600
contentall ofRequired
fiscal_codestring · FiscalCodeOptional

User's fiscal code.

Example: SPNDNL80R13C555X
feature_level_typestringOptionalDefault: STANDARDExample: STANDARD
Responses
201
Message created.
application/json
400
Invalid payload.
application/json
401
Unauthorized
403
Forbidden.
429
Too many requests
500
The message cannot be delivered.
application/json
post
POST /api/v1/messages HTTP/1.1
Host: api.io.pagopa.it
Ocp-Apim-Subscription-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 1039

{
  "time_to_live": 3600,
  "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.",
    "require_secure_channels": true,
    "payment_data": {
      "amount": 1,
      "notice_number": "text",
      "invalid_after_due_date": true,
      "payee": {
        "fiscal_code": "12345678901"
      }
    },
    "prescription_data": {
      "nre": "text",
      "iup": "text",
      "prescriber_fiscal_code": "TCNZRO80R13C555Y"
    },
    "legal_data": {
      "sender_mail_from": "text",
      "has_attachment": true,
      "message_unique_id": "text",
      "original_message_url": "text",
      "pec_server_service_id": "text"
    },
    "eu_covid_cert": {
      "auth_code": "text"
    },
    "third_party_data": {
      "id": "text",
      "original_sender": "text",
      "original_receipt_date": "2018-10-13T00:00:00.000Z",
      "has_attachments": true,
      "has_remote_content": true,
      "has_precondition": "text",
      "summary": "text",
      "configuration_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
    },
    "due_date": "2018-10-13T00:00:00.000Z"
  },
  "default_addresses": {
    "email": "foobar@example.com"
  },
  "fiscal_code": "SPNDNL80R13C555X",
  "feature_level_type": "STANDARD"
}
{
  "id": "text"
}
require_secure_channels
Informazioni importanti circa il titolo (subject) del messaggio
Informazioni importanti circa il corpo (markdown) del messaggio