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
TDH – Manifestazione di Pubblico Interesse (VAT Refund) – Architettura
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: 1
Data: 15/11/2022
TABELLA DELLE VERSIONI | |||
Data | Versione | Descrizione | Par. modificati |
15/11/2022 | 1 | Prima redazione del documento | All |
Indice
2.3 Xxxxxxxxx – VAT Refund Player 7
3.3 Xxxxxxxxx – VAT Refund Player 11
1. Scopo del documento
Lo scopo del documento è la condivisione delle informazioni di tipo architetturale in merito all’implementazione delle API di Interconnessione tra il TDH e gli operatori del settore del rimborso dell’IVA (VAT Refund) che vorranno attestarsi ad esso. In tal senso, dovranno essere considerate le seguente API di interconnessione:
• Get Gustomer Data
• Get Refund Status
A mezzo delle API appena menzionate quindi, l’operatore VAT Refund attestato al Tourism Digital Hub (TDH) potrà agevolare la fase di emissione della fattura tramite il pre-filling dei dati (Get Customer Data) oltre che esportare, in visualizzazione, l’avanzamento delle fatture dei turisti (Get Refund Status).
1.1 Acronimi e definizioni
ACRONIMO | DESCRIZIONE |
AEM | Adobe Experience Manager |
AEP | Adobe Experience Platform |
API | Application Programming Interface |
CIAM | Customer Identity Access Management (SAP Customer Data Cloud) |
CDP | Customer Data Platform |
MIDDLEWARE | Orchestra la comunicazione tra CIAM e CDP |
JWT | JSON Web Token |
REST | REpresentational State Transfer API – Interfaccia di programmazione API |
SOAP | SOAP – Interfaccia di programmazione API |
TIBCO | Piattaforma implementata quale middleware |
XDM | Experience Data Model |
Tabella 1 - Acronimi e definizioni
1.2 Prerequisiti
Per poter usufruire delle chiamate alle API verso il Middleware sono richieste le autenticazioni descritte di seguito:
- Effettuare la chiamata al servizio {ambiente}/rest/version/getOAuth passando come input clientID =
clientID e clientSecret = clientSecret forniti in precedenza
- Il servizio restituirà un token che dovrà essere passato in come bearer della Get Customer Data O Get Refuns Status
Per la corretta individuazione di {ambiente}, vedere il paragrafo “Error! Reference source not found. Error! Reference source not found.”.
Figura 1 - Sequence Diagram per la generazione del Token
1.3 Platform Architecture
Di seguito lo schema architetturale delle chiamate.
Figura 2 - Platform Architecture
2 Get Customer Data
L’API Get Customer Data è necessaria per fornire ai VAT Refund Player i dati relativi agli utenti che utilizzano il QR Code per il pre-filling dei dati in negozio.
2.1 Assunzioni
Questo paragrafo definisce le assunzioni alla base della solution.
o La comunicazione tra il VAT Refund Player e il CIAM avviene tramite il Middleware che si occuperà di:
• Recuperare le informazioni necessarie dal CIAM
• Inviare le informazioni necessarie al VAT Refund Player o La comunicazione tra il CIAM e il Middleware avviene tramite:
• API
o La comunicazione tra Middleware e VAT Refund Player avviene tramite:
• API
2.2 Use Case
Questo paragrafo descrive il caso d’uso della solution per il pre-filling dei dati:
Nel caso d’uso l’utente naviga su Xxxxxx.xx, si logga con le credenziali definite in fase di registrazione ed entra nella sua area riservata.
L’utente continua la navigazione accedendo alla sezione del sito “VAT Refund Wallet”, clicca “completa il profilo” ed inserisce i dati relativi al passaporto necessari per poter attivare il servizio di Tax Free Shopping.
Una volta attivato il servizio, nella sezione del sito “VAT Refund Wallet”, l’utente potrà generare il QR Code, tramite il pulsante Genera QR code, da far scannerizzare al negozio in fase di acquisto.
Infine, una volta che il turista avrà effettuato i suoi acquisti, la scansione del QR Code da parte del negoziante, permetterà ai VAT Refund Player di recuperare le informazioni necessarie per interrogare il TDH permettendo il pre-filling delle fatture con i dati che l’utente ha inserito precedentemente nella sua area personale.
Figura 3 - Flowchart del processo di Pre-filling
2.3 Xxxxxxxxx – VAT Refund Player
2.3.1 Request
RESPONSE BODY – application/json
FIRST LEVEL | DESCRIPTION | TYPE | NOTE | MAND ATORY |
ciam_id | Codice univoco alfanumerico generato dal CIAM per identificare ogni turista registrato nella piattaforma TDH | String | no | |
doc_number | Numero identificativo del passaporto o della carta di identità (in caso di paesi SEE/EFTA non UE) inserita in fase di attivazione del servizio “VAT Refund” sulla piattaforma TDH | String | no | |
doc_iso | Paese di emissione del passaporto o della carta di identità (in caso di paesi SEE/EFTA non UE) inserita in fase di attivazione del servizio “VAT Refund” sulla piattaforma TDH | String | ISO ALPHA 2 | no |
Tabella 2 - Request Get Customer Data VAT Refund Player
2.3.2 Response
RESPONSE BODY – application/json
FIRST LEVEL | DESCRIPTION | TYPE | NOTE | MAND ATORY |
ciam_id | Codice univoco alfanumerico generato dal CIAM per identificare ogni turista registrato nella piattaforma TDH | String | yes | |
tourist_name | Nome con cui il turista si è registrato sulla piattaforma TDH | String | yes | |
tourist_surname | Xxxxxxx con cui il turista si è registrato sulla piattaforma TDH | String | yes | |
tourist_email | Indirizzo e-mail del turista che viene inserito in fase di registrazione sulla piattaforma TDH | String | yes | |
tourist_doc_number | Numero identificativo del passaporto o della carta di identità (in caso di paesi SEE/EFTA non UE) inserita in fase di attivazione del servizio “VAT Refund” sulla piattaforma TDH | String | yes |
tourist_doc_type | Tipo di documento | Enum | CI: Carta di identità PA: Passaporto | yes |
tourist_doc_exp | Data di scadenza del passaporto o della carta di identità (in caso di paesi SEE/EFTA non UE) inserita in fase di attivazione del servizio “VAT Refund” sulla piattaforma TDH | Date | yyyy-mm-dd | yes |
tourist_doc_iso | Paese di emissione del passaporto o della carta di identità (in caso di paesi SEE/EFTA non UE) inserita in fase di attivazione del servizio “VAT Refund” sulla piattaforma TDH | String | ISO ALPHA 2 | yes |
tourist_birth | Data di nascita del turista inserita in fase di attivazione del servizio “VAT Refund” sulla piattaforma TDH | Date | yyyy-mm-dd | yes |
tourist_country | Paese di residenza inserita in fase di attivazione del servizio “VAT Refund” sulla piattaforma TDH | String | ISO ALPHA 2 | yes |
tourist_birth_countr y | Paese di nascita riportato nel passaporto o nella carta di identità (in caso di paesi SEE/EFTA non UE) inserita in fase di attivazione del servizio “VAT Refund” sulla piattaforma TDH | String | ISO ALPHA 2 | yes |
Tabella 3 - Response Get Customer data CIAM
2.4 Middleware
Questa interfaccia verrà messa a disposizione del VAT Refund Player per recuperare i dati del cliente dal sistema TDH.
2.4.1. Sequence diagram
Di seguito è illustrato il sequence diagram del flusso oggetto del documento.
Figura 4 - Sequence Diagram Tax Refund Get Customer Data (int_090)
2.5 Swagger
2.5.1 Request
Name | Type | Description | |
ciamid (*) | string | ||
country | string | ||
docNumber | string |
Tabella 4 - Request Get Customer Data (int_090)
2.5.2 Response
Status Code | Name | Type |
200 | ciamId | string |
touristName | string | |
touristSurname | string |
touristEmail | string | |
touristDocNumber | string | |
touristDocType | string | |
touristDocExp | string | |
touristDocIso | string | |
touristBirth | string | |
touristCountry | string | |
touristBirthCountry | string | |
400 | codiceEsito | string |
500 | codiceEsito | string |
Tabella 5 - Response Get Customer Data (int_090)
3 Get Refund Status
L’API Get Refund Status è necessaria per mostrare su Xxxxxx.xx il riepilogo delle fatture, con il relativo status
d’avanzamento per il rimborso dell’IVA, dai sistemi dei VAT Refund Player.
3.1 Assunzioni
Questo paragrafo definisce le assunzioni alla base della solution.
o La comunicazione tra il VAT Refund Player e il CIAM avviene tramite il Middleware che si occuperà di:
• Recuperare le informazioni necessarie dal CIAM
• Inviare le informazioni necessarie al VAT Refund Player o La comunicazione tra il CIAM e il Middleware avviene tramite:
• API
o La comunicazione tra Middleware e VAT Refund Player avviene tramite:
• API
3.2 Use Case
Questo paragrafo descrive il caso d’uso della solution per la visualizzazione del riepilogo delle fatture:
Nel caso d’uso l’utente naviga su Xxxxxx.xx, si logga con le credenziali definite in fase di registrazione ed entra nella sua area riservata.
L’utente continua la navigazione accedendo alla sezione “VAT Refund Wallet”, all’interno del quale ha già
inserito i dati relativi al passaporto e quindi attivato il servizio di Tax Free Shopping.
Nella sezione “VAT Refund Wallet”, ogni qual volta il turista accederà alla sezione verrà inviata una chiamata
al VAT Refund Player, per ricevere il riepilogo delle fatture:
• Nel caso non siano presenti fatture verrà mostrato un messaggio informativo in cui si consiglia di attendere
• Nel caso in cui siano presenti delle fatture vi sarà una tabella riepilogativa contenente il nome della
fattura, data di emissione fattura, valore dell’importo, negozio presso cui è stata emessa, città del
negozio, indirizzo del negozio, nome del VAT Refund Player, link alla fattura sul canale digitale del Player e status del rimborso della fattura.
Figura 5 - Flowchart del processo
3.3 Xxxxxxxxx – VAT Refund Player
3.3.1 Request
RESPONSE BODY – application/json
FIRST LEVEL | DESCRIPTION | TYPE | NOTE | MAND ATORY |
ciam_id | Codice univoco alfanumerico generato dal CIAM per identificare ogni turista registrato nella piattaforma TDH | String | no | |
doc_number | Numero identificativo del passaporto o della carta di identità (in caso di paesi SEE/EFTA non UE) inserita in fase di attivazione del servizio “VAT Refund” sulla piattaforma TDH | String | no | |
doc_iso | Paese di emissione del passaporto o della carta di identità (in caso di paesi SEE/EFTA non UE) inserita in fase di attivazione del servizio “VAT Refund” sulla piattaforma TDH | String | ISO ALPHA 2 | no |
Tabella 6 – Request Get Refund Status AEM
3.3.2 Response
RESPONSE BODY – application/json
0xx XXXXX | 0xx XXXXX | 0xx XXXXX | DESCRIPTION | TYPE | NOTE | MAND ATORY |
ciam_id { } | ciam_id | Codice univoco alfanumerico generato dal CIAM per identificare ogni turista registrato nella piattaforma TDH | String | yes | ||
ciam_id { } | doc_number | Numero identificativo del passaporto o della carta di identità (in caso di paesi SEE/EFTA non UE) inserita in fase di attivazione del servizio “VAT Refund” sulla piattaforma TDH | String | yes | ||
ciam_id { } | doc_iso | Paese di emissione del passaporto o della carta di identità (in caso di paesi SEE/EFTA non UE) inserita in fase di attivazione del servizio “VAT Refund” sulla piattaforma TDH | String | ISO ALPHA 2 | yes | |
ciam_id { } | vat_player | Nome del VAT Refund Player che sta gestendo la pratica | String | yes | ||
ciam_id { } | link | Link con il rimando presso il canale digitale del VAT Refund Player | String | yes | ||
ciam_id { } | invoices { } | inv_date | Data in cui è stata emessa la fattura | Date | yyyy-mm-dd | yes |
ciam_id { } | invoices { } | inv_number | Numero identificativo della fattura | String | yes | |
ciam_id { } | invoices { } | inv_total | Valore dell’importo della fattura | Float | ######.## | yes |
ciam_id { } | invoices { } | inv_shop | Negozio presso cui è stata emessa la fattura | String | yes |
ciam_id { } | invoices { } | inv_shop_city | Città del negozio presso cui è stata emessa la fattura | String | yes | |
ciam_id { } | invoices { } | inv_shop_addr ess | Indirizzo del negozio presso cui è stata emessa la fattura | String | yes | |
ciam_id { } | invoices { } | inv_status | Lo status nell’iter di rimborso della fattura | String | yes |
Tabella 7 - Campi Response Get Refund Status VAT Refund Player
3.3.3 Esempio di Response
{
"12345678":{
"ciam_id":"12345678", "doc_number":"AZ789254", "doc_iso":"UK", "vat_player":"Tax Refund",
"link":"https:\/\/xxx.xxxxxxxxx.xx\/", "invoice":[
{
"inv_date":"2022-08-28", "inv_number":"TR\/26\/2022", "inv_total":"1936.27", "inv_shop":"NEGOZIO DI PROVA",
"inv_shop_city":"ROMA", "inv_shop_address":"Via del Corso, 32", "inv_status":"0"
},
{
"inv_date":"2022-07-26",
"inv_number":"36",
"inv_total":"4000.00", "inv_shop":"NEGOZIO DI PROVA 2",
"inv_shop_city":"MILANO", "inv_shop_address":"Via della Spiga, 1", "inv_status":"1"
}
]
}
}
3.4 Middleware
Questa interfaccia verrà messa a disposizione per invocare il partner ed ottenere da esso l’elenco delle
fatture, con i loro attributi, associate al cliente che sta utilizzando il TDH.Sequence diagram
3.4.1 Sequence Diagram
Di seguito è illustrato il sequence diagram del flusso oggetto del documento.
Figura 6 - Sequence Diagram - Customer Bill Info (Int_091)
3.5 Swagger
3.5.1 Request
Name | Type | Description |
ciamId (*) | string | |
docNumber (*) | string | |
docIso (*) | string |
Tabella 8 - Request Customer Bill InfoResponse
3.5.2 Response
Code | Name | Type | |
200 | docIso | string | |
invoices | invNumber | string | |
invShopCity | string | ||
invStatus | string | ||
invTotal | string | ||
invDate | string | ||
invShop | string | ||
invShopAddress | string | ||
docNumber | string | ||
ciamId | string | ||
link | string | ||
vatPlayer | string | ||
400 | codiceEsito | string | |
500 | codiceEsito | string | |
Tabella 9 - Customer Bill InfoResponse
4 Vincoli e assunzioni
# | Tipo | Descrizione |
1 | Disegno Tecnico | Sono ancora in corso alcuni approfondimenti sul disegno tecnico che potrebbero comportare la modifica di una o più sezioni del documento. |