Integrazione dei calendari con un servizio di terze parti

La presente documentazione descrive come integrare sistemi esterni (ad esempio IVR o sistemi di gestione code) con le API dei calendari di OpenCity Italia

Le API – in formato ReST – messe a disposizione dalla piattaforma consentono le integrazioni necessarie con i sistemi esterni. Sono previste chiamate senza autenticazione per l’accesso a informazioni pubbliche e un meccanismo di autenticazione per la consultazione di dati non pubblici e per le operazioni di scrittura dove previste.

Verranno presi in esame 2 use-case specifici:

L'integrazione con un sistema Taglia code
L'integrazione di un IVR (Interactive Voice Response)

Le API dei calendari di Opencity Italia verranno interrogate al fine di:

Recuperare configurazioni dei servizi e delle agende
Ottenere disponibilità e slot prenotabili
Effettuare prenotazioni (opzionale)
Recuperare appuntamenti per una sede

La documentazione e i test delle API sono disponibili tramite interfaccia di tipo swagger.

Catalogo servizi e configurazione agende

Api Doc - Comune di Buglianowww.comune.bugliano.pi.it

Calendari, disponibilità, appuntamenti

Api Definitionservizi.comune.bugliano.pi.it

1. Integrazione IVR

1.1 Flusso generale

Il sistema IVR consente la prenotazione di appuntamenti tramite scelta vocale tra diverse tipologie di servizio, ad esempio:

Rilascio documenti
Certificati
Identità digitale
Autentiche

Per ogni servizio selezionato il flusso prevede due passaggi principali:

Recupero configurazione del servizio Uffici, sedi e calendari associati.
Recupero disponibilità Individuazione delle prime disponibilità nei calendari della sede scelta.

1.2 Recupero configurazione del servizio

Endpoint

GET /api/openapi/booking-config?id={service_id}

Descrizione

Questa chiamata restituisce:

Informazioni sul servizio
Uffici che lo erogano
Sedi
Calendari associati alla sede

Esempio di risposta (estratto)

{
  "items": [
    {
      "id": 2240,
      "link": "https://www.comune.bugliano.pi.it/api//servizi/47b0fb50deb217bfcceb5b6b4c32ba5b",
      "name": "Attivazione della TARI",
      "offices": [
        {
          "id": 856,
          "link": "https://www.comune.bugliano.pi.it/api//amministrazione/uffici/2c1aad31d1f20d6189ee5d1881a125e4",
          "name": "Ufficio Ambiente",
          "places": [
            {
              "id": 213,
              "link": "https://www.comune.bugliano.pi.it/api//vivere-il-comune/luoghi/4c246236f96f06a1a73a8ca05ebf71e7",
              "name": "Palazzo del municipio",
              "location": {
                "lat": 44.611185,
                "lng": 11.661106,
                "address": "Via Niccolò Macchiavelli 40062 Molinella"
              },
              "calendars": [...]
              ],
              ...              
            }
          ]
        }
      ],
      "categories": [
        "Tributi, finanze e contravvenzioni"
      ]
    }
  ],
  "self": "https://www.comune.bugliano.pi.it/api/openapi/booking-config?offset=0&limit=200&id=2240",
  "next": null,
  "prev": null,
  "count": 1
}

Il servizio è erogato dall’Ufficio Anagrafe in due sedi, è necessario individuare la sede desiderata per la quale si vogliono trovare le disponibilità. Ipotizziamo che ci interessino le disponibilità della sede di Via Niccolò Macchiavelli: dobbiamo entrare quindi nella struttura calendars, che è fatta come segue:

{
  ...
  "calendars": [
    {
      "id": "b95b5409-2b3d-44d1-b534-12bb99206b1b",
      "link": "https://servizi.comune.bugliano.pi.it/lang/api/calendars/b95b5409-2b3d-44d1-b534-12bb99206b1b",
      "availabilities_link": "https://servizi.comune.bugliano.pi.it/lang/api/availabilities?available=true&calendar_ids=b95b5409-2b3d-44d1-b534-12bb99206b1b"
    },
    {
      "id": "d35879fc-2047-47ed-8dd1-e317dc6c5cd0",
      "link": "https://servizi.comune.bugliano.pi.it/lang/api/calendars/d35879fc-2047-47ed-8dd1-e317dc6c5cd0",
      "availabilities_link": "https://servizi.comune.bugliano.pi.it/lang/api/availabilities?available=true&calendar_ids=d35879fc-2047-47ed-8dd1-e317dc6c5cd0"
    },
    {
      "id": "2e1e0f6c-3b51-4877-86bc-c9331f46b423",
      "link": "https://servizi.comune.bugliano.pi.it/lang/api/calendars/2e1e0f6c-3b51-4877-86bc-c9331f46b423",
      "availabilities_link": "https://servizi.comune.bugliano.pi.it/lang/api/availabilities?available=true&calendar_ids=2e1e0f6c-3b51-4877-86bc-c9331f46b423"
    }
  ],
  "merge_availabilities": true,
  "merged_availabilities_link": "https://servizi.comune.bugliano.pi.it/lang/api/availabilities?available=true&calendar_ids=b95b5409-2b3d-44d1-b534-12bb99206b1b%2Cd35879fc-2047-47ed-8dd1-e317dc6c5cd0%2C2e1e0f6c-3b51-4877-86bc-c9331f46b423",
  ...
}

1.3 Recupero disponibilità

Una volta selezionato il servizio è possibile fare la seconda chiamata che restituisce le disponibilità per i calendari collegati al servizio e alla sede selezionata

Questa API è pensata per restituire X slot ottimali nell’ambito di un intervallo dinamico di giorni, utile per sistemi IVR che devono proporre appuntamenti.

Endpoint

GET /lang/api/availabilities/windowed?window_size=Y&limit=X&reserve=true|false&calendar_ids=...

Parametri

Parametro

Validazione e default

Descrizione

window_size

intero, tra 1 e 30

default: 8

Numero di giorni per i quali si vogliono degli appuntamenti liberi

limit

intero, tra 1 e 10 default: 3

Numero di appuntamenti che si vogliono suggerire nell’IVR

reserve

booleano default: false

Riserva gli appuntamenti contestualmente alla chiamata, senza necessità di ulteriori chiamate per riservare i tre slot

calendar_ids

obbligatorio

Lista di UUID separati da virgola

Logica di selezione

Per scegliere gli appuntamenti liberi viene individuato un intervallo di giorni in cui è presente almeno uno slot libero. È possibile quindi che vengano elencati dei giorni non consecutivi e questo rende indeterminabile a priori l’intervallo coperto da questa chiamata. Nell’esempio che segue vengono ritornati per esempio 8 giorni tra il 1 settembre e il 16 settembre. Su servizi con calendari molto saturi anche se vengono richiesti 8 giorni potrebbero esserci un numero minore di giorni tra cui scegliere.

Nel caso di servizi con calendari molto liberi di fatto stiamo individuando il numero massimo di giorni tra il primo e l’ultimo appuntamento suggerito. Nel caso di servizi con calendari saturati in modo molto disomogeneo potrebbero esserci intervalli di tempo anche molto ampi tra il primo e l’ultimo appuntamento suggerito.

Indichiamo i tre slot proposti con A, B, C

1 disp

1/9/25

2/9/25

5/9/25

7/9/25

8/9/25

10/9/25

11/9/25

16/9/25

Matt

Pom

Nell’intervallo di giorni individuati restituisce la prima (A) e l’ultima disponibilità (C) di quei giorni: questo favorisce al massimo la differenza della fascia oraria negli slot suggeriti.

La seconda disponibilità è nel giorno di mezzo dell’intervallo di 8 giorni, la piattaforma cerca, se è possibile, di restituire un periodo del giorno diverso da quello del PRIMO meeting (A).

Se A è di mattina B è nel pomeriggio e viceversa.

Esempio

Calendario con disponibilità Lu, Ma, Me, Gio, Ve | 09:00 - 18:00

{
  "meta": {
    "count": 3,
    "parameter": {
      "calendar_ids": "83bb67e1-2137-4852-b6b1-d68809df43b1",
      "reserve": false,
      "window_size": "8",
      "limit": "3"
    }
  },
  "links": {
    "self": null,
    "prev": null,
    "next": null
  },
  "data": [
    {
      "date": "2025-07-31",
      "start_time": "10:30",
      "end_time": "11:00",
      "slots_available": 1,
      "availability": true,
      "opening_hour_id": "a90d71fe-0d56-4a1b-a1cf-11a567541041",
      "calendar_id": "83bb67e1-2137-4852-b6b1-d68809df43b1",
      "meeting_id": null, // null|Uuid meeting in bozza, valorizzato solo se reserve = true
      "meeting_code": "K001"// null|string 
    },
    {
      "date": "2025-08-05",
      "start_time": "12:00",
      "end_time": "12:30",
      "slots_available": 1,
      "availability": true,
      "opening_hour_id": "a90d71fe-0d56-4a1b-a1cf-11a567541041",
      "calendar_id": "83bb67e1-2137-4852-b6b1-d68809df43b1",
      "meeting_id": null, // null|Uuid meeting in bozza, valorizzato solo se reserve = true
      "meeting_code": "K002"// null|string
    },
    {
      "date": "2025-08-08",
      "start_time": "09:00",
      "end_time": "09:30",
      "slots_available": 1,
      "availability": true,
      "opening_hour_id": "a90d71fe-0d56-4a1b-a1cf-11a567541041",
      "calendar_id": "83bb67e1-2137-4852-b6b1-d68809df43b1",
      "meeting_id": null, // null|Uuid meeting in bozza, valorizzato solo se reserve = true
      "meeting_code": "K003" // null|string 
    }
  ]
}

1.5 Conferma degli appuntamenti

In caso di reserve = true il campo meetind_id sarà valorizzato con uuid del meeting in bozza, per poter confermare un meeting andrà fatta una PUT/PATCH sul meeting selezionato cambiando lo stato ed inserendo anche i dati generali del meeting (Nome del richiedente, email, numero di telefono ecc ecc)

Endpoint

PATCH /lang/api/meetings/{meeting_id}

Esempio

{
  "status": "1", // Stato confermato
  "name": "Mario Rossi",
  "email": "",
  "phone_number": "",
  "reason": "",
  "user_message": "",
  "motivation_outcome": "",
  "videoconference_link": "",
  "opening_hour": "",
  "locale": "it",
  "calendar_group_config_id": "5916", // Id del servizio 
  "calendar_group_office_id": "964",  // Id dell’ufficio
  "calendar_group_place_id": "780",   // Id della sede
  "location": ""
}

2. Integrazione Sistemi Tagliacode

I sistemi di gestione code possono sincronizzare ogni giorno gli appuntamenti previsti per una sede specifica.

Poiché i calendari accettano tipicamente prenotazioni solo fino al giorno successivo, è sufficiente un’unica sincronizzazione giornaliera.

2.1 Recupero agende relative a una sede

Endpoint

GET /api/openapi/booking-config?place_id={place_id}

Questa chiamata restituisce:

Tutti i servizi erogati nella sede
Tutti i calendari da cui provengono gli appuntamenti

I calendar ID ottenuti saranno utilizzati nella chiamata successiva.

Esempio di risposta

{
  "items": [
    {
      "id": 2240,
      "link": "https://www.comune.bugliano.pi.it/api//servizi/47b0fb50deb217bfcceb5b6b4c32ba5b",
      "name": "Attivazione della TARI",
      "offices": [
        {
          "id": 856,
          "link": "https://www.comune.bugliano.pi.it/api//amministrazione/uffici/2c1aad31d1f20d6189ee5d1881a125e4",
          "name": "Ufficio Ambiente",
          "places": [
            {
              "id": 213,
              "link": "https://www.comune.bugliano.pi.it/api//vivere-il-comune/luoghi/4c246236f96f06a1a73a8ca05ebf71e7",
              "name": "Palazzo del municipio",
              "location": {
                "lat": 44.611185,
                "lng": 11.661106,
                "address": "Via Niccol&ograve; Macchiavelli 40062 Molinella"
              },
              "calendars": [
                {
                  "id": "b95b5409-2b3d-44d1-b534-12bb99206b1b",
                  "link": "https://servizi.comune.bugliano.pi.it/lang/api/calendars/b95b5409-2b3d-44d1-b534-12bb99206b1b",
                  "availabilities_link": "https://servizi.comune.bugliano.pi.it/lang/api/availabilities?available=true&calendar_ids=b95b5409-2b3d-44d1-b534-12bb99206b1b"
                },
                {
                  "id": "d35879fc-2047-47ed-8dd1-e317dc6c5cd0",
                  "link": "https://servizi.comune.bugliano.pi.it/lang/api/calendars/d35879fc-2047-47ed-8dd1-e317dc6c5cd0",
                  "availabilities_link": "https://servizi.comune.bugliano.pi.it/lang/api/availabilities?available=true&calendar_ids=d35879fc-2047-47ed-8dd1-e317dc6c5cd0"
                },
                {
                  "id": "2e1e0f6c-3b51-4877-86bc-c9331f46b423",
                  "link": "https://servizi.comune.bugliano.pi.it/lang/api/calendars/2e1e0f6c-3b51-4877-86bc-c9331f46b423",
                  "availabilities_link": "https://servizi.comune.bugliano.pi.it/lang/api/availabilities?available=true&calendar_ids=2e1e0f6c-3b51-4877-86bc-c9331f46b423"
                }
              ],
              "merge_availabilities": true,
              "merged_availabilities_link": "https://servizi.comune.bugliano.pi.it/lang/api/availabilities?available=true&calendar_ids=b95b5409-2b3d-44d1-b534-12bb99206b1b%2Cd35879fc-2047-47ed-8dd1-e317dc6c5cd0%2C2e1e0f6c-3b51-4877-86bc-c9331f46b423"
            }
          ]
        }
      ],
      "categories": [
        "Tributi, finanze e contravvenzioni"
      ],
      "show_howto_in_motivation": true,
      "view_type": "select"
    }
  ]
}

2.2 Recupero appuntamenti del giorno

La chiamata è autenticata, si dovranno utilizzare le credenziali fornite per reperire un token JWT da allegare alla chiamata come indicato nella documentazione:

API ReST | Sviluppatori e partner tecnologici | Opencity Italiadocs.opencityitalia.it

Endpoint

GET /lang/api/meetings?calendars_ids=C1,C2,C3&from_time=...&to_time=...

Il risultato è una struttura dati di questo tipo (si omettono volutamente i campi non strettamente necessari): ogni elemento dell’array contiene un appuntamento per una persona con codice breve code.

Esempio di risposta (estratto)

[
  {
    "id": "5b00796e-ef10-4c98-b9f5-b0f7ffd7a17d",
    "user": "5300188a-fc05-4f49-8933-6d2d7d5c9ebc",
    "email": "string",
    "phone_number": "string",
    "fiscal_code": "string",
    "name": "string",
    "from_time": "2025-06-03T10:00:00+02:00",
    "to_time": "2025-06-03T10:20:00+02:00",
    "status": 1,
    "code": "K123",
    "calendar_group_config_id": "2282",
    "calendar_group_office_id": "964",
    "calendar_group_place_id": "4864"
  }
]

Nel json dell’appuntamento verranno riportate anche le indicazioni relative al servizio, alla sede ed all’ufficio.

id del servizio → calendar_group_config_id
id dell’ufficio → calendar_group_office_id
id della sede → calendar_group_place_id

PreviousEsempio con GovWay NextImportazioni massive

Last updated 1 month ago

Was this helpful?

Good night

hashtag1. Integrazione IVR

hashtag1.1 Flusso generale

hashtag1.2 Recupero configurazione del servizio

hashtagEndpoint

hashtagDescrizione

hashtagEsempio di risposta (estratto)

hashtag1.3 Recupero disponibilità

hashtagEndpoint

hashtagParametri

hashtagLogica di selezione

hashtagEsempio

hashtag1.5 Conferma degli appuntamenti

hashtagEndpoint

hashtagEsempio

hashtag2. Integrazione Sistemi Tagliacode

hashtag2.1 Recupero agende relative a una sede

hashtagEndpoint

hashtagEsempio di risposta

hashtag2.2 Recupero appuntamenti del giorno

hashtagEndpoint

hashtagEsempio di risposta (estratto)

1. Integrazione IVR

1.1 Flusso generale

1.2 Recupero configurazione del servizio

Endpoint

Descrizione

Esempio di risposta (estratto)

1.3 Recupero disponibilità

Endpoint

Parametri

Logica di selezione

Esempio

1.5 Conferma degli appuntamenti

Endpoint

Esempio

2. Integrazione Sistemi Tagliacode

2.1 Recupero agende relative a una sede

Endpoint

Esempio di risposta

2.2 Recupero appuntamenti del giorno

Endpoint

Esempio di risposta (estratto)