Spedizione messaggi via API

Pianificazione di una notifica da servizi

Le applicazioni che prevedono la spedizione di notifiche tramite l'AppIO possono integrarsi tramite le API di backoffice esposte da AppIO.

Send a new message.

Send a message through the service template. The service_instance parameter identifies the IO service through which the message is sent, and it's a configuration parameter provided by the service administrator. The placeholder list is also provided by the service administrator, and the API user has to provide the values. Upon receiving a call to this endpoint, GovIO builds the actual message to be sent to the IO services. In the process, the placeholders values are substituted in the message body and message subject by a template engine. A 201 response status denotes that the final message is built and scheduled by GovIO for the expedition to the IO services.

POSThttp://localhost:10001/messages

Query parameters

Body

application/json

taxcode*string

The fiscal code of the receiver, all upper case.

Example: "PCRMJV76P12B782Z"

Pattern: [A-Z]{6}[0-9LMNPQRSTUV]{2}[ABCDEHLMPRST][0-9LMNPQRSTUV]{2}[A-Z][0-9LMNPQRSTUV]{3}[A-Z]

paymentGovioMessagePaymentItem (object)

Optional Field, marks the message as a payment message.

emailstring (email)

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

scheduled_expedition_date*string (date-time)

The date when this message has to be sent to the citizien.

due_datestring (date-time)

The expiration date for the message subject. When set, the IO app shows an expiration date for this message.

placeholdersarray of Placeholder (object)

The placeholder values to be substituted in the message template.

Response

201400401403429503default

Successful operation.

Body

application/hal+json

taxcode*string

The fiscal code of the receiver, all upper case.

Example: "PCRMJV76P12B782Z"

Pattern: [A-Z]{6}[0-9LMNPQRSTUV]{2}[ABCDEHLMPRST][0-9LMNPQRSTUV]{2}[A-Z][0-9LMNPQRSTUV]{3}[A-Z]

paymentGovioMessagePaymentItem (object)

Optional Field, marks the message as a payment message.

emailstring (email)

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

scheduled_expedition_date*string (date-time)

The date when this message has to be sent to the citizien.

due_datestring (date-time)

The expiration date for the message subject. When set, the IO app shows an expiration date for this message.

id*integer (int64)

GovIO Message Id.

Example: 1

status*GovioMessageStatus (enum)

acceptedthrottledscheduledrecipient_allowedprofile_not_existssender_not_alloweddeniedsentbad_requestforbiddenprocessedcreated

status_detailstring

Pattern: [\s\S]*

appio_message_idstring

Pattern: .*

creation_date*string (date-time)

expedition_datestring (date-time)

last_update_statusstring (date-time)

subject*string

Example: "Lorem ipsum"

markdown*string

Example: "# Lorem ipsum dolor sit amet\nUt enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."

sender_id*UserId (integer (int64))

User identifier.

Example: 1

service_instance_id*GovioServiceInstanceId (integer (int64))

Govio Service Instance Id.

Example: 1

_linksobject

_embeddedobject

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:10001/messages?service_instance=1&idempotency_key=123e4567-e89b-12d3-a456-426614174000', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "scheduled_expedition_date": "2024-12-26T17:08:33.625Z",
      "taxcode": "PCRMJV76P12B782Z"
    }),
});
const data = await response.json();

Response

201400401403429503default

{
  "taxcode": "PCRMJV76P12B782Z",
  "payment": {
    "amount": 62.12,
    "notice_number": 300012548634478200,
    "invalid_after_due_date": false,
    "payee_taxcode": 10000000001
  },
  "email": "[e-mail]",
  "scheduled_expedition_date": "2024-12-26T17:08:33.625Z",
  "due_date": "2024-12-26T17:08:33.625Z",
  "id": 1,
  "status": "accepted",
  "status_detail": "text",
  "appio_message_id": "text",
  "creation_date": "2024-12-26T17:08:33.625Z",
  "expedition_date": "2024-12-26T17:08:33.625Z",
  "last_update_status": "2024-12-26T17:08:33.625Z",
  "subject": "Lorem ipsum",
  "markdown": "# Lorem ipsum dolor sit amet\nUt enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.",
  "sender_id": 1,
  "service_instance_id": 1,
  "_links": {
    "self": {
      "href": "https://govhub.it/govio/messages/1"
    },
    "service_instance": {
      "href": "https://govhub.it/govio/service-instances/1"
    },
    "sender": {
      "href": "https://govhub.it/govio/users/1"
    }
  },
  "_embedded": {
    "service-instance": {
      "service_id": 1,
      "organization_id": 1,
      "template_id": 1,
      "enabled": true,
      "io_service_id": "text",
      "id": 1,
      "_links": {
        "self": {
          "href": "https://govhub.it/govio/service-instances/1"
        },
        "service": {
          "href": "https://govhub.it/govio/services/1"
        },
        "organization": {
          "href": "https://govhub.it/govio/organizations/1"
        },
        "template": {
          "href": "https://govhub.it/govio/templates/1"
        }
      },
      "_embedded": {
        "service": {
          "id": 1,
          "service_name": "SUAP-Integrazione",
          "description": "Service for customer management.",
          "_links": {
            "self": {
              "href": "https://govhub.it/govregistry/services/1"
            },
            "logo": {
              "href": "https://govhub.it/govregistry/services/1/logo"
            },
            "logo_miniature": {
              "href": "https://govhub.it/govregistry/services/logo_miniature"
            }
          }
        },
        "organization": {
          "id": 1,
          "legal_name": "Giletti S.R.L.",
          "tax_code": "01234567890",
          "_links": {
            "self": {
              "href": "https://govhub.it/govregistry/organizations/1"
            },
            "logo": {
              "href": "https://govhub.it/govregistry/organizations/1/logo"
            },
            "logo_miniature": {
              "href": "https://govhub.it/govregistry/organizations/logo_miniature"
            }
          }
        },
        "template": {
          "name": "Spedizione Messaggio CIE",
          "description": "Segnala la scadenza della proprià C.I.E.",
          "subject": "Scadenza CIE n. ${cie.uppercase}",
          "message_body": "Salve, con la presente la informiamo che in data ${due_date} scadrà la Carta di Identità elettronica numero ${cie.uppercase}.",
          "has_payment": false,
          "has_due_date": false,
          "id": 1,
          "_links": {
            "self": {
              "href": "https://govhub.it/govio/templates/1"
            },
            "placeholders": {
              "href": "https://govhub.it/govio/templates/1/placeholders"
            }
          }
        }
      }
    },
    "sender": {
      "principal": "user-1",
      "full_name": "Antonio Giscardi",
      "email": "[e-mail]",
      "enabled": false,
      "id": 1,
      "_links": {
        "self": {
          "href": "https://govhub.it/govregistry/users/1"
        },
        "avatar": {
          "href": "https://gravatar.com/avatar/md5/d2c457c9c97c9e4e2226317fe5685892/s=100&d=identicon"
        }
      }
    }
  }
}

La richiesta al servizio di pianificazione di una nuova notifica prevede il parametro idempotency_key che consente alla piattaforma di riconoscere eventuali richieste duplicate.

Per la consultazione dei messaggi inviati sono disponibili le risorse REST di ricerca e lettura.

List Govio Messages

Read and Filter the Govio Messages.

GEThttp://localhost:10001/messages

Query parameters

Response

200400401403429503default

Successful operation.

Body

application/hal+json

page*PageInfo (object)

items*array of GovioMessage (all of)

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:10001/messages?sort=unsorted&sort_direction=asc', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400401403429503default

{
  "page": {
    "offset": 20,
    "limit": 25,
    "total": 32
  },
  "items": [
    {
      "taxcode": "PCRMJV76P12B782Z",
      "payment": {
        "amount": 62.12,
        "notice_number": 300012548634478200,
        "invalid_after_due_date": false,
        "payee_taxcode": 10000000001
      },
      "email": "[e-mail]",
      "scheduled_expedition_date": "2024-12-26T17:08:33.625Z",
      "due_date": "2024-12-26T17:08:33.625Z",
      "id": 1,
      "status": "accepted",
      "status_detail": "text",
      "appio_message_id": "text",
      "creation_date": "2024-12-26T17:08:33.625Z",
      "expedition_date": "2024-12-26T17:08:33.625Z",
      "last_update_status": "2024-12-26T17:08:33.625Z",
      "subject": "Lorem ipsum",
      "markdown": "# Lorem ipsum dolor sit amet\nUt enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.",
      "sender_id": 1,
      "service_instance_id": 1,
      "_links": {
        "self": {
          "href": "https://govhub.it/govio/messages/1"
        },
        "service_instance": {
          "href": "https://govhub.it/govio/service-instances/1"
        },
        "sender": {
          "href": "https://govhub.it/govio/users/1"
        }
      },
      "_embedded": {
        "service-instance": {
          "service_id": 1,
          "organization_id": 1,
          "template_id": 1,
          "enabled": true,
          "io_service_id": "text",
          "id": 1,
          "_links": {
            "self": {
              "href": "https://govhub.it/govio/service-instances/1"
            },
            "service": {
              "href": "https://govhub.it/govio/services/1"
            },
            "organization": {
              "href": "https://govhub.it/govio/organizations/1"
            },
            "template": {
              "href": "https://govhub.it/govio/templates/1"
            }
          },
          "_embedded": {
            "service": {
              "id": 1,
              "service_name": "SUAP-Integrazione",
              "description": "Service for customer management.",
              "_links": {
                "self": {
                  "href": "https://govhub.it/govregistry/services/1"
                },
                "logo": {
                  "href": "https://govhub.it/govregistry/services/1/logo"
                },
                "logo_miniature": {
                  "href": "https://govhub.it/govregistry/services/logo_miniature"
                }
              }
            },
            "organization": {
              "id": 1,
              "legal_name": "Giletti S.R.L.",
              "tax_code": "01234567890",
              "_links": {
                "self": {
                  "href": "https://govhub.it/govregistry/organizations/1"
                },
                "logo": {
                  "href": "https://govhub.it/govregistry/organizations/1/logo"
                },
                "logo_miniature": {
                  "href": "https://govhub.it/govregistry/organizations/logo_miniature"
                }
              }
            },
            "template": {
              "name": "Spedizione Messaggio CIE",
              "description": "Segnala la scadenza della proprià C.I.E.",
              "subject": "Scadenza CIE n. ${cie.uppercase}",
              "message_body": "Salve, con la presente la informiamo che in data ${due_date} scadrà la Carta di Identità elettronica numero ${cie.uppercase}.",
              "has_payment": false,
              "has_due_date": false,
              "id": 1,
              "_links": {
                "self": {
                  "href": "https://govhub.it/govio/templates/1"
                },
                "placeholders": {
                  "href": "https://govhub.it/govio/templates/1/placeholders"
                }
              }
            }
          }
        },
        "sender": {
          "principal": "user-1",
          "full_name": "Antonio Giscardi",
          "email": "[e-mail]",
          "enabled": false,
          "id": 1,
          "_links": {
            "self": {
              "href": "https://govhub.it/govregistry/users/1"
            },
            "avatar": {
              "href": "https://gravatar.com/avatar/md5/d2c457c9c97c9e4e2226317fe5685892/s=100&d=identicon"
            }
          }
        }
      }
    }
  ]
}

Reads a Govio Message

Read the message with the provided id.

GEThttp://localhost:10001/messages/{id}

Path parameters

id*MessageId (integer (int64))

GovIO Message Id.

Example: 1

Response

200400401403404429503default

Successful operation.

Body

application/hal+json

taxcode*string

The fiscal code of the receiver, all upper case.

Example: "PCRMJV76P12B782Z"

Pattern: [A-Z]{6}[0-9LMNPQRSTUV]{2}[ABCDEHLMPRST][0-9LMNPQRSTUV]{2}[A-Z][0-9LMNPQRSTUV]{3}[A-Z]

paymentGovioMessagePaymentItem (object)

Optional Field, marks the message as a payment message.

emailstring (email)

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

scheduled_expedition_date*string (date-time)

The date when this message has to be sent to the citizien.

due_datestring (date-time)

The expiration date for the message subject. When set, the IO app shows an expiration date for this message.

id*integer (int64)

GovIO Message Id.

Example: 1

status*GovioMessageStatus (enum)

acceptedthrottledscheduledrecipient_allowedprofile_not_existssender_not_alloweddeniedsentbad_requestforbiddenprocessedcreated

status_detailstring

Pattern: [\s\S]*

appio_message_idstring

Pattern: .*

creation_date*string (date-time)

expedition_datestring (date-time)

last_update_statusstring (date-time)

subject*string

Example: "Lorem ipsum"

markdown*string

Example: "# Lorem ipsum dolor sit amet\nUt enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."

sender_id*UserId (integer (int64))

User identifier.

Example: 1

service_instance_id*GovioServiceInstanceId (integer (int64))

Govio Service Instance Id.

Example: 1

_linksobject

_embeddedobject

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:10001/messages/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400401403404429503default

{
  "taxcode": "PCRMJV76P12B782Z",
  "payment": {
    "amount": 62.12,
    "notice_number": 300012548634478200,
    "invalid_after_due_date": false,
    "payee_taxcode": 10000000001
  },
  "email": "[e-mail]",
  "scheduled_expedition_date": "2024-12-26T17:08:33.625Z",
  "due_date": "2024-12-26T17:08:33.625Z",
  "id": 1,
  "status": "accepted",
  "status_detail": "text",
  "appio_message_id": "text",
  "creation_date": "2024-12-26T17:08:33.625Z",
  "expedition_date": "2024-12-26T17:08:33.625Z",
  "last_update_status": "2024-12-26T17:08:33.625Z",
  "subject": "Lorem ipsum",
  "markdown": "# Lorem ipsum dolor sit amet\nUt enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.",
  "sender_id": 1,
  "service_instance_id": 1,
  "_links": {
    "self": {
      "href": "https://govhub.it/govio/messages/1"
    },
    "service_instance": {
      "href": "https://govhub.it/govio/service-instances/1"
    },
    "sender": {
      "href": "https://govhub.it/govio/users/1"
    }
  },
  "_embedded": {
    "service-instance": {
      "service_id": 1,
      "organization_id": 1,
      "template_id": 1,
      "enabled": true,
      "io_service_id": "text",
      "id": 1,
      "_links": {
        "self": {
          "href": "https://govhub.it/govio/service-instances/1"
        },
        "service": {
          "href": "https://govhub.it/govio/services/1"
        },
        "organization": {
          "href": "https://govhub.it/govio/organizations/1"
        },
        "template": {
          "href": "https://govhub.it/govio/templates/1"
        }
      },
      "_embedded": {
        "service": {
          "id": 1,
          "service_name": "SUAP-Integrazione",
          "description": "Service for customer management.",
          "_links": {
            "self": {
              "href": "https://govhub.it/govregistry/services/1"
            },
            "logo": {
              "href": "https://govhub.it/govregistry/services/1/logo"
            },
            "logo_miniature": {
              "href": "https://govhub.it/govregistry/services/logo_miniature"
            }
          }
        },
        "organization": {
          "id": 1,
          "legal_name": "Giletti S.R.L.",
          "tax_code": "01234567890",
          "_links": {
            "self": {
              "href": "https://govhub.it/govregistry/organizations/1"
            },
            "logo": {
              "href": "https://govhub.it/govregistry/organizations/1/logo"
            },
            "logo_miniature": {
              "href": "https://govhub.it/govregistry/organizations/logo_miniature"
            }
          }
        },
        "template": {
          "name": "Spedizione Messaggio CIE",
          "description": "Segnala la scadenza della proprià C.I.E.",
          "subject": "Scadenza CIE n. ${cie.uppercase}",
          "message_body": "Salve, con la presente la informiamo che in data ${due_date} scadrà la Carta di Identità elettronica numero ${cie.uppercase}.",
          "has_payment": false,
          "has_due_date": false,
          "id": 1,
          "_links": {
            "self": {
              "href": "https://govhub.it/govio/templates/1"
            },
            "placeholders": {
              "href": "https://govhub.it/govio/templates/1/placeholders"
            }
          }
        }
      }
    },
    "sender": {
      "principal": "user-1",
      "full_name": "Antonio Giscardi",
      "email": "[e-mail]",
      "enabled": false,
      "id": 1,
      "_links": {
        "self": {
          "href": "https://govhub.it/govregistry/users/1"
        },
        "avatar": {
          "href": "https://gravatar.com/avatar/md5/d2c457c9c97c9e4e2226317fe5685892/s=100&d=identicon"
        }
      }
    }
  }
}