Ministero dell'economia e delle finanze
Nota 31-8-2012 n. 39377/Giochi/Sco/2012
Nuova versione del protocollo di comunicazione per le scommesse a quota fissa su simulazioni di eventi.
Emanata dal Ministero dell'economia e delle finanze, Amministrazione autonoma dei monopoli di Stato, Direzione generale, Direzione per i giochi, Ufficio scommesse sportive ed ippiche a quota fissa e scommesse ippiche a totalizzatore.
Nota 31 agosto 2012, n. 39377/Giochi/Sco/2012 (1).
Nuova versione del protocollo di comunicazione per le scommesse a quota fissa su simulazioni di eventi.
(1) Emanata dal Ministero dell'economia e delle finanze, Amministrazione autonoma dei monopoli di Stato, Direzione generale, Direzione per i giochi, Ufficio scommesse sportive ed ippiche a quota fissa e scommesse ippiche a totalizzatore.
Ai
Concessionari delle scommesse ippiche e sportive ed ai relativi fornitori dei servizi di connettività
Loro sedi
e, p.c.:
Alla
So.Ge.I. s.p.a.
Via Mario Carucci, 99
00143 - Roma
Si comunica la pubblicazione sul sito istituzionale di AAMS della bozza aggiornata versione 1.1 del protocollo di comunicazione delle scommesse a quota fissa su simulazioni di eventi (PSV), all'interno della quale sono stabilite le modalità di interazione con il sistema centrale di AAMS dei sistemi di accettazione del gioco per le suddette scommesse.
Si riepilogano, di seguito, le principali novità introdotte sulla scorta delle riunioni tecniche tenutesi con i stakeholder di settore:
- Sostituzione dell'attributo estesto TIME_STAMP con TIME_STAMP_UTC;
- struttura datetime sostituita da datetime_utc;
- modificato il messaggio 9000-2 Apertura evento virtuale;
- modificato il messaggio 9000-3 Richiesta estrazione.
Eventuali osservazioni, quesiti e richieste di chiarimento possono essere inviate all'indirizzo e-mail assistenza-giochi@sogei.it e, per conoscenza, a giochi.ufficio15@aams.it.
Il Dirigente
Luca Turchi
Allegato
Protocollo per le scommesse su eventi virtuali
Introduzione
Il PSV è un protocollo applicativo per la gestione delle scommesse a quota fissa su eventi virtuali.
Le interazioni tra client e server si basano sullo scambio di due messaggi: richiesta e risposta e per definizione, il client effettua la richiesta ed il server invia la risposta.
Il protocollo è di tipo half-duplex in quanto un client non può inviare al server un messaggio se sta ancora attendendo la risposta relativa ad una richiesta precedente.
Per consentire l'utilizzo del protocollo all'interno di una rete a più livelli in cui sono presenti nodi intermedi, che eseguono funzionalità applicative, è stato scelto di non orientare il protocollo alla connessione.
1. Entità coinvolte
I soggetti coinvolti nell'utilizzo del protocollo sono: l’Amministrazione Autonoma dei Monopoli di Stato, i Fornitori del servizio di Connettività, i Concessionari e il Totalizzatore Nazionale.
Nel presente documento i nomi dei soggetti sono abbreviati secondo le seguenti sigle:
Entità
Sigla
Amministrazione autonoma dei monopoli di Stato
AAMS
Fornitore del Servizio di Connettività
FSC
Concessionario
CN
Punto Vendita
PVEND
Terminale di accettazione gioco
TAG
Totalizzatore Nazionale
TN
2. Allineamento applicativo
Una transazione PSV è intesa come una sequenza di messaggi “richiesta+risposta” scambiati tra un client ed un server; la sequenza è identificata univocamente tramite un apposito campo del protocollo obbligatorio in ciascun messaggio.
Il client è tenuto a valorizzare il campo identificativo della transazione nel messaggio di richiesta ed il server restituisce, nella risposta, il medesimo valore permettendo al client di associare i messaggi di risposta alla richiesta.
Il client che non dovesse ricevere la risposta attesa è autorizzato, secondo gli intervalli della tabella:
2 secondi
Prima retry
4 secondi
Seconda retry
4 secondi
Dalla terza retry in poi
a ripetere la richiesta mantenendo inalterato il campo identificativo di transazione.
Questa regola consente di ottenere l’allineamento applicativo ovvero:
- Il client che dovesse ricevere una risposta con un identificativo di transazione diverso da quello inviato in richiesta, ha la possibilità di scartare tale risposta in attesa di quella corretta;
- Il server elabora la richiesta che ha ricevuto, invia la risposta al client e ne memorizza il contenuto. Nel caso in cui il server dovesse ricevere una richiesta, dallo stesso client contenente il medesimo identificativo di transazione, restituisce la risposta memorizzata senza elaborare nuovamente il messaggio. Il recupero del messaggio di risposta dal server è possibile esclusivamente per l’ultima transazione elaborata.
È obbligatorio che ciascun client generi un identificativo di transazione differente tra due transazioni consecutive.
Il client è tenuto ad inviare la richiesta fino al ricevimento della risposta per tutti i messaggi che comportano la variazione dei dati presenti sul server.
3. Convenzioni di codifica
Di seguito sono riportati e descritti i tipi di dati utilizzati nelle specifiche dei messaggi del protocollo:
Tipo
Descrizione
bit
Numero di un bit. Può valere 0 od 1
boolean
Numero di 8 bit senza segno. Può valere solo 0 od 1. Il valore 0 significa "falso" mentre il valore 1 significa "vero" (qualsiasi altro valore diverso da 0 viene considerato "vero")
char
Numero di 8 bit con segno (complemento a due)
uchar
Numero di 8 bit senza segno
short
Numero di 16 bit con segno (complemento a due)
ushort
Numero di 16 bit senza segno
Int
Numero di 32 bit con segno (complemento a due)
uint
Numero di 32 bit senza segno
long
Numero di 64 bit con segno (complemento a due)
ulong
Numero di 64 bit senza segno
ret_code
Numero di 16 bit con segno che descrive l'esito di una richiesta
string
Struttura per la rappresentazione di vettori di uchar a lunghezza variabile costituita da un uchar che indica la lunghezza del vettore seguito da tanti uchar per quanti sono gli elementi del vettore. La rappresentazione/codifica dei caratteri è secondo lo standard ISO/IEC 8859-1.
lstring
Struttura per la rappresentazione di vettori di uchar a lunghezza variabile costituita da un ushort che indica la lunghezza del vettore seguito da tanti uchar per quanti sono gli elementi del vettore (vettori più grandi di 256). La rappresentazione/codifica dei caratteri è secondo lo standard ISO/IEC 8859-1.
datetime_utc
Struttura per la rappresentazione di data e ora (lunghezza 7 byte)
Tipo
Descrizione
ushort
Anno
uchar
Mese (da 1 a 12)
uchar
Giorno (da 1 a 31)
uchar
Ora (da 0 a 23)
uchar
Minuti (da 0 a 59)
uchar
Secondi (da 0 a 59)
La dicitura ‘[n]’ seguente uno dei tipi rappresentati indica che si tratta di un vettore di ‘n’ elementi del tipo indicato. È possibile specificare matrici a più dimensioni indicandone per ciascuna la dimensione massima tramite l'unione di più diciture '[n]'.
Esempi:
char[16] indica un vettore di 16 caratteri con segno;
long[4] indica un vettore di 4 long;
bit[8][25] indica una matrice di 25 elementi da 8 bit ciascuno.
Nel caso di vettori di tipo bit, gli stessi sono considerati numerati da 0 alla dimensione del vettore meno 1.
Tutti i campi numerici specificati nei messaggi vanno considerati in modalità big endian. (Sistema di indirizzamento della memoria in cui gli elementi più lunghi di un byte, vengono memorizzati con gli 8 bit più significativi nell'indirizzo più basso).
4. Struttura dei messaggi
Ogni messaggio applicativo, scambiato tra un client ed un server è composto da tre elementi: l’header, il body e gli attributi estesi.
L'header ha una lunghezza fissa mentre il body e gli attributi estesi hanno una lunghezza variabile.
Il body e gli attributi estesi possono non essere presenti relativamente alle necessità applicative.
Gli attributi estesi seguono sempre il body.
Nel documento è possibile fare riferimento ai campi di un messaggio tramite la sintassi parte.campo dove parte può essere header, body od attributi estesi e campo indica il nome del campo nell’elemento indicato.
La dimensione massima che il messaggio (header + body + attributi estesi) può assumere è 4 Kbyte.
4.1 - Header
L'header è una struttura comune a tutti i messaggi del protocollo ed è costituita dai seguenti campi:
Campo
Tipo
Descrizione
versione
uchar
Versione protocollo. Attualmente è 2
id_fsc
ushort
Identificativo del Fornitore del servizio di connettività
id_cn
uint
Identificativo del Concessionario. Il valore 0 indica che il client del servizio è il FSC
id_pvend
uint
Numero identificativo del punto vendita. Il valore 0 indica che il client del servizio è il FSC
id_tag
ushort
Numero identificativo del TAG all'interno del pvend (vedi nota seguente).
tipo_tag
uchar
Tipo TAG secondo la seguente codifica:
0
Client Fornitore del Servizio di Connettività
1
Terminale con operatore
2
Terminale self-service
3
Servizio telefonico con operatore
4
Servizio telefonico automatico
5
Internet
6
TV interattiva
lung_body
ushort
Lunghezza del body
lung_ae
ushort
Lunghezza totale degli attributi estesi
id_transazione
uchar[8]
Identificativo della transazione
id_servizio
ushort
Identificativo del servizio
id_messaggio
uchar
Identificativo del messaggio, univoco nell'ambito del servizio
liberi
uchar[3]
Per sviluppi futuri
Nota:
Il Campo TAG identifica il codice del terminale all’interno del punto vendita. Per un corretto utilizzo del campo TAG si devono distinguere i terminali fisici (TIPO_TAG 1, 2) e virtuali (TIPO_TAG 3, 4, 5, 6). Un’ulteriore distinzione va fatta per il TIPO_TAG 0.
Terminali fisici (TIPO_TAG 1, 2)
Sono i veri e propri terminali di gioco presenti nei punti vendita dei concessionari. Ogni punto vendita può utilizzare un criterio di sua scelta per la numerazione delle apparecchiature di gioco, ma il totale deve riflettere il numero degli apparecchi effettivamente presenti. Sarebbe altresì opportuno che la convenzione usata sia costante e che un terminale specifico si identifichi sempre con lo stesso codice. Limite massimo TAG utilizzabili = 150.
Terminali Virtuali (TIPO_TAG 3, 4, 5, 6)
Sono i terminali virtuali utilizzati nel cosiddetto "gioco a distanza". In questa tipologia di gioco il TAG non identifica un terminale fisico, ma individua un generico processo, utilizzato dal sistema client, per eseguire una transazione PSV completa verso il Totalizzatore Nazionale. Si evince che il client dovrebbe usare un insieme di risorse o "pool" ben definito per comunicare con il totalizzatore. Il numero del TAG identifica un processo all'interno del pool utilizzato. La dimensione del pool, cioè del numero di terminali virtuali o processi utilizzati, è funzione del carico transazionale, ovvero si utilizzeranno TAG diversi se più giocatori stanno simultaneamente eseguendo transazioni. Limite massimo TAG utilizzabili = 50.
Client Fornitore del Servizio di Connettività (TIPO_TAG 0)
Sono i terminali virtuali utilizzati dall'FSC per i servizi PSV di sua competenza: palinsesti, rendiconto contabile, firma digitale. Il sistema del Fornitore di Servizi dovrebbe utilizzare uno o due terminali al massimo per servizio. Limite massimo TAG utilizzabili = 30.
4.2 - Body
Il body è la struttura dati in grado di trasportare le informazioni applicative relative al messaggio.
Tabella dei servizi:
Servizio
Descrizione
9000
Servizio dei gestione dei palinsesti
9100
Servizio di vendita
9200
Servizio rendiconto
9300
Servizio firma digitale
4.3 - Firma digitale
Per verificare l’origine e l’integrità di un messaggio il PSV, ove è necessario, prevede la gestione della firma digitale.
Modalità di firma:
- La firma deve essere applicata sull’intero messaggio (Header+Body+Ates);
- Sul messaggio viene calcolato il digest che poi viene firmato con la chiave privata;
- Il digest firmato con la chiave privata viene aggiunto al messaggio originale come attributo esteso;
- Gli algoritmi sono specificati nel tipo di attributo esteso.
Modalità di verifica:
- Il controllo della firma deve essere fatto sull’intero messaggio (Header+Body+Ates) escluso attributo esteso della firma;
- Si utilizza la chiave pubblica per decriptare il digest;
- Il digest decriptato deve essere confrontato con il digest del messaggio;
- Gli algoritmi sono specificati nel tipo di attributo esteso.
5. Servizio di gestione palinsesti
Il servizio di gestione del palinsesto permette al FSC, per conto di uno o più CN, di creare e gestire il proprio palinsesto.
Il palinsesto è un programma giornaliero disposto da uno o più CN che utilizzano la medesima piattaforma di gioco virtuale e contenente eventi virtuali della medesima disciplina. Ogni palinsesto è contraddistinto da un codice univoco.
Il codice palinsesto è composto da due numeri per l'anno, 3 numeri per l'FSC e 5 numeri per il progressivo all'interno dell'anno e dell'FSC.
Per esempio il primo palinsesto assegnato nell'anno 2012 all'FSC 999 è 1299900001 ovvero nel protocollo viaggerà come 000000004D7AE661.
Per potere accettare gioco su un determinato evento virtuale è necessario che tale evento e le sue principali caratteristiche siano dichiarate dal FSC al TN. Il TN codifica l'evento virtuale in modo univoco all'interno del palinsesto.
Il FSC richiede i numeri pseudo casuali per la determinazione del risultato ufficiale dell'evento virtuale al TN, fornendo tutti i dati necessari. Contestualmente a questa richiesta il TN chiude l'accettazione delle scommesse sull'evento virtuale.
Successivamente allo svolgimento dell'evento virtuale il FSC fornirà al TN i risultati ufficiali elaborati.
5.1 - Palinsesto
Client abilitato
FSC,0,0,TAG
Header.id servizio
9000
Header.id_messaggio
1
Descrizione:
Questo messaggio consente ad un FSC di ottenere il codice del palinsesto che intende aprire sul TN.
Un palinsesto può essere aperto al massimo con un giorno di anticipo rispetto alla data di richiesta.
Richiesta:
body:
Campo
Tipo
Descrizione
cod_piatt
ushort
Codice univoco assegnato alla piattaforma di gioco virtuale
disciplina
ushort
Codice della disciplina del palinsesto
anno
ushort
Anno del palinsesto
mese
uchar
Mese del palinsesto
giorno
uchar
Giorno del palinsesto
n_conc
ushort
Numero di concessionari che aderiscono al palinsesto (zero indica tutti i concessionari dell'FSC)
conc
uint
Codice concessionario (se tutti il campo non è presente)
attributi estesi:
- IP_RISP
Facoltativo
Risposta:
body:
Campo
Tipo
Descrizione
esito
ret_code
Esito della richiesta. I campi seguenti possono non essere presenti in caso di esito negativo
palinsesto
ulong
Codice del palinsesto
attributi estesi:
-
TIME_STAMP_UTC
Obbligatorio
-
IP_RISP
Facoltativo
codici di ritorno:
- 1024 - Richiesta ok seguono informazioni della richiesta;
- 1513 - Concessionario non identificato;
- 2006 - Disciplina non identificata;
- 2007 - Un Palinsesto della disciplina indicata risulta già codificato per la giornata attuale;
- 2008 - Piattaforma non identificata;
- 2009 - Piattaforma senza concessionari abilitati.
5.2 - Apertura evento virtuale
Client abilitati
FSC,0,0,TAG
header.id_servizio
9000
header.id_messaggio
2
Descrizione:
Questo messaggio consente ad un FSC di ottenere un codice univoco per l'identificazione di un evento virtuale all'interno del palinsesto e contestualmente di aprire l'accettazione delle giocate su di esso.
Un evento virtuale può essere aperto al massimo con quattro ore di anticipo rispetto all'orario di richiesta.
Richiesta:
body:
Campo
Tipo
Descrizione
cod_piatt
ushort
Codice univoco assegnato alla piattaforma di gioco virtuale
palinsesto
ulong
Codice del palinsesto
Descr_eve
string
Descrizione dell'evento virtuale
Data_ora_eve
datetime_utc
Data svolgimento dell'evento virtuale
n_var
uchar
Numero di elementi “Dati Evento” che seguono. Vale 0 se i dati non sono significativi
Dati Evento
Cod_var
uchar
Codice della variabile
valore
uint
Valore della variabile espressa in decimillesimi
n_scom
uchar
Numero di elementi “Scommessa” che seguono
Scommessa
Cod_scom
ushort
Codice della tipologia di scommessa
n_var
uchar
Numero di elementi “Dati Scommessa” che seguono. Vale 0 se i dati non sono significativi
Dati Scommessa
Cod_var
uchar
Codice della variabile
Valore
uint
Valore della variabile espressa in decimillesimi
n_esiti
uchar
Numero di elementi “Esito” che seguono. Vale 0 se i dati non sono significativi per la tipologia di scommessa
Esito
esito
uchar
Codice dell'esito
peso
uint
Probabilità legata all'esito espressa in decimillesimi
quota
uint
Valore della quota espressa in centesimi
n_var
uchar
Numero di elementi “Dati Esito” che seguono. Vale 0 se i dati non sono significativi
Dati Esito
cod var
uchar
Codice della variabile
valore
uint
Valore della variabile espressa in decimillesimi
attributo estesi:
- IP_RISP
Facoltativo
Risposta:
body:
Campo
Tipo
Descrizione
esito
ret_code
Esito della richiesta. I campi seguenti possono non essere presenti in caso di esito negativo
cod_eve
ushort
Codice assegnato all'evento virtuale
attributi estesi:
-
TIME_STAMP_UTC
Obbligatorio
-
IP_RISP
Facoltativo
codici di ritorno:
- 1024 - Richiesta ok seguono informazioni della richiesta
- 2000 - Palinsesto non identificato;
- 2002 - Tipologia di scommessa non identificata;
- 2003 - Esito non identificato;
- 2004 - Errore peso;
- 2008 - Piattaforma non identificata;
- 2010 - Palinsesto non associato alla piattaforma indicata;
- 2011 - Data evento diversa dalla data palinsesto;
- 2012 - Palinsesto non aperto;
- 2013 - Numero massimo eventi giornaliero superato;
- 2014 - Assenza scommesse con esiti;
- 2015 - Variabili errate;
- 2020 - Data ora evento non valida.
5.3 - Richieste estrazione
Client abilitati
FSC,0,0,TAG
header.id_servizio
9000
header.id_messaggio
3
Descrizione:
Questo messaggio consente ad un FSC di richiedere al TN i numeri pseudo casuali necessari per la determinazione del risultato ufficiale dell'evento virtuale. Contestualmente a tale richiesta il TN chiude l'accettazione delle giocate sull'evento virtuale.
Richiesta:
body:
Campo
Tipo
Descrizione
cod_piatt
ushort
Codice univoco assegnato alla piattaforma di gioco virtuale
palinsesto
ulong
Codice del palinsesto
cod_eve
ushort
Codice dell'evento virtuale
n_scom
uchar
Numero di elementi “Scommessa” che seguono
Scommessa
cod_scom
ushort
Codice della tipologia di scommessa. Vale 0 se i numeri random non sono legati ad una particolare scommessa
n_random
uchar
Numero di numeri random
attributo estesi:
- IP_RISP
Facoltativo
Risposta:
body:
Campo
Tipo
Descrizione
Esito
ret_code
Esito della richiesta. I campi seguenti possono non essere presenti in caso di esito negativo
cod_piatt
ushort
Codice univoco assegnato alla piattaforma di gioco virtuale
palinsesto
ulong
Codice del palinsesto
cod_eve
ushort
Codice dell'evento virtuale
n_scom
uchar
Numero di elementi "Dati Scommessa" che seguono
Dati Scommessa
cod_scom
ushort
Codice della tipologia di scommessa. Vale 0 se i numeri random non sono legati ad una particolare scommessa
n_random
uchar
Numero di elementi "Dati Random" che seguono
Dati Random
ordine
uchar
Ordine dei numeri random
random
int
Numero random estratto
attributi estesi:
-
TIME_STAMP_UTC
Obbligatorio
-
IP_RISP
Facoltativo
codici di ritorno:
- 1024 - Richiesta ok seguono informazioni della richiesta;
- 2001 - Evento non identificato;
- 2002 - Tipologia di scommessa non identificata;
- 2008 - Piattaforma non identificata;
- 2016 - Evento non aperto;
- 2018 - Numero scommesse diverso da quello atteso.
5.4 - Risultati ufficiali
Client abilitati
FSC,0,0,TAG
header.id_servizio
9000
header.id_messaggio
4
Descrizione:
Questo messaggio consente al FSC di comunicare al TN i risultati ufficiali elaborati per un determinato evento virtuale.
Richiesta:
body:
Campo
Tipo
Descrizione
cod_piatt
ushort
Codice univoco assegnato alla piattaforma di gioco virtuale
palinsesto
ulong
Codice del palinsesto
cod_eve
ushort
Codice dell'evento virtuale
n_scom
uchar
Numero di elementi "Dati Scommessa" che seguono
Scommessa
cod_scom
ushort
Codice della tipologia di scommessa
n_esiti
uchar
Numero degli esiti, che determina il risultato, ufficiali indicati rispettivamente nell'ordine
esito
uchar
Codice dell'esito
attributi estesi:
- IP_RISP
Facoltativo
Risposta:
body:
Campo
Tipo
Descrizione
esito
ret_code
Esito della richiesta. I campi seguenti possono non essere presenti in caso d’esito negativo
attributi estesi:
- TIME_STAMP_UTC
Obbligatorio
- IP_RISP
Facoltativo
codici di ritorno:
- 1024 - Richiesta ok seguono informazioni della richiesta;
- 2001 - Evento non identificato;
- 2003 - Esito non identificato;
- 2008 - Piattaforma non identificata;
- 2017 - Evento non chiuso;
- 2018 - Numero scommesse diverso da quello atteso;
- 2019 - Numero esiti diverso da quello atteso.
5.5 - Annullo evento virtuale
Client abilitati:
FSC,0,0,TAG
header.id_servizio
9000
header.id_messaggio
5
Descrizione:
Questo messaggio consente al FSC di annullare un evento virtuale precedentemente aperto a causa di malfunzionamenti al sistema.
Richiesta:
body:
Campo
Tipo
Descrizione
cod_piatt
ushort
Codice univoco assegnato alla piattaforma di gioco virtuale
palinsesto
ulong
Codice del palinsesto
cod_eve
ushort
Codice dell'evento virtuale
Attributi estesi:
- IP_RISP
Facoltativo
Risposta:
body:
Campo
Tipo
Descrizione
esito
ret_code
Esito della richiesta. I campi seguenti possono non essere presenti in caso d’esito negativo
attributi estesi:
- TIME_STAMP_UTC
Obbligatorio
- IP_RISP
Facoltativo
codici di ritorno:
- 1024 - Richiesta ok seguono informazioni della richiesta
- 2000 - Palinsesto non identificato;
- 2001 - Evento non identificato;
- 2003 - Piattaforma non identificata;
- 2008 - Piattaforma non identificata;
- 2010 - Palinsesto non associato alla piattaforma indicata;
- 2018 - Evento non aperto.
6. Servizio vendita
Questo servizio consente ai concessionari tramite i loro client di vendere, pagare, rimborsare ed annullare scommesse a quota fissa su eventi virtuali.
6.1 - Vendita
Client abilitato
FSC,CN,PVEND,TAG
header.id_servizio
9100
header.id_messaggio
1
Descrizione:
Questo messaggio consente ad un Terminale di un PVEND di vendere scommesse a quota fissa singole o multiple su eventi virtuali.
Richiesta:
body:
Campo
Tipo
Descrizione
prezzo
uint
Prezzo del biglietto (in centesimi)
max_pag
uint
Importo massimo di pagamento
n_scom
uchar
Numero di scommesse che seguono (max 20)
Dettaglio delle scommesse
palinsesto
ulong
Codice palinsesto
cod_eve
ushort
Codice dell'evento virtuale
cod_scom
ushort
Codice della tipologia di scommessa
quota
uint
Quota associata all’esito espressa in centesimi
n_esiti
uchar
Numero degli esiti necessari per effettuare il pronostico sulla scommessa, indicati rispettivamente nell'ordine
esito
uchar
Codice dell'esito
attributi estesi:
- IP_RISP
Facoltativo
- ID_GIOCATA
Obbligatorio
- FIRMA_DIG01
Obbligatorio
- CONTO 2
Obbligatorio se è gioco a distanza
Risposta:
body:
Campo
Tipo
Descrizione
esito
ret_code
Esito della richiesta. I campi seguenti possono non essere presenti in caso di esito negativo
id
bit[80]
Identificativo del biglietto rappresentato in base sedici
attributi estesi:
-
TIME_STAMP_UTC
Obbligatorio
-
FIRMA_DIG01
Obbligatorio
-
IP_RISP
Facoltativo
-
CONTO 2
Obbligatorio se è gioco a distanza
codici di ritorno:
- 1024 - Richiesta ok seguono i dati della vendita;
- 1520 - Non è stato possibile verificare la firma digitale;
- 1517 - Il servizio di vendita è stato momentaneamente chiuso dal TN;
- 1521 - Richiesta di vendita nella quale non sono presenti gli attributi estesi obbligatori (ID_GIOCATA, FIRMA_DIG01, CONTO, CONTO_2 se si tratta di gioco a distanza);
- 1522 - Vendita con un Tipo Tag non abilitato per quel CN;
- 1523 - Errore conto;
- Vedere Tabella codici di ritorno - Vendita.
6.2 - Pagamento/Rimborso
Client abilitato
FSC,CN,PVEND,TAG
header.id_servizio
9100
header.id_messaggio
2
Descrizione:
Questo messaggio consente ad un CN di pagare e/o rimborsare un biglietto.
Richiesta:
body:
Campo
Tipo
Descrizione
id
bit[48]
Identificativo del biglietto rappresentato in base sedici
importo
uint
Importo effettivo da pagare e/o rimborsare
attributi estesi:
IP_RISP
Facoltativo
FIRMA_DIG01
Obbligatorio
CONTO_2
Obbligatorio se è gioco a distanza
Risposta:
body:
Campo
Tipo
Descrizione
esito
ret_code
Esito della richiesta. I campi seguenti possono non essere presenti in caso di esito negativo
id
bit[80]
Identificativo del biglietto rappresentato in base sedici
stato
uchar
Stato del biglietto (vedi tabella stati del biglietto)
importo
uint
Importo pagato e/o rimborsato
attributi estesi:
-
TIME_STAMP_UTC
Obbligatorio
-
FIRMA_DIG01
Obbligatorio
-
IP_RISP
Facoltativo
-
CONTO_2
Obbligatorio se è gioco a distanza
codici di ritorno:
- 1024 - Richiesta ok seguono i dati del pagamento e/o rimborso;
- 1520 - Non è stato possibile verificare la firma digitale;
- 1517 - Il servizio di pagamento è stato momentaneamente chiuso dal TN;
- 1521 - Richiesta di pagamento nella quale non sono presenti gli attributi estesi obbligatori (FIRMA_DIG01, CONTO_2 se si tratta di gioco a distanza);
- 1523 - Errore di conto;
- Vedere Tabella codici di ritorno - Pagamento.
6.3 -Informazione biglietto
Client abilitato
FSC,CN,PVEND,TAG
header.id_servizio
9100
header.id_messaggio
3
Descrizione:
Questo messaggio consente ad un CN di ottenere le informazioni relative ad un biglietto già emesso.
Richiesta:
body:
Campo
Tipo
Descrizione
id
bit[48]
Identificativo del biglietto rappresentato in base sedici
attributi estesi:
-
IP_RISP
Facoltativo
Risposta:
body:
Campo
Tipo
Descrizione
esito
ret code
Esito della richiesta
id
bit[48]
Identificativo del biglietto rappresentato in base sedici
prezzo
uint
Prezzo del biglietto (in centesimi)
max_pag
uint
Importo massimo di pagamento
n_scom
uchar
Numero di scommesse che seguono
Dettaglio delle scommesse
palinsesto
ulong
Codice del palinsesto
cod_eve
ushort
Codice dell'evento virtuale
cod_scom
ushort
Codice della tipologia di scommessa
quota
uint
Quota associata all'esito espressa in centesimi
n_esiti
uchar
Numero degli esiti necessari per effettuare il pronostico sulla scommessa, indicati rispettivamente nell'ordine
esito
uchar
Codice dell'esito
attributi estesi:
-
ID_GIOCATA
Obbligatorio
-
CONTO 2
Obbligatorio se è gioco a distanza
-
IP_RISP
Facoltativo
-
TIME_STAMP_UTC
Obbligatorio
codici di ritorno:
- 1024 - Richiesta ok seguono i dati del biglietto;
- 1516 - Il biglietto non esiste.
7. Rendiconto contabile del concessionario
Questo servizio consente a un FSC di ottenere i dati relativi al rendiconto contabile dei loro CN.
7.1 - Rendiconto giornaliero
Client abilitati:
FSC,0,0,TAG
header.id_servizio
9200
header.id_messaggio
1
Descrizione:
Questa funzione consente di ottenere dal TN i dati per l’analisi economici e finanziari per data di competenza.
Richiesta:
body:
Campo
Tipo
Descrizione
cn
uint
Identificativo concessionario
anno
ushort
Anno richiesto (da 0 a 65535)
mese
uchar
Mese richiesto (da 1 a 12)
giorno
uchar
Giorno richiesto (da 1 a 31)
attributi estesi:
- IP_RISP
Facoltativo
Risposta:
body:
Campo
Tipo
Descrizione
esito
ret_code
Esito della richiesta. I campi seguenti possono non essere presenti in caso di esito negativo
cn
uint
Identificativo concessionario
anno
ushort
Anno richiesto
mese
uchar
Mese richiesto (da 1 a 12)
giorno
uchar
Giorno richiesto (da 1 a 31)
n_caus
uchar
Specifica quanti sono gli elementi "Causale di Rendiconto" che seguono
Causale di Rendiconto
caus
ushort
Causale di rendiconto (vedi Tabella delle causali di rendiconto)
a.c.num
uint
Numero (il significato dipende dalla Causale di Rendiconto)
a.c.imp
uint
Importo (il significato dipende dalla Causale di Rendiconto)
aliq
ushort
Aliquota espressa in centesimi (il significato dipende dalla Causale di Rendiconto)
attributi estesi:
- IP_RISP
Facoltativo
codici di ritorno:
- 1024 - Richiesta ok seguono i dati;
- 1516 - Non ci sono dati per la richiesta fatta;
- 1530 - Dati non elaborati;
- 1513 - Il concessionario non appartiene al FSC;
- 1518 - I dati della richiesta non sono congruenti.
7.2 - Elenco biglietti prescritti
Client abilitati:
FSC,0,0,TAG
header.id_servizio
9200
header.id_messaggio
2
Descrizione:
Questo messaggio consente di ottenere dal TN l’elenco parziale o totale dei biglietti prescritti.
Non è consentito richiedere più di 20 biglietti alla volta
Richiesta:
body:
Campo
Tipo
Descrizione
cn
uint
Identificativo concessionario
anno
ushort
Anno di prescrizione
mese
uchar
Mese di prescrizione
giorno
uchar
Giorno di prescrizione
tck_iniziale
uint
Posizione del biglietto iniziale nell’elenco richiesto (da 1 a 4294967295)
tck_finale
uint
Posizione del biglietto finale nell’elenco richiesto (da 1 a 4294967295).
Attributi estesi:
- IP_RISP
Facoltativo
Risposta:
body:
Campo
Tipo
Descrizione
esito
ret_code
Esito della richiesta. I campi seguenti possono non essere presenti in caso di esito negativo
cn
uint
Identificativo concessionario
anno
ushort
Anno richiesto
mese
uchar
Mese
giorno
uchar
Giorno
n_ticket
uchar
Numero di biglietti che seguono
Dettaglio Biglietto
id_ticket
bit[48]
Identificativo del biglietto
prezzo
uint
Prezzo del biglietto
Importo_vinc
uint
Importo di vincita
importo_rimb
uint
Importo rimborso
Dati relativi alla emissione del biglietto
FSC
ushort
Fornitore del Servizio di Connettività
conc
uint
Concessionario
pvend
uint
Punto vendita
tag
ushort
Terminale
dataora_ven
datetime_utc
Data e Ora della vendita
attributi estesi:
- IP_RISP
Facoltativo
codici di ritorno:
- 1024 - Richiesta ok seguono i dati;
- 1516 - Non ci sono dati per la richiesta fatta;
- 1513 - Il concessionario non appartiene al FSC;
- 1518 - I dati della richiesta non sono congruenti;
- 1530 - Dati non elaborati.
7.3 - Elenco biglietti telematici non riscossi 2
Client abilitati:
FSC,0,0,TAG
header.id_servizio
9200
header.id_messaggio
3
Descrizione:
Questo messaggio consente di ottenere dal TN l'elenco parziale o totale dei biglietti telematici non riscossi.
Non è consentito richiedere più di 180 biglietti alla volta.
Richiesta:
body:
Campo
Tipo
Descrizione
cn
uint
Identificativo concessionario
anno
ushort
Anno richiesto
mese
uchar
Mese richiesto
giorno
uchar
Giorno richiesto
tck_iniziale
uint
Posizione del biglietto iniziale nell’elenco richiesto (da 1 a 4294967295)
tck_finale
uint
Posizione del biglietto finale nell’elenco richiesto (da 1 a 4294967295).
Attributi estesi:
- IP_RISP
Facoltativo
Risposta:
body:
Campo
Tipo
Descrizione
esito
ret_code
Esito della richiesta. I campi seguenti possono non essere presenti in caso di esito negativo
cn
uint
Identificativo concessionario
anno
ushort
Anno richiesto
mese
uchar
Mese richiesto
giorno
uchar
Giorno richiesto
n_ticket
uchar
Numero di biglietti che seguono
Biglietti
id_ticket
bit[48]
Identificativo del biglietto
stato
uchar
Stato del biglietto (vedi tabella stati del biglietto)
id_rete
uchar
Identificativo di rete di apertura del conto(vedere Tabella Codici Rete)
id_cn
uint
Identificativo concessionario di apertura del conto
conto
uchar
Tipo conto (vedere Tabella Tipo Conto)
string
Numero del conto di gioco
importo
uint
Importo totale da pagare e/o rimborsare
attributi estesi:
- IP_RISP
Facoltativo
codici di ritorno:
- 1024 - Richiesta ok seguono i dati;
- 1516 - Non ci sono dati per la richiesta fatta;
- 1513 - Il concessionario non appartiene al FSC;
- 1518 - I dati della richiesta non sono congruenti;
- 1530 - Dati non elaborati.
7.4 - Totale biglietti giornaliero
Client abilitati:
FSC,0,0,TAG
header.id_servizio
9200
header.id_messaggio
4
Descrizione:
Questo messaggio consente di ottenere dal TN il totale dei biglietti emessi nella giornata per uno specifico concessionario.
Richiesta:
body:
Campo
Tipo
Descrizione
cn
uint
Identificativo concessionario
anno
ushort
Anno richiesto
mese
uchar
Mese di richiesto
giorno
uchar
Giorno richiesto
Attributi estesi:
- IP_RISP
Facoltativo
Risposta:
body:
Campo
Tipo
Descrizione
esito
ret_code
Esito della richiesta. I campi seguenti possono non essere presenti in caso di esito negativo
cn
uint
Identificativo concessionario
anno
ushort
Anno richiesto
mese
uchar
Mese richiesto
giorno
uchar
Giorno richiesto
n_ticket
uint
Numero di biglietti totali emessi
attributi estesi:
- IP_RISP
Facoltativo
codici di ritorno:
- 1024 - Richiesta ok seguono i dati;
- 1516 - Non ci sono dati per la richiesta fatta;
- 1513 - Il concessionario non appartiene al FSC;
- 1530 - Dati non elaborati.
8. Gestione firma digitale
Questo servizio consente la gestione delle chiavi per la firma digitale dei messaggi.
8.1 - Richiesta scambio chiavi pubbliche
Client abilitati:
FSC,0,0,TAG
header.id_servizio
9300
header.id_messaggio
1
Descrizione:
Questa funzione consente al FSC di comunicare al TN la chiave pubblica con cui riconoscere la propria firma e ricevere in risposta la chiave pubblica del TN. Le chiavi pubbliche scambiate sono in formato PEM.
Richiesta:
body:
Campo
Tipo
Descrizione
chiave_pub
Istring
Chiave pubblica del CN
attributi estesi:
- IP_RISP
Facoltativo
- FIRMA_DIG01
Obbligatorio
Risposta:
body:
Campo
Tipo
Descrizione
esito
ret_code
Esito della richiesta. I campi seguenti possono non essere presenti in caso di esito negativo
chiave_pub
Istring
Chiave pubblica del TN
attributi estesi:
- IP_RISP
Facoltativo
codici di ritorno:
- 1024 - Scambio di chiavi avvenuta;
- 1520 - Firma non valida;
- 1521- Richiesta scambio chiavi pubbliche nella quale non sono presenti gli attributi estesi obbligatori (FIRMA_DIG01).
9. Attributi estesi
Gli attributi estesi consentono di estendere le informazioni trasportate da un certo messaggio senza dover modificare il formato del body.
L'entità destinataria di un certo messaggio può facilmente determinare se nel messaggio sono presenti e dove degli attributi estesi semplicemente analizzando i campi lung_ae e lung_body dell'header.
Gli attributi estesi consistono di una struttura formata dai seguenti campi:
Campo
Tipo
Descrizione
id
ushort
Numero identificativo dell'attributo esteso. Ogni tipo di attributo esteso ha un numero identificativo diverso ed univocamente assegnato nell'ambito del protocollo
lung
uchar
Lunghezza del campo seguente (da 0 a 255). Il valore 0 indica che il campo seguente non è presente
dati
uchar[lung]
Dati dell'attributo esteso. A questo campo verrà dato uno o più nomi a secondo dell'attributo esteso
Per ogni attributo esteso viene, inoltre, specificata una sigla mnemonica che facilita l'identificazione dell'attributo nel presente documento.
Di seguito sono riportati i formati ed i numeri identificativi degli attributi estesi del protocollo.
9.1 - TIME_STAMP_UTC (1200) DATA ORA UTC
Questo attributo esteso è inviato da un server al client nel messaggio di risposta di tutte quelle transazioni in cui il client ha necessità di conoscere l'esatto momento in cui il server ha processato la richiesta.
Questo timestamp è specificato nel Time Zone UTC (Universal Time Coordinated).
Il formato dell'attributo esteso è il seguente:
Mnemonico:
TIME_STAMP_UTC
Campo
Valore
id
1200
lung
7
dati
anno
ushort
Anno
mese
uchar
Mese (da 1 a 12)
giorno
uchar
Giorno (da 1 a 31)
ora
uchar
Ora (da 0 a 23)
min
uchar
Minuto (da 0 a 59)
sec
uchar
Secondo (da 0 a 59)
9.2 - ID_GIOCATA (1029) Identificativo giocata
Questo attributo esteso è inviato dal TAG al TN nei messaggi di vendita come identificativo univoco della giocata.
Mnemonico:
ID_GIOCATA
Campo
Valore
Id
1029
lung
8
dati
anno
ushort
Anno
giorno
ushort
Progressivo nell'anno
id
uint
Identificativo univoco della giocata, nella giornata, per TAG
9.3 - IP_RISP (1036) Indirizzo di destinazione della risposta
Questo attributo esteso è inviato dai FSC al TN insieme ad una richiesta per segnalare che si intende ricevere la risposta all'indirizzo IP e porta UDP specificati.
Il formato dell'attributo esteso è il seguente:
Mnemonico:
IP_RISP
Campo
Valore
Id
1036
lung
6
dati
port
ushort
Porta UDP dove si intende ricevere la risposta
addr
uint
Indirizzo IP dove si intende ricevere la risposta
9.4 - FIRMA_DIG01 (1093) Firma digitale
Questo attributo esteso è inviato come firma del messaggio.
Definizione algoritmo:
- hashing MD5;
- Chiave Pubblica/Privata RSA 256 bit con un padding di tipo RSA_PKCS1_PADDING.
Mnemonico:
FIRMA_DIG01
Campo
Valore
Id
1093
lung
44
dati
firma
uchar[44]
Firma digitale. Codificato base 64
9.5 - CONTO_2 (1125) Nuovo Conto per il gioco a distanza
Questo attributo esteso è inviato per specificare un conto di gioco a distanza indicando anche il codice identificativo del concessionario presso il quale il conto è attivo.
Il formato dell'attributo esteso è il seguente:
Mnemonico:
CONTO_2
Campo
Valore
Id
1025
lung
Dipende dai dati
dati
Id_rete
uchar
Identificativo di rete(vedere Tabella Codici Rete)
Id_cn
uint
Identificativo concessionario
conto
uchar
Tipo conto (vedere Tabella Tipo Conto)
string
Numero del conto di gioco
Nessun commento:
Posta un commento