Da Libro Bianco OpenPass.
|
|
| Riga 1: |
Riga 1: |
| − | == Architettura software dei servizi Web Sistema OpenPass == | + | == Servizi del Formato 3 == |
| − | La comunicazione tra il server OpenPass ed i client delle stazioni avviene su protocollo HTTP mediante l’architettura software RESTful.
| |
| − | | |
| − | Per la comunicazione sono stati progettati e realizzati sei servizi organizzate in risorse web accessibili a seguito di autenticazione.
| |
| − | | |
| − | L’architettura software utilizza il paradigma client-server; i servizi attivati, in architettura RESTFul, sono di seguito riportati.
| |
| − | | |
| | | | |
| | === LOGIN === | | === LOGIN === |
Versione delle 13:17, 26 set 2016
Servizi del Formato 3
LOGIN
Consente l’autenticazione di un utente che desidera collegarsi. Ad ogni stazione è associata una login specifica fornita da ANEF SKI Lombardia. L’autenticazione vale per tutta la durata della sessione di scambio dati.
Parametri input
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| Username |
testo |
si |
Username della stazione
|
| Password |
testo |
si |
Password della stazione
|
Parametri output
| Parametro |
Tipo |
Descrizione
|
| Group |
numerico |
Codice univoco di identificazione del gruppo
|
| Company |
numerico |
Codice univoco di identificazione del gruppo
|
REGISTERTOKEN
Consente di registrare un token personalizzato. I tokens che cominciano con ‘Root.’ richiedono l’accesso di un amministratore. Ogni token ha un tipo associato (es. numerico, data, ora etc.). Il token non dipende dalla Stazione che ne fa richiesta.
Parametri input
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| Name |
testo |
si |
Nome del token
|
| Description |
testo |
si |
Descrizione del significato di token
|
| Type |
numerico |
si |
Tipo assegnato (0=numerico, 1=data, 2=ora)
|
Parametri output
| Parametro |
Tipo |
Descrizione
|
| CreatedNew |
boolean |
Booleano che indica se il token è stato aggiunto
|
REGISTERFORMAT
Consente di registrare un formato di registrazione da utilizzare per la produzione e l’interpretazione di biglietti. Ritorna un codice identificativo univoco per il formato. La chiamata può essere effettuata tutte le volte che si vuole, il sistema ritornerà sempre lo stesso codice. Il codice di formato è quindi uguale per tute le stazioni che ne fanno richiesta. Lo stesso formato può essere condiviso tra più biglietti (es. Stagionale Adulti, Ridotto, FISI etc.).
Parametri input
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| Description |
testo |
si |
Descrizione del formato
|
| Creator |
testo |
si |
Nome del creatore del formato
|
| Fixed area |
oggetto |
no |
Oggetto contenente gli oggetti TokenAllocation della fixed area
|
| Variable area |
oggetto |
no |
Oggetto contenente gli oggetti TokenAllocation della variable area
|
Oggetto Fixed area
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| TokenAllocation |
oggetto |
si |
Oggetto contenente i valori dei Token
|
Oggetto Variable area
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| TokenAllocation |
oggetto |
si |
Oggetto contenente i valori dei Token
|
Oggetto TokenAllocation
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| Name |
testo |
si |
Nome del Token precedentemente salvato
|
| BitAdress |
numerico |
no |
BitAdreass
|
| BitWidth |
numerico |
no |
BitWidth
|
| ConstantValue |
numerico |
no |
ConstantValue
|
Parametri output
| Parametro |
Tipo |
Descrizione
|
| FormatIdentifier |
numerico |
Codice numerico univoco di identificazione del formato
|
ENUMERATEFORMATS
Restituisce l'elenco esaustivo dei codici identificativi dei formati noti al server.
Parametri input
Nessuno
Parametri output
| Parametro |
Tipo |
Descrizione
|
| FormatIdentifiers |
oggetto |
Lista dei codici identificativi dei formati noti al server
|
Oggetto FormatIdentifiers
| Parametro |
Tipo |
Descrizione
|
| Int |
numerico |
Codice numerico univoco di identificazione dei formati noti al server
|
GETFORMAT
Dato un codice identificativo di formato ottiene la definizione dello stesso
Parametri input
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| FormatIdentifier |
numerico |
si |
Codice numerico univoco di identificazione del formato
|
Parametri output
| Parametro |
Tipo |
Descrizione
|
| Identifier |
numerico |
Codice numerico univoco di identificazione del formato
|
| Description |
testo |
Descrizione del formato
|
| Creator |
testo |
Nome del creatore del formato
|
| LastTouch |
data |
Data e ora di creazione
|
| Fixed area |
oggetto |
Oggetto contenente gli oggetti token allocation della fixed area
|
| Variable area |
oggetto |
Oggetto contenente gli oggetti toke allocation della variable area
|
Oggetto Fixed area
| Parametro |
Tipo |
Descrizione
|
| TokenAllocation |
oggetto |
Oggetto contenente i valori dei Token
|
Oggetto Variable area
| Parametro |
Tipo |
Descrizione
|
| TokenAllocation |
oggetto |
Oggetto contenente i valori dei Token
|
Oggetto TokenAllocation
| Parametro |
Tipo |
Descrizione
|
| Name |
testo |
Nome del Token precedentemente salvato
|
| BitAdress |
numerico |
BitAdress
|
| BitWidth |
numerico |
BitWidth
|
| ConstantValue |
numerico |
ConstantValue
|
REGISTERTICKET
Consente di registrare un set di valori di tokens costanti per una certa categoria di biglietti al fine di poterla identificare con rapidità nelle elaborazioni dati. (Es. Stagionale adulti, Stagionale ridotto). Ritorna un codice identificativo univoco per il biglietto che è identico al valore passato per il token “TicketID” obbligatorio. La chiamata può essere effettuata tutte le volte che si vuole; a parità di valori il sistema ritornerà sempre lo stesso codice. La chiamata consente una registrazione diversa per ogni Stazione, ma il codice numerico ritornato sarà a parità di set di valori lo stesso su più stazioni. Due biglietti uguali non possono né devono avere codici identificativi differenti.
Parametri input
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| Description |
testo |
si |
Descrizione del ticket
|
| CustomerAge |
numerico |
si |
Classe di età del destinatario del biglietto (1=”Bambini <=11”, 2=”Ragazzi 12-17”, 3=”Adulti 18-64”, 4=”Senior >= 65”)
|
| CustomerType |
numerico |
no |
Tipologia del destinatario del biglietto (1=”Non Residenti”, 2=”Residenti”)
|
| Values |
oggetto |
si |
oggetto contenente i TokenValue
|
Oggetto Values
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| TokenValue |
oggetto |
si |
Oggetto che contiene i dati dei token
|
Oggetto TokenValue
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| Name |
testo |
si |
Nome del token. (Il Token “Root.TicketID” è obbligatorio)
|
| Value |
testo |
si |
Valore del token. (Il valore del Token “Root.TicketID” è obbligatorio)
|
Parametri output
| Parametro |
Tipo |
Descrizione
|
| TicketIdentifier |
numerico |
Codice numerico univoco di identificazione del biglietto. Il codice restituito sarà quello che viene passato con il Token “Root. TicketID”
|
ENUMERATETICKETS
Ottieni l’elenco esaustivo dei codici identificativi dei biglietti noti al server per la stazione specificata.
Parametri input
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| Company |
numerico |
si |
Codice numerico univico di identificazione della stazione
|
Parametri output
| Parametro |
Tipo |
Descrizione
|
| TicketIdentifiers |
oggetto |
Lista dei codici identificativi dei ticket noti al server
|
Oggetto TicketIdentifiers
| Parametro |
Tipo |
Descrizione
|
| Int |
numerico |
Codice numerico univoco di identificazione dei ticket noti al server
|
GETTICKET
Dato un codice identificativo di biglietto, ottiene la definizione dello stesso
Parametri input
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| Company |
numerico |
si |
Codice numerico univoco di identificazione della stazione
|
| TicketIdentifier |
numerico |
si |
Codice numerico univoco di identificazione del biglietto
|
Parametri output
| Parametro |
Tipo |
Descrizione
|
| Identifier |
numerico |
Codice numerico univoco di identificazione del biglietto
|
| Description |
testo |
Descrizione del biglietto
|
| CustomerAge |
numerico |
Classe di età del destinatario del biglietto (1=”Bambini <=11”, 2=”Ragazzi 12-17”, 3=”Adulti 18-64”, 4=”Senior >= 65”)
|
| CustomerType |
numerico |
Tipologia del destinatario del biglietto (1=”Non Residenti”, 2=”Residenti”)
|
| LastTouch |
data |
Data e ora di creazione
|
| Values |
oggetto |
Oggetto contenente i TokenValue
|
Oggetto Values
| Parametro |
Tipo |
Descrizione
|
| TokenValue |
oggetto |
Oggetto che contiene i dati dei token
|
Oggetto TokenValue
| Parametro |
Tipo |
Descrizione
|
| Name |
testo |
Nome del token
|
| Value |
testo |
Valore del token
|
ENUMERATEGROUPS
Ottieni l'elenco esaustivo dei codici identificativi dei gruppi noti al server.
Parametri input
Nessuno
Parametri output
| Parametro |
Tipo |
Descrizione
|
| GroupIdentifies |
oggetto |
Lista dei codici identificativi dei gruppi noti al server
|
Oggetto GroupIdentifies
| Parametro |
Tipo |
Descrizione
|
| Int |
numerico |
Codice numerico univoco di identificazione dei gruppi noti al server
|
ENUMERATECOMPANIES
Ottieni l’elenco esaustivo delle stazioni note al server appartenenti al gruppo specificato.
Parametri input
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| Group |
numerico |
si |
Codice numerico univoco di identificazione del gruppo
|
Parametri output
| Parametro |
Tipo |
Descrizione
|
| Companies |
oggetto |
Lista dei codici identificativi delle stazioni appartenenti al gruppo
|
Oggetto Companies
| Parametro |
Tipo |
Descrizione
|
| Int |
numerico |
Codice numerico univoco di identificazione delle stazioni note al server
|
ENUMERATEWORKSTATIONS
Ottieni l’elenco esaustivo delle postazioni di vendita note al server appartenenti alla società specificata.
Parametri input
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| Company |
numerico |
si |
Codice numerico univoco di identificazione della stazione
|
Parametri output
| Parametro |
Tipo |
Descrizione
|
| Workstations |
oggetto |
Lista dei codici identificativi delle workstations appartenenti alla stazione
|
Oggetto Workstation
| Parametro |
Tipo |
Descrizione
|
| Int |
numerico |
Codice numerico univoco di identificazione delle workstations note al server
|
REGISTERWORKSTATIONKEY
Registra una chiave pubblica appartenente ad una postazione emittente
Parametri input
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| Group |
numerico |
si |
Codice numerico univoco di identificazione del group
|
| Company |
numerico |
si |
Codice numerico univoco di identificazione della stazione
|
| Workstation |
numerico |
si |
Codice numerico univoco di identificazione della workstation
|
| KeyIdentifier |
numerico |
si |
Codice di identificazione della chiave
|
| Expiri |
data |
si |
Data di fine validità della chiave
|
| KeyLength |
numerico |
si |
Lunghezza della chiave
|
| Modulus |
testo |
si |
Modulo della chiave
|
| Exponent |
testo |
si |
Esponente della chiave
|
Parametri output
| Parametro |
Tipo |
Descrizione
|
| CreatedNew |
boolean |
Booleano che indica se la chiave è stata aggiunta
|
ENUMERATEKEYS
Ottieni l’elenco esaustivo delle chiavi pubbliche della postazione emittente specificata
Parametri input
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| Group |
numerico |
si |
Codice numerico univoco di identificazione del gruppo
|
| Workstation |
numerico |
si |
Codice numerico univoco di identificazione della workstation
|
Parametri output
| Parametro |
Tipo |
Descrizione
|
| KeyIdentifiers |
oggetto |
Lista dei codici identificativi delle chiavi appartenenti alle workstation
|
Oggetto KeyIdentifiers
| Parametro |
Tipo |
Descrizione
|
| Int |
numerico |
Codice numerico univoco di identificazione delle chiavi
|
GETKEY
Ottieni la chiave pubblica specificata
Parametri input
| Parametro |
Tipo |
Obligatorio |
Descrizione
|
| Group |
numerico |
si |
Codice numerico univoco di identificazione del group
|
| Workstation |
numerico |
si |
Codice numerico univoco di identificazione della workstation
|
| KeyIdentifier |
numerico |
si |
Codice di identificazione della chiave richiesta
|
Parametri output
| Parametro |
Tipo |
Descrizione
|
| Group |
numerico |
Codice numerico univoco di identificazione del group
|
| Company |
numerico |
Codice numerico univoco di identificazione della stazione
|
| Workstation |
numerico |
Codice numerico univoco di identificazione della workstation
|
| KeyIdentifier |
numerico |
Codice di identificazione della chiave
|
| Expiri |
data |
Data di fine validità della chiave
|
| KeyLength |
numerico |
Lunghezza della chiave
|
| Modulus |
testo |
Modulo della chiave
|
| Exponent |
testo |
Esponente della chiave
|
REGISTERCUSTOMER
Permette la registrazione di un cliente sul sistema ottenendo un codice numerico identificativo
Parametri input
| Paramentro |
Tipo |
Obbligatorio |
Descrizione
|
| Name |
numerico |
si |
Nome del cliente
|
| Name |
numerico |
si |
Numero cliente attribuito localmente dalle casse emittenti
|
| Name |
numerico |
no |
CRSIdentifier
|
| Name |
testo |
no |
CRSData
|
| Name |
testo |
no |
Info1
|
| Name |
testo |
no |
Info2
|
| Name |
numerico |
no |
Codice Postale
|
| Name |
testo |
no |
Immagine
|
| Name |
data |
no |
Data di fine validità del record
|
Parametri output
| Paramentro |
Tipo |
Descrizione
|
| CustomerIdentifier |
numerico |
Codic enumerico univoco di identificazione del cliente identico al codice attribuito localmente dalle casse emittenti
|
| CreatedNew |
boolean |
Booleano che indica se il nuovo cliente è stato aggiunto
|
REGISTERSALES
Registra un insieme di vendite di biglietti di consorzio in formato comune sul server per il gruppo, la società e le postazioni specificate. Ogni chiamata può contenere una o più registrazioni di vendita. Ogni vendita è associata ad un cliente, il cui codice identificativo va ottenuto con l'invocazione del servizio RegisterCustomer. Il CustomerIdentifier è a 0 per i biglietti non nominativi. All’interno di ogni vendita, unitamente al ticket identifier (che specifica i valori costanti), vengono specificati i valori rilevanti dei tokens ‘dinamici’, ovvero quelli assegnati al momento dell’edizione di un biglietto.
Parametri input
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| Group |
numerico |
si |
Codice numerico univoco di identificazione del gruppo
|
| Company |
numerico |
si |
Codice numerico di identificazione della stazione
|
| Sales |
oggetto |
si |
Oggetto che contiene i SaleTransaction
|
Oggetto Sales
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| SaleTransaction |
oggetto |
si |
Oggetto che contiene i dati delle vendite
|
Oggetto SaleTransaction
| Paramentro |
Tipo |
Obbligatorio |
Descrizione
|
| Workstation |
numerico |
si |
Codice numerico univoco di identificazione della workstation
|
| OperationType |
numerico |
si |
Specifica il tipo di operazione (0=vendite, 1=annullamenti)
|
| CreationTime |
data |
si |
Data e ora di creazione e vendita del biglietto
|
| Amount |
numerico |
si |
Prezzo
|
| CustomerIdentifier |
numerico |
si |
Identificativo del cliente ottenuto registrando il cliente con il servizio RegisterCustomer (0 per biglietti non nominativi)
|
| TicketIdentifier |
numerico |
si |
Codice identificativo univoco del biglietto
|
| ChipID |
testo |
no |
ChipID dei dati di vendita
|
| Values |
oggetto |
si |
Oggetto che contiene i TokenValue
|
Oggetto Values
| Paramentro |
Tipo |
Obbligatorio |
Descrizione
|
| TokenValue |
oggetto |
si |
Oggetto che contiene i dati dei token
|
Oggetto TokenValue
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| Name |
testo |
si |
Nome del token
|
| Value |
testo |
si |
Valore del token
|
Parametri output
| Paramentro |
Tipo |
Descrizione
|
| InsertedRecordsCount |
numerico |
Numero dei record effettivamente inseriti
|
REGISTERPASSAGES
Registra un insieme di passaggi agli impianti di biglietti di consorzio in formato comune sul server per il gruppo, la società e gli impianti specificati. Ogni chiamata può contenere una o più registrazioni di passaggio. Ogni passaggio è opzionalmente associato ad un cliente, il cui codice identificativo va ottenuto con la RegisterCustomer. Ricordiamo che il CustomerIdentifier è a 0 per i biglietti non nominativi. All’interno di ogni passaggio, unitamente al ticket identifier (che specifica i valori costanti), vengono specificati i valori rilevanti dei tokens ‘dinamici’, ovvero quelli assegnati al momento dell’edizione di un biglietto e che si modificano durante l’utilizzo.
Parametri input
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| Group |
numerico |
si |
Codice numerico univoco di identificazione del gruppo
|
| Company |
numerico |
si |
Codice numerico univoco di identificazione del gruppo
|
| Passages |
oggetto |
si |
Oggetto che contiene i PassageTransaction
|
Oggetto Passages
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| PassageTransaction |
oggetto |
si |
Oggetto che contiene i dati dei passaggi
|
Oggetto PassageTransaction
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| CustomerIdentifier |
numerico |
si |
Identificativo del cliente ottenuto registrando il cliente con il servizio RegisterCustomer (0 per biglietti non nominativi)
|
| TicketIdentifier |
numerico |
si |
Codice identificativo del biglietto
|
| LogTime |
data |
si |
Data e ora del passaggio
|
| CheckpointName |
testo |
si |
Identificativo testuale univoco (case sensitive) dell’impianto di risalita all’interno della società specificata
|
Values || oggetto || si || Oggetto che contiene i TokenValue
Oggetto Values
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| TokenValue |
oggetto |
si |
Oggetto che contiene i dati dei token
|
Oggetto Token Value
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| Name |
testo |
si |
Nome del token
|
| Value |
testo |
si |
Valore del token
|
Parametri output
| Parametro |
Tipo |
Descrizione
|
| InsertedRecordsCount |
numerico |
Numero dei record effettivamente inseriti
|
SETDAILYFIRSTPASSAGESCOUNT
Invia al server, ai fini statistici, il conteggio indistinto dei primi passaggi di tutti i biglietti di stazione e di consorzio e non obbligatoriamente il conteggio distinto dei primi passaggi categorizzati.
Parametri input
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| Group |
numerico |
si |
Codice numerico univoco di identificazione del gruppo
|
| Company |
numerico |
si |
Codice numerico univoco di identificazione della stazione
|
| Values |
oggetto |
si |
Oggetto che contiene i DailyFirstPassagesCount
|
Oggetto Values
| Parametro |
Tipo |
Obbligatorio |
Descrizione
|
| DailyFirstPassagesCount |
oggetto |
si |
Oggetto che contiene i conteggi dei passaggi
|
Oggetto DailyFirstPassagesCount
| Paramentro |
Tipo |
Obbligatorio |
Descrizione
|
| Day |
data |
si |
Data del giorno a cui si riferisce il conteggio dei passaggi
|
| Count |
numerico |
si |
Numero dei passaggi
|
Parametri output
Nessun parametro.
ERRORI
| Sigla |
Significato
|
| 200 Bad credentials |
Le credenziali fornite sono errate
|
| 201 Must login first |
Non è stato eseguito il login
|
| 202 Bad request |
Errore generico nella richiesta
|
| 203 Unknown token |
Un token menzionato nel formato non è conosciuto
|
| 204 Unknown format |
Il formato richiesto è sconosciuto
|
| 205 Unknown ticket |
Il biglietto richiesto è sconosciuto
|
| 206 Unknown company |
La società non è nell’elenco del server
|
| 210 Unknown group |
Il gruppo specificato non è noto al server
|
| 211 Unknown Company |
La società specificata non è nota al server
|
| 212 Unknown workstation |
La postazione specificata non è nota al server
|
| 220 Unknown key |
La chiave richiesta non è stata registrata
|
| 301 Root.TicketID can not be empty or text |
Si è inviata la registrazione di un biglietto sprovvisto di numero di identificazione o con numero di identificazione non numerico
|
| 302 CustomerAge can not be empty |
Si è inviata la registrazione di un biglietto sprovvisto di informazione relativa alla fascia di età, oppure con un codice relativo alla fascia di età errato
|
