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.

post

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.

Authorizations

header-principal

GovHub-Consumer-PrincipalstringRequired

Query parameters

service_instanceinteger · int64Required

Govio Service Instance Id.

Example: 1

idempotency_keystring · uuidRequired

Body

application/json

taxcodestring · min: 16 · max: 16Required

The fiscal code of the receiver, all upper case.

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

emailstring · email · max: 255Optional

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

scheduled_expedition_datestring · date-timeRequired

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

due_datestring · date-timeOptional

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

Responses

201

Successful operation.

application/hal+json

400

Bad Request.

application/problem+json

401

Required credentials missing.

application/problem+json

403

Agent not authorized for the operation.

application/problem+json

429

Too many requests.

application/problem+json

503

Service Unavailable.

application/problem+json

default

Unexpected error.

application/problem+json

post

/messages

HTTPcURLJavaScriptPython

POST /messages?service_instance=1&idempotency_key=123e4567-e89b-12d3-a456-426614174000 HTTP/1.1
Host: localhost:10001
GovHub-Consumer-Principal: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 321

{
  "taxcode": "PCRMJV76P12B782Z",
  "payment": {
    "amount": 62.12,
    "notice_number": 300012548634478200,
    "invalid_after_due_date": true,
    "payee_taxcode": 10000000001
  },
  "email": "[e-mail]",
  "scheduled_expedition_date": "2026-03-21T13:05:51.105Z",
  "due_date": "2026-03-21T13:05:51.105Z",
  "placeholders": [
    {
      "name": "cie",
      "value": "CA000000AA"
    }
  ]
}

{
  "taxcode": "PCRMJV76P12B782Z",
  "payment": {
    "amount": 62.12,
    "notice_number": 300012548634478200,
    "invalid_after_due_date": true,
    "payee_taxcode": 10000000001
  },
  "email": "[e-mail]",
  "scheduled_expedition_date": "2026-03-21T13:05:51.105Z",
  "due_date": "2026-03-21T13:05:51.105Z",
  "id": 1,
  "status": "accepted",
  "status_detail": "text",
  "appio_message_id": "text",
  "creation_date": "2026-03-21T13:05:51.105Z",
  "expedition_date": "2026-03-21T13:05:51.105Z",
  "last_update_status": "2026-03-21T13:05:51.105Z",
  "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": true,
          "has_due_date": true,
          "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": true,
      "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

get

Read and Filter the Govio Messages.

Authorizations

header-principal

GovHub-Consumer-PrincipalstringRequired

Query parameters

scheduled_expedition_date_fromstring · date-timeOptional

scheduled_expedition_date_tostring · date-timeOptional

expedition_date_fromstring · date-timeOptional

expedition_date_tostring · date-timeOptional

tax_codestring · min: 1 · max: 99999999OptionalPattern: [\s\S]*

service_idinteger · int64 · max: 9223372036854776000Optional

Service identifier.

Example: 1

organization_idinteger · int64 · max: 9223372036854776000Optional

Organization identifier.

Example: 1

service_qstring · max: 255OptionalExample: user_1Pattern: ^[^\u0000]*$

organization_qstring · max: 255OptionalExample: user_1Pattern: ^[^\u0000]*$

statusstring · enumOptional

Filters by message state.

Possible values:

sortstring · enumRequired

Sorting field.

Default: idPossible values:

sort_directionstring · enumRequired

Direction Sorting field.

Default: descPossible values:

limitinteger · int32 · min: 1 · max: 100Optional

Max number of provided items.

offsetinteger · int64 · max: 9223372036854776000Optional

offset (zero-based) of indexed results.

Default: 0

Responses

200

Successful operation.

application/hal+json

and

400

Bad Request.

application/problem+json

401

Required credentials missing.

application/problem+json

403

Agent not authorized for the operation.

application/problem+json

429

Too many requests.

application/problem+json

503

Service Unavailable.

application/problem+json

default

Unexpected error.

application/problem+json

get

/messages

HTTPcURLJavaScriptPython

GET /messages?sort=id&sort_direction=desc HTTP/1.1
Host: localhost:10001
GovHub-Consumer-Principal: YOUR_API_KEY
Accept: */*

{
  "page": {
    "offset": 20,
    "limit": 25,
    "total": 32
  },
  "items": [
    {
      "taxcode": "PCRMJV76P12B782Z",
      "payment": {
        "amount": 62.12,
        "notice_number": 300012548634478200,
        "invalid_after_due_date": true,
        "payee_taxcode": 10000000001
      },
      "email": "[e-mail]",
      "scheduled_expedition_date": "2026-03-21T13:05:51.105Z",
      "due_date": "2026-03-21T13:05:51.105Z",
      "id": 1,
      "status": "accepted",
      "status_detail": "text",
      "appio_message_id": "text",
      "creation_date": "2026-03-21T13:05:51.105Z",
      "expedition_date": "2026-03-21T13:05:51.105Z",
      "last_update_status": "2026-03-21T13:05:51.105Z",
      "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": true,
              "has_due_date": true,
              "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": true,
          "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

get

Read the message with the provided id.

Authorizations

header-principal

GovHub-Consumer-PrincipalstringRequired

Path parameters

idinteger · int64Required

GovIO Message Id.

Example: 1

Responses

200

Successful operation.

application/hal+json

taxcodestring · min: 16 · max: 16Required

The fiscal code of the receiver, all upper case.

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

emailstring · email · max: 255Optional

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

scheduled_expedition_datestring · date-timeRequired

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

due_datestring · date-timeOptional

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

idinteger · int64Required

GovIO Message Id.

Example: 1

statusstring · enumRequiredPossible values:

status_detailstring · max: 2000000OptionalPattern: [\s\S]*

appio_message_idstring · max: 1024OptionalPattern: .*

creation_datestring · date-timeRequired

expedition_datestring · date-timeOptional

last_update_statusstring · date-timeOptional

subjectstring · min: 10 · max: 120RequiredExample: Lorem ipsum

markdownstring · min: 80 · max: 10000RequiredExample: # Lorem ipsum dolor sit amet Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

sender_idinteger · int64 · max: 9223372036854776000Required

User identifier.

Example: 1

service_instance_idinteger · int64Required

Govio Service Instance Id.

Example: 1

400

Bad Request.

application/problem+json

401

Required credentials missing.

application/problem+json

403

Agent not authorized for the operation.

application/problem+json

404

Not Found.

application/problem+json

429

Too many requests.

application/problem+json

503

Service Unavailable.

application/problem+json

default

Unexpected error.

application/problem+json

get

/messages/{id}

HTTPcURLJavaScriptPython

GET /messages/{id} HTTP/1.1
Host: localhost:10001
GovHub-Consumer-Principal: YOUR_API_KEY
Accept: */*

{
  "taxcode": "PCRMJV76P12B782Z",
  "payment": {
    "amount": 62.12,
    "notice_number": 300012548634478200,
    "invalid_after_due_date": true,
    "payee_taxcode": 10000000001
  },
  "email": "[e-mail]",
  "scheduled_expedition_date": "2026-03-21T13:05:51.105Z",
  "due_date": "2026-03-21T13:05:51.105Z",
  "id": 1,
  "status": "accepted",
  "status_detail": "text",
  "appio_message_id": "text",
  "creation_date": "2026-03-21T13:05:51.105Z",
  "expedition_date": "2026-03-21T13:05:51.105Z",
  "last_update_status": "2026-03-21T13:05:51.105Z",
  "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": true,
          "has_due_date": true,
          "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": true,
      "id": 1,
      "_links": {
        "self": {
          "href": "https://govhub.it/govregistry/users/1"
        },
        "avatar": {
          "href": "https://gravatar.com/avatar/md5/d2c457c9c97c9e4e2226317fe5685892/s=100&d=identicon"
        }
      }
    }
  }
}