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
Calendari, disponibilità, appuntamenti
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
Descrizione
Questa chiamata restituisce:
Informazioni sul servizio
Uffici che lo erogano
Sedi
Calendari associati alla sede
Esempio di risposta (estratto)
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:
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
Parametri
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
2
3
4
5
6
7
8
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
A
C
Pom
B
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
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
Esempio
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
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
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:
Endpoint
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)
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
Last updated
Was this helpful?