CONTRATTO ESECUTIVO PER L'AFFIDAMENTO DI "TOURISM DIGITAL HUB - TDH" MEDIANTE ORDINATIVO DI FORNITURA NELL'AMBITO DELL'ACCORDO QUADRO PER I SERVIZI APPLICATIVI PER LE PUBBLICHE AMMINISTRAZIONI STIPULATO DA CONSIP - ID 2212 – LOTTO 1
TDH022 - GUIDA ALLA RICHIESTA DI
UTILIZZO DI API DEL CATALOGO TDH
CONTRATTO ESECUTIVO PER L'AFFIDAMENTO DI "TOURISM DIGITAL HUB - TDH" MEDIANTE ORDINATIVO DI FORNITURA NELL'AMBITO DELL'ACCORDO QUADRO PER I SERVIZI APPLICATIVI PER LE PUBBLICHE AMMINISTRAZIONI STIPULATO DA CONSIP - ID 2212 – LOTTO 1
CIG DERIVATO 8924679E15 – CUP J51B21002940006
Versione: 2.0 Data: 14/04/2022
Versione | Data | Tipologia Modifica |
1.0 | 19/02/2022 | Prima Release |
2.0 | 14/04/2022 | Seconda Release |
INDICE GENERALE
4
2 CAPITOLO 2 – AMBITO DI APPLICAZIONE
6
2.1 Soggetti destinatari del documento 6
3 CAPITOLO 3 - RIFERIMENTI E SIGLE
7
3.1 Note di lettura del documento 7
3.2 Note di lettura del documento 7
4 CAPITOLO 4 – UTILIZZO DELLE API PUBBLICATE NEL CATALOGO TDH
9
4.1 Descrizione delle fasi del processo per l’utilizzo di una API 9
4.1.1 Messa a disposizione delle Linee Guida e Catalogo API 10
4.1.2 Selezione API di interesse 11
4.1.3 Sviluppo e configurazione delle chiamate API 12
4.1.4 Test di integrazione e collaudo chiamata API 12
4.1.5 Accettazione richiesta di utilizzo dell’API 12
4.1.6 Avvio chiamate (PUT) per trasferimento dati 13
4.1.7 Acquisizione dati da Aderente erogatore 13
5 BIBLIOGRAFIA E SITOGRAFIA DI RIFERIMENTO
14
CAPITOLO 1 – INTRODUZIONE
1.1 Contesto di riferimento
Il Ministero del Turismo, coadiuvato da ENIT - Agenzia nazionale per il turismo, ha il compito di coordinare l’intero ecosistema turistico italiano, promuovendo, in maniera unitaria, il rilancio del settore turistico mediante un’offerta informativa e di servizi coesa ed eterogenea, a fronte dei continui cambiamenti della domanda, nazionale ed internazionale.
Obiettivo dell’iniziativa TDH è il rilancio di Xxxxxx.xx, arricchito con nuovi contenuti prodotti internamente e in collaborazione con le Regioni e Province Autonome, ma anche attraverso integrazioni con partner in ambito Turistico. Nel dettaglio, per ogni argomento trattato, il portale presenterà contenuti dalla triplice valenza:
• Interesse: contenuti redazionali (articoli editoriali, informativi, guide, foto, video e altri contenuti multimediali) legati ad una determinata destinazione, attività o evento annesso;
• Destinazione: che si riferisce ad un POI o area geografica persistente nel medio/lungo termine, la cui attinenza sarà presentata tenendo conto di criteri di vicinanza geografica, somiglianza e affinità;
• Offerta: offerte di prodotti o servizi (ad es. ristoranti, alloggi, esperienze) collegate alla destinazione o argomento ricercato.
Il TDH, inoltre, si pone l’obiettivo di far incontrare profittevolmente la domanda turistica verso l’Italia con la relativa offerta italiana (erogata da diversi attori), mettendo in relazione tra loro gli interessi della persona (turista), le destinazioni e l’offerta prima, durante e dopo l’esperienza turistica, creando valore per tutti gli attori coinvolti.
All’interno del TDH è prevista la progettazione e implementazione di un Piattaforma di Integrazione
– Full Life Cycle API Manager che ha l’obiettivo di supportare l’interoperabilità tra applicazioni e servizi sia esterni che interni al TDH:
• servizi esterni: dati di seconda parte (es. Regioni), dati di terza parte (es Enti Privati e Pubblici integrativi rispetto al sistema nazionale), dati geografici;
• servizi interni: integrazione con applicazioni interne al TDH che coprono moduli specifici (es. CRM).
In un’ottica di raggiungimento dell’obiettivo di coinvolgimento dell’intero sistema turistico italiano, la Piattaforma di Integrazione e Api Manager garantisce il coordinamento informatico e informativo dei dati tra le Amministrazioni (centrali, regionali e locali), gli Enti e Società Terze con l’Ecosistema Digitale del TDH. Viene altresì identificato un protocollo di comunicazione standard tra il TDH e il mondo esterno, definito TDH022.
In tal senso, il TDH022 si pone come Standard Digitale a livello Nazionale, preposto allo scambio di dati e contenuti sia “aperti” (open data) che “chiusi” (private data) tra i partecipanti, svolgendo altresì ruolo di interfaccia di integrazione tra il TDH e gli Operatori di Settore che desiderano far parte dell’Ecosistema e che sono operativi sul territorio nazionale italiano.
In Figura 1 - Ecosistema TDH e connessione al mondo esterno mediante TDH022 viene schematizzata la strategia del Tourism Digital Hub e di interconnessione.
Figura 1 - Ecosistema TDH e connessione al mondo esterno mediante TDH022
Le modalità di interazione con l’Ecosistema TDH permettono sia di fruire di servizi digitali disponibili al suo interno sia di svilupparne/erogarne di nuovi (open o closed) mettendoli a disposizione dei soggetti aderenti all’Ecosistema. In tal senso, le interazioni prevedono che gli operatori (pubblici e privati) aderenti al TDH022 possano svolgere a seconda dei casi funzioni di:
• erogatore di servizi, nel caso in cui mettano a disposizione del TDH servizi e funzionalità;
• fruitore dei servizi, nel caso in cui utilizzino servizi digitali messi a disposizione da soggetti terzi all’interno dell’Ecosistema.
1.2 Obiettivo del documento
Il presente documento indica le modalità operative e le Linee Guida tecnologiche che è necessario seguire al fine di poter utilizzare una API disponibile nel catalogo dell’Ecosistema TDH. La richiesta d’uso delle API all’interno dell’Ecosistema TDH avviene in modo controllato, in accordo a un processo di accettazione ben preciso che prevede l’interazione tra l’Aderente (in qualità di erogatore) e l’Ecosistema stesso. Tale processo è dettagliato nei prossimi capitoli.
In questa versione, vengono dettagliate le modalità di richiesta d’uso API sia in modalità “PUT” sia in modalità “GET”; nel primo caso (“PUT”), l’Aderente, in qualità di erogatore, richiede la possibilità di trasmettere i dati in suo possesso per trasferirli all’interno dell’Ecosistema TDH, tramite il protocollo TDH022; nel secondo caso (“GET”), l’Aderente, in qualità di fruitore, richiede la possibilità di ricevere i dati dell’Ecosistema TDH.
CAPITOLO 2 – AMBITO DI APPLICAZIONE
Il presente Documento è redatto quale documento relativo alle modalità operative e alle Linee Guida tecnologiche che è necessario seguire al fine di poter utilizzare una API all’interno del TDH.
2.1 Soggetti destinatari del documento
Il Documento è destinato a tutti gli Aderenti che in qualità di erogatori o fruitori utilizzano servizi e funzionalità all’interno del Tourism Digital Hub (TDH), in virtù dell’accordo di adesione e interoperabilità stipulato con il MiTur.
Di seguito, a livello esemplificativo e non esaustivo, si riporta un elenco dei Soggetti Pubblici e Privati destinatari del Documento Operativo, sia presenti a titolo di erogatori che di fruitori dei servizi e delle funzionalità all’interno del Tourism Digital Hub (TDH).
Soggetti Pubblici:
• Pubblica Amministrazione Centrale (es. Ministero del Turismo),
• Pubblica Amministrazione Locale (es. Regioni, Province…),
• Enti Nazionali e Locali (es. ENIT),
• Enti No Profit,
• Imprese pubbliche collegate agli ambiti turistici (es. impianti di risalita…).
Soggetti Privati:
• Imprese ricettive, di ristorazione, ecc…,
• Tour Operator/Agenzie di viaggio,
• Sindacati,
• Imprese private collegate agli ambiti turistici (es. impianti di risalita…).
CAPITOLO 3 - RIFERIMENTI E SIGLE
3.1 Note di lettura del documento
Conformemente alle norme ISO/IEC Directives, Part 3 per la stesura dei documenti tecnici il presente Documento Operativo utilizzerà le parole chiave «DEVE», «DEVONO», «NON DEVE», «NON DEVONO», «DOVREBBE», «NON DOVREBBE», «PUÒ» e «OPZIONALE», la cui interpretazione è descritta di seguito:
• DEVE o DEVONO, indicano un requisito obbligatorio per rispettare la Linea di indirizzo;
• NON DEVE o NON DEVONO, indicano un assoluto divieto delle specifiche;
• DOVREBBE o NON DOVREBBE, indicano che le implicazioni devono essere comprese e attentamente pesate prima di scegliere approcci alternativi;
• PUÓ o POSSONO o l'aggettivo OPZIONALE, indica che il lettore può scegliere di applicare o meno senza alcun tipo di implicazione o restrizione la specifica.
3.2 Note di lettura del documento
Per una più agevole lettura si riporta un glossario dei termini e delle definizioni contenuti nel presente documento.
[Aderente] | Soggetto che ha aderito alla Infrastruttura interoperabilità con TDH attraverso il processo di accreditamento |
[AgID] | Agenzia per l’Italia Digitale |
[API] | Un insieme di procedure, funzionalità, operazioni disponibili al programmatore e di solito raggruppate per formare un insieme di strumenti specifici per l’espletamento di un determinato compito |
[CAD] | Decreto Legislativo 7 marzo 2005, n. 82 - «Codice dell’Amministrazione Digitale» (noto anche come “CAD”), aggiornato con modifiche dal D.L. 16 luglio 2020 n.76 e convertito in legge con la L. 11 settembre 2020 n.120 |
[Catalogo TDH] | Componente unica e centralizzata, che assicura alle parti coinvolte nel rapporto di erogazione e fruizione la conoscenza delle API disponibili, e per esse, i livelli di servizio dichiarati |
[E-service] | I servizi digitali realizzati ai sensi del CAD art. 1, comma 1, lettera n-quater) da un erogatore per assicurare l’accesso ai propri dati e/o l’integrazione dei propri processi attraverso l’interazione dei suoi sistemi informatici con quelli dei fruitori, trovano attuazione nell’implementazione di API |
[Erogatore] | Uno dei soggetti di cui all’articolo 2, comma 2 del CAD che rende disponibile e-service ad altre organizzazioni, per la fruizione di dati in suo possesso o l’integrazione dei processi da esso realizzati |
[Fruitore] | Organizzazione che utilizza gli e-service messi a disposizione da uno dei soggetti di cui all’articolo 2, comma 2 del CAD |
[TDH] | Tourism Digital Hub |
[TDH022] | TDH022 - Interfaccia di interoperabilità del Tourism Digital Hub |
[TMB] | Technical Management Board: struttura interna al MiTur che valida, certifica e monitora le API e i contenuti all’avvio e a regime |
CAPITOLO 4 – UTILIZZO DELLE API PUBBLICATE NEL CATALOGO TDH
Nella figura seguente viene riportato il processo per richiedere l’utilizzo delle API pubblicate all’interno del catalogo TDH; a seguire viene riportata una descrizione di tutti i passi che caratterizzano tale processo all’interno dell’Ecosistema.
Figura 1 Processo per la richiesta d’uso di un’API del catalogo TDH (da sinistra a destra il flusso delle attività che ogni soggetto svolge e la corrispondente sincronizzazione)
Si precisa che le interazioni tra l’Aderente e l’Ecosistema sono supportate da un ambiente di relazione1 disponibile online sul TDH attraverso il quale gestire le richieste d’uso delle API ed i necessari scambi informativi (incluse eventuali notifiche).
4.1 Descrizione delle fasi del processo per l’utilizzo di una API
Nei paragrafi seguenti vengono dettagliate le fasi di processo per il corretto utilizzo delle API da parte degli Aderenti, in particolare per quelli "erogatori" che intendono trasmettere le informazioni da esporre all'interno dell'Ecosistema TDH.
Per gli Aderenti "fruitori", l'accesso alle risorse dell'Ecosistema è previsto nel rispetto degli impegni
assunti con l’accordo di adesione e interoperabilità con il TDH.
1 L’ambiente di relazione sarà un processo telematico che sarà esplorato e definito in una fase successiva.
4.1.1 Messa a disposizione delle Linee Guida e Catalogo API
L’Ecosistema TDH mette a disposizione dei soggetti Aderenti gli strumenti necessari per rendere i propri sistemi informatici interoperabili, al fine di permettere il coordinamento informativo e informatico dei dati tra le Amministrazioni (centrali, regionali e locali), gli Enti e Società Terze con l’Ecosistema Digitale TDH, tramite il protocollo TDH022.
Le Linee Guida si pongono in linea con le indicazioni emanate da AgID, contribuendo alla definizione di un modello di interoperabilità tra gli operatori turistici, focalizzandosi sui processi, le tecnologie e le loro modalità di utilizzo, al fine di assicurare lo scambio di dati e contenuti con il TDH per mezzo dello standard TDH022. Sono inoltre definiti i contesti di interazione all’interno dell’Ecosistema.
Le modalità di interazione con l’Ecosistema TDH descritte all’interno del documento “TDH022_Linee_guida_interoperabilità” (e i suoi allegati) permetteranno sia di fruire di servizi digitali (open) disponibili al suo interno sia di inviare richieste per lo sviluppo/erogazione di nuovi (open o closed) mettendoli a disposizione dei soggetti aderenti all’Ecosistema. In tal senso, le interazioni prevedono che gli operatori (pubblici e privati) aderenti al TDH022 possano svolgere la funzione di erogatore di servizi e fruitore dei servizi, come precedentemente descritto. In tal senso è possibile da parte di un operatore turistico svolgere alternativamente o entrambe le funzioni.
Le Linee Guida individuano il Catalogo delle API quale componente, unica e centralizzata, che assicura alle parti coinvolte nel rapporto di erogazione e fruizione la consapevolezza sulle API disponibili, e per esse, i livelli di servizio dichiarati.
Il Catalogo contiene tutte le API offerte e potenzialmente disponibili per essere utilizzate all'interno dell’Ecosistema TDH, con l’obiettivo di contribuire alla crescita dell’Ecosistema stesso e quindi di arricchire l’offerta turistica italiana. A tale scopo l’Ecosistema TDH mette a disposizione dei soggetti aderenti gli standard tecnologici e regole comuni da adottare al fine di consentire alle API di poter costantemente “parlare” e interagire con l'Ecosistema stesso.
Nella sua prima versione, il Catalogo API messo a disposizione dal TDH consiste in una serie2 di API, ognuna delle quali consente sia la trasmissione (PUT) sia la ricezione di dati dall’Ecosistema (GET). In particolare:
• API N.1: Destination
2 Il numero delle API disponibili a Catalogo è incrementale.
• API N.2: Interest
• API N.3: POI (Point of Interest)
• API N.4: ROOM
• API N.5: HOTEL OFFER
Il Catalogo sarà costantemente aggiornato e reso fruibile in base alla roadmap di evoluzione dell’Ecosistema TDH coordinata dal MiTur e anche rispetto alle eventuali richieste di implementazione di API specifiche suggerite dagli Aderenti.
4.1.2 Selezione API di interesse
L’Aderente identifica l’API di interesse che ritiene opportuno utilizzare in base al tipo di operazione che intende svolgere: nel caso di Aderente “erogatore”, per trasmettere le informazioni da esporre all’interno dell'Ecosistema TDH, l’utente seleziona l’API da utilizzare in modalità “PUT”; nel caso di Aderente “fruitore”, l’utente seleziona l’API da utilizzare in modalità “GET”. Tale valutazione di opportunità viene eseguita dall’Aderente in accordo alle proprie strategie aziendali o al proprio ruolo istituzionale e in linea con le finalità e gli obiettivi strategici del TDH previsti dall’accordo di adesione e interoperabilità stipulato con il MiTur.
In particolare, per gli Aderenti erogatori le API di principale interesse saranno riferite alla condivisione e/o alla trasmissione di contenuti digitali (articoli, immagini, video, ecc...) e di informazioni riferiti a POI (Punti di Interesse), Destinazioni, Interessi ed Offerte.
Ognuna delle API disponibile online all’interno del Catalogo TDH è provvista della relativa documentazione tecnica a corredo che contiene istruzioni su come usare per integrarsi efficacemente con l’API, in cui sono contenuti dettagli su standard, funzioni, classi, tipi di ritorno, argomenti e altro, supportato da tutorial ed esempi. L’Aderente è invitato a seguire le istruzioni relative all’API selezionata per poter procedere con le opportune configurazioni necessarie per avviare la chiamata all’API e il processo di trasmissione dei dati da o verso l’Ecosistema TDH.
I dati che l’Aderente erogatore può decidere di mettere a disposizione all’interno dell’Ecosistema attraverso l’API riguardano in generale informazioni o funzionalità specifiche dell’Aderente stesso, direttamente o indirettamente correlate al settore del Turismo, e comunque in linea con le finalità e gli obiettivi del TDH. Analogamente, l’Aderente fruitore può recuperare le informazioni o le funzionalità disponibili all’interno dell'Ecosistema TDH, in base alla ricerca effettuata.
4.1.3 Sviluppo e configurazione delle chiamate API
Le chiamate alle API che permettono di interoperare con l’Ecosistema TDH saranno configurate dall’Aderente erogatore secondo gli standard tecnologici e le Linee Guida riportate nel documento "TDH022_Linee_Guida_Interoperabilità". Non sono ammesse eccezioni.
Nella documentazione tecnica a corredo delle API sarà disponibile anche un documento denominato “Piano di validazione e collaudo” con i casi d’uso da eseguire per il successivo collaudo della soluzione, a supporto della fase di implementazione e configurazione dell’Aderente.
In particolare, per ogni API è definito il relativo dataset e l’alberatura ontologica come specifiche da rispettare per la configurazione delle chiamate e la restituzione dei dati, così come dettagliato nella documentazione tecnica a corredo di ogni specifica API.
4.1.4 Test di integrazione e collaudo chiamata API
In questa fase di verifica, il Technical Management Board, una volta ricevuta da parte dell’Aderente erogatore la richiesta di utilizzo di una API, provvede ad eseguire in concerto con l’Aderente le opportune verifiche di correttezza e coerenza delle chiamate e dei dati trasmessi attraverso l’API verso l’Ecosistema TDH, come da piano di collaudo.
In particolare, il TMB effettua gli opportuni test per verificare la correttezza delle chiamate all’API e
la consistenza dei dati trasmessi.
4.1.5 Accettazione richiesta di utilizzo dell’API
Il processo di verifica delle API può concludersi positivamente o meno a seconda delle non conformità rilevate dal Technical Management Board alla conclusione dei test di integrazione. In caso di esito positivo del processo di verifica, il Technical Management Board dell’Ecosistema rilascia all’Aderente erogatore un resoconto con il dettaglio delle verifiche svolte.
Qualora durante la sessione di test di integrazione fossero rilevate delle non conformità che non consentono il corretto utilizzo dell’API, il TMB svolgerà un ruolo di supporto al fine di consentire agli Aderenti erogatori di poter configurare correttamente la chiamata all’API e di portare così a termine con successo la richiesta di utilizzo della stessa.
4.1.6 Avvio chiamate (PUT) per trasferimento dati
Una volta ottenuto il consenso all’utilizzo dell’API da parte del TMB, l’Aderente erogatore è autorizzato ad avviare le chiamate per trasmettere i propri dati e informazioni all’interno dell’Ecosistema TDH, nel rispetto degli impegni assunti con l’accordo di adesione e interoperabilità con il TDH.
4.1.7 Acquisizione dati da Aderente erogatore
L’Ecosistema TDH viene alimentato con i dati e le informazioni messe a disposizione dall’Aderente erogatore, contribuendo all’arricchimento dei contenuti da condividere con tutti i soggetti fruitori dell’Ecosistema stesso, assolvendo così il compito di valorizzare, integrare e favorire la propria offerta per tutti gli attori coinvolti.
Si precisa che tutte le indicazioni e le Linee Guida specifiche per poter portare a termine con successo la procedura di richiesta di utilizzo delle API sono rese disponibili online agli Aderenti all’interno dell’ambiente di relazione dell’Ecosistema TDH.
BIBLIOGRAFIA E SITOGRAFIA DI RIFERIMENTO
Linee Guida sull’interoperabilità tecnica delle Pubbliche Amministrazioni
Autore: AgID – Prima pubblicazione: 27/04/2021 Riferimento online:
Linee Guida per la pubblicazione di API E015
Autore: E015 Digital Ecosystem - Prima pubblicazione: 06/06/2018 Riferimento online: xxxxx://xxx.x000.xxxxxxx.xxxxxxxxx.xx/xxxx/xxxxxxxxxx
Documento Operativo – Pattern di Interazione Autore: AgID – Prima pubblicazione: 27/04/2021 Riferimento online:
xxxxx://xxx.xxxx.xxx.xx/xxxxx/xxxxxxx/xxxxx/xxxxxxxxxx_xxxxx/00_xxxxxxx_xxxxxxxxxxx_0.xxx
Documento Operativo – Pattern di Sicurezza Autore: AgID – Prima pubblicazione: 27/04/2021 Riferimento online:
xxxxx://xxx.xxxx.xxx.xx/xxxxx/xxxxxxx/xxxxx/xxxxxxxxxx_xxxxx/00_xxxxxxx_xxxxxxxxx.xxx
Documento Operativo – Profili di interoperabilità Autore: AgID – Prima pubblicazione: 04/09/2020 Riferimento online:
xxxxx://xxx.xxxx.xxx.xx/xxxxx/xxxxxxx/xxxxx/xxxxxxxxxx_xxxxx/00_xxxxxxx_xx_xxxxxxxxxxxxxxxx.xxx
Documento Operativo – Raccomandazioni di implementazione
Autore: AgID – Prima pubblicazione: 04/09/2020 Riferimento online:
Immagine di copertina – Credits
Sito Web: Freepik – Autore: Flaticon
Riferimento online: xxxxx://xxx.xxxxxxxx.xxx/xxxx-xxxx/xxxx_0000000