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
Manuale operativo 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
Data: 06/07/2022
Versione: 1.0
TABELLA DELLE VERSIONI | |||
Data | Versione | Descrizione | Par. modificati |
06/07/2022 | 1.0 | Prima redazione del documento | Tutti |
Indice
4 FASE 1: Processo di adesione al TDH 5
4.1 Pubblicazione Comunicazione 6
4.2 Inoltro Comunicazione di interesse 6
4.5 Registrazione e Profilazione 6
4.6 Accesso e navigazione nella area personale 7
4.7 Supporto e affiancamento 7
5 FASE 2: Processo per l’utilizzo delle API pubblicate Errore. Il segnalibro non è definito.
5.1 Messa a disposizione delle Linee Guida e Catalogo API 8
5.2 Selezione API di interesse 8
5.3 Sviluppo e configurazione delle chiamate API 8
5.4 Test di integrazione e collaudo chiamata API 9
5.5 Accettazione richiesta di utilizzo dell’API 9
5.6 Avvio chiamate per trasferimento dati 9
5.7 Acquisizione dati da Aderente erogatore 9
Indice tabelle
Tabella 1 – Acronimi e definizioni 5
Indice figure
Figura 1 - Processo di Adesione per l'utilizzo del Portale TDH 5
attività che ogni soggetto svolge e la corrispondente sincronizzazione) 7
1 Scopo del documento
Il presente documento è redatto quale documento operativo per gli operatori aderenti al TDH, in coerenza con l’assetto organizzativo e tecnologico dell’ecosistema, e vuole essere una guida a supporto post sottoscrizione del contratto di adesione. In dettaglio il documento supporta il referente dell’aderente nelle fasi tecniche/operative (analisi tecniche, implementazione/configurazione chiamate API, test di integrazione, etc.) e di supporto con l’ausilio del TMB (Technical Management Board) per traguardare l’attivazione dell’interoperabilità mediante le API messe a disposizione dal TDH.
2 Acronimi e definizioni
Acronimo | Descrizione |
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 |
MiTur | Ministero del Turismo |
Partner | Xxxxxxxx interessato ad aderire al TDH |
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, e supporta gli aderenti in tutte le fasi pre go-live. |
Tabella 1 – Acronimi e definizioni
3 Introduzione
Il TDH è una piattaforma di contenuti e servizi per far incontrare profittevolmente la domanda turistica verso l’Italia con la relativa offerta italiana (erogata sia da attori nazionali che internazionali), mettendo in relazione tra loro gli interessi della persona (turista), le destinazioni e l’offerta prima, durante e dopo l’esperienza turistica, creando valore aggiunto per tutti gli attori coinvolti.
Nei capitoli successivi vengono illustrati tutti gli steps del processo E2E che permettono a un soggetto aderente all’ecosistema TDH di traguardare l’attivazione dei servizi per l’interoperabilità a mezzo API, con particolare focus alle fasi successive alla sottoscrizione dell’accordo. In dettaglio le fasi del processo E2E possono essere suddivise in due:
1. Fase 1 (Amministrativa di adesione): dalla formulazione di una richiesta di adesione all’ecosistema TDH alla sottoscrizione del contratto di adesione,
2. Fase 2 (Tecnico/Operativa): dalla registrazione all’ecosistema TDH alla fruizione dei servizi messi a
disposizione dall’Ecosistema stesso, tramite l’utilizzo delle API.
Queste due fasi avvengono con modalità e tempi distinti, così come descritto rispettivamente nel Capitolo 4 e nel Capitolo Errore. L'origine riferimento non è stata trovata.. Il particolare il capitolo 4 sarà trattato ad alto livello in quanto in funzione della tipologia di aderente (PP.AA o soggetto/operatore economico privato) e di accordo di adesione (realizzazione di campagne di co-branding, scambio di contenuti editoriali, settore della ristorazione, etc) il processo presenta delle specificità. Il capitolo 5 invece è standard e dettaglia le modalità operative/organizzative con cui il referente dell’aderente si interfaccia con la struttura interna del MiTur (TMB) per indirizzare tutte le attività tecniche di implementazione/configurazione/test per integrazione con l’ecosistema TDH.
4 FASE 1: Processo di adesione al TDH
Nella figura seguente viene riportato, a titolo di esempio, il processo di adesione da parte di un soggetto pubblico interessato all’Ecosistema TDH1; a seguire viene riportata una sintesi degli steps principali che caratterizzano tale processo all’interno dell’Ecosistema.
1 Il processo di adesione per i soggetti ed operatori economici privati presenta delle leggere differenze nelle fasi precedenti alla sottoscrizione dell’accordo anche in funzione della tipologia di adesione (contenuti redazionali, co- branding, strutture ricettive, etc). Dalla fase di registrazione e profilazione il processo è il medesimo sia per le PP.AA che per i soggetti ed operatori economici privati.
Figura 1 - Processo di Adesione per l'utilizzo del Portale TDH
4.1 Pubblicazione Comunicazione
Il soggetto interessato a partecipare all’iniziativa Tourism Digital Hub potrà esprimere la propria volontà di aderire rispondendo alla specifica manifestazione di interesse pubblicata dal MiTur ed ENIT attraverso gli opportuni canali e strumenti. Alla prima redazione del presente manuale sono disponibili sul sito xxxxx://xxx.xxxx.xx i seguenti avvisi:
- Avviso pubblico per raccogliere le adesioni, da parte di soggetti ed operatori economici privati, interessati alla stipula di accordi di collaborazione finalizzati all’ideazione e allo svolgimento di iniziative di co-branding volte a promuovere, attraverso il portale xxxxx://xxx.xxxxxx.xx i marchi italiani e le eccellenze del Made in Italy, garantendone la visibilità su scala internazionale.
4.2 Inoltro Comunicazione di interesse
Il soggetto interessato deve presentare un’istanza di adesione, generata in formato PDF su cui apporre la
firma digitale, trasmettendola via PEC al seguente indirizzo: xxxxxxxxxxxx@xxxx.xxxx.xx.
4.3 Ricezione
Tutte le istanze di adesione presentate saranno oggetto di verifica da parte delle competenti strutture del MiTur - l’ENIT preposte alla definizione delle strategie redazionali per il sito internet xxxxx://xxx.xxxxxx.xx e/o per il portale TDH.
ENIT raccoglie le richieste. In questa fase, il Technical Management Board (TMB) contatta il soggetto interessato per supportarlo nella verifica di sussistenza dei requisiti specifici per l’adesione.
4.4 Sottoscrizione accordo
Una volta superata la fase di istruttoria con esito positivo e di verifica di sussistenza dei requisiti specifici per l’adesione, il Partner riceve a mezzo PEC l’accordo di adesione che deve provvedere a compilare in tutte le sue parti, a sottoscrivere e a inviare a ENIT.
5 FASE 2: Processo per l’utilizzo delle API pubblicate
5.1 Registrazione e Profilazione
Alla ricezione del contratto firmato da parte del Partner, il MiTur/ENIT invia una email al Partner con l’invito ad accedere al TDH, con le istruzioni per procedere con la registrazione e la profilazione.
5.2 Accesso e navigazione nella area personale
L’utente del Partner che ha provveduto alla registrazione e alla profilazione sul portale TDH, ha facoltà di accedere all’Area personale del portale Web, in cui può procedere con l’invio di inviti alla registrazione destinati ad altri contatti riconducibili all’organizzazione di cui fa parte.
5.3 Supporto e affiancamento
Il referente operativo del Partner avvia le attività di sviluppo ed implementazione dei servizi con il TMB, in accordo con le fasi indicate nei paragrafi successivi.
Nell’Area personale del portale Web, l’utente collegato al TDH può richiedere di ricevere assistenza e/o consultare la documentazione tecnica (Linee Guida, Manuali API, etc). Ad esempio, da questa sezione può effettuare richieste di recupero password, oppure può richiedere un’assistenza tecnica specifica, oppure può avanzare richieste di chiarimenti afferenti alle pratiche amministrative, e così via.
Attraverso l’adesione al TDH, ciascun Aderente potrà fruire delle API disponibili, e presenti a Catalogo, finalizzate all’esposizione della propria offerta e/o alla ricezione di dati presenti nell’Ecosistema, in base alle proprie esigenze.
L’Ecosistema TDH mette a disposizione dei referenti operativi del partner aderente 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.
Nella figura seguente viene riportato il processo per richiedere l’utilizzo delle API pubblicate all’interno del TDH; a seguire viene riportata una descrizione di tutti i passi che caratterizzano tale processo all’interno dell’Ecosistema.
svolge e la corrispondente sincronizzazione)
Le modalità tecniche 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/o fruitore dei servizi, come precedentemente descritto.
Nei paragrafi seguenti vengono dettagliate le fasi di processo per il corretto utilizzo delle API da parte degli Aderenti che intendono scambiare le informazioni all'interno dell'Ecosistema TDH.
5.4 Messa a disposizione delle Linee Guida e Catalogo API
Il Catalogo contiene tutte le API offerte e potenzialmente disponibili per essere utilizzate all'interno dell’Ecosistema TDH. A tale scopo l’Ecosistema TDH mette a disposizione dei referenti operativi dei partner gli standard tecnologici e le 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 serie di API, ognuna delle quali consente sia la trasmissione (PUT) sia la ricezione di dati dall’Ecosistema (GET).
Per maggiori dettagli sulle API, fare riferimento alla specifica documentazione tecnica disponibile all’interno
degli allegati all’Accordo di adesione, oppure nella specifica area dedicata sul TDH.
Il Catalogo sarà costantemente aggiornato e reso fruibile in base alla roadmap di evoluzione dell’Ecosistema
TDH coordinata dal MiTur.
Il referente operativo del partner sarà supportato dal TMB che lo affiancherà per le fasi di implementazione/test/collaudo/assistenza della soluzione di interoperabilità a mezzo API con il TDH.
5.5 Selezione API di interesse
Il referente operativo 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”.
In particolare, per gli Aderenti le API di principale interesse saranno riferite alla condivisione e/o alla trasmissione di contenuti digitali (articoli, immagini, video, etc...) 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.
5.6 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.
5.7 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 negli opportuni ambienti di pre-prod/Integrazione, 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.
5.8 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.
5.9 Avvio chiamate per trasferimento dati
Una volta ottenuto il consenso all’utilizzo dell’API da parte del TMB, l’Aderente erogatore riceverà le opportune configurazioni per l’ambiente di produzione (endpoint, credenziali, etc) e sarà autorizzato ad
avviare le chiamate per trasmettere i propri dati e informazioni all’interno dell’Ecosistema TDH di produzione,
nel rispetto degli impegni assunti con l’accordo di adesione e interoperabilità con il TDH.
5.10 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.