GESACC V.2.2.

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

GENERAL DESCRIPTION

Zucchetti’s Stadium Access Control System is a hardware and software solution entirely
developed and implemented by Zucchetti S.p.A.

The system is based on a LAN/WLAN architecture and an on-site centralized SW that manages
in real-time the various fully integrated control devices.

Zucchetti Access Control SW

Hand-held Devices Gate Devices

Ethernet / WiFi

LAN / WLAN

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 1 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

TICKETING INTERFACE SCHEME

Application Server
Ticketing System

GuardianW
Web Services

Internet

Access Control DB

DB Server

LAN / WLAN

The Guardian-W is a software module belonging to the suite of Zucchetti SW 'Guardian' that
provides the Web Services needed to feed and to get data from the Access Control DB.

In older configurations, the Ticketing Systems provide the data by an own client that read and
write into the interface DB of the access control. Therefore they must have on the LAN of the
access control a suitable own HW/SW to do the job.

With the Guardian-W module, the Ticketing System has a simple and effective way to exchanging
data with the Access Control System regardless the localization of the box offices and the venue.

Each venue has its own Access Control SW installation that runs the devices of access control
and the local DB of the allowed tickets.

The Guardian-W supplies Services to insert data into the Access Control DB like:

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 2 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

- define Ticketing Sections to enable different behaviours

- create records of Performances
- insert ticket records allowed, or not allowed, to the defined performances
- change the status of a subset of tickets (voided, stolen and so on)

Each Service has a ‘get’ method to get back the information about the previously recorded data.

Note that, even though it is recommended to have separated servers for the different functions,
for most common situations where there are a modest number of control points and attendees,
the Application Server, the DB Server and the Web Server could be the same machine.

To exchange data via Web Services with the Guardian-W, the box-office SW must be provided
of a valid account.

Each account on the Guardian-W module has the following attributes that must be used within
the Web Services:
- user name
- password
- one o more Ticketing System Codes

All these data will be send through the Web Services that will verify the compliance with the
stored setting for the account. Each account, identified by its user-id/password, is allowed to
send and get data just for its own Ticketing System Codes. This lets to handle more Ticketing
Systems to feeding data on the same venue if needed.

There are some dedicated Services with administrator rights to create and handle accounts, but
there is a more user friendly way, by using the integrated features of the Guardian-S module:
the user accounts and other configuration stuff of the Guardian-W unit can be defined and
configured via a web based interface of the Guardian-S, the main user interface module of the
Guardian SW suite.

The Guardian-S module provides also a set of web-based features to examine via browser a set
of reports about the expected attendees and the number of attendances, some of these suitable
for mobile devices.

Another features inside the Guardian-S module is the ability to using the Web Services of the
Guardian-W simply by uploading files in .CSV format via browser. This facility is useful for that
Ticketing Systems that occasionally have to send its issued tickets to the access control system
(e.g. for guests supporters), and they have not implemented the required web services calls.

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 3 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

TICKETING SERVICE SPECIFICATIONS

The Guardian-W Services implement an exchanging data-format compliant with the public
security rules of the Italian Ministry of Internal (Home Office) and in compliance with the
regulations of the Revenue Agency / SIAE of Italy.
These rules expect special data to be provided. The most relevant data are the Unique
Identification Codes of the tickets provided by the ad hoc SmarCard issued by the Italian SIAE.

On other countries or for performance no subject to these regulations the data and its coherency
rules are just a sub-set of the Italian version.

Customarily to signal a ‘no Italian SIAE compliant’ behaviour and switch the web services to
handle less restrictive rules, the web service methods must be called without the fields related
to the Smart Card (‘SmartCardCode’ and ‘SmartCardProg’) or with these fields set to blank.
In this case, the code printed on the ticket, and read by the control devices, will be used as the
unique identifier of the ticket itself for the allowed performances.

In following definitions we have been pointed out the differences in handling SIAE-compliant and
no-SIAE-compliant data.

Many of SIAE-compliant fields have no meaning for no-SIAE-compliant systems that can not
worry about these fields leaving them blanks.
The web services will provide default values for some omitted data that cannot be empty, so
must not be source of confusing to get valid values for fields sent as empty.

SERVICE PROTOCOLS

The URLs of the pages of Guardian-W web services are in the following format

http://<host>[:<port>]/GuardianW/<service>

where

<host> is the public/local address of the machine running the Guardian-W

<port> is the optional port to address the Guardian-W services
<service> is the requie service

1 WSDL

http://<host>[:<port>]/GuardianW/wsb?wsdl

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 4 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

2 SOAP

Endpoint /GuardianW/wsb/soap/

ContentType text/xml; charset=utf-8

SOAPAction http://www.zucchetti.it/GuardianW/wsb/<service_name>

2.1 Request sample - GetPerformances service

POST http://localhost:8001/GuardianW/wsb/soap HTTP/1.1

Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: "http://www.zucchetti.it/GuardianW/wsb/GetPerformances"
Content-Length: 1077
Host: localhost:8001
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:guar="http://www.zucchetti.it/GuardianW/"
xmlns:zuc="http://schemas.datacontract.org/2004/07/Zucchetti.Guardian.WebServices.Data">
<soapenv:Header/>
<soapenv:Body>
<guar:GetPerformances>
<guar:auth>
<zuc:UserName>user</zuc:UserName>
<zuc:Password>password</zuc:Password>
</guar:auth>
<guar:TicketingCode></guar:TicketingCode>
<guar:VenueCode></guar:VenueCode>
<guar:PerformanceDate></guar:PerformanceDate>
<guar:PerformanceTime></guar:PerformanceTime>
<guar:OrganizerCode></guar:OrganizerCode>
<guar:PerformanceStartDate></guar:PerformanceStartDate>
<guar:PerformanceStartTime></guar:PerformanceStartTime>
</guar:GetPerformances>
</soapenv:Body>
</soapenv:Envelope>

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 5 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

3 SOAP 1.2

Endpoint /GuardianW/wsb/soap12/

ContentType application/soap+xml; charset=utf-8;

action=”http://www.zucchetti.it/GuardianW/wsb/<service_name>”

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 6 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

3.1 Request sample - SetTickets service with required fields only

POST http://localhost:8001/GuardianW/wsb/soap12 HTTP/1.1

Accept-Encoding: gzip,deflate
Content-Type: application/soap+xml;charset=UTF-
8;action="http://www.zucchetti.it/GuardianW/wsb/SetTickets"
Content-Length: 3357
Host: localhost:8001
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:guar="http://www.zucchetti.it/GuardianW/"
xmlns:zuc="http://schemas.datacontract.org/2004/07/Zucchetti.Guardian.WebServices.Data">
<soap:Header/>
<soap:Body>
<guar:SetTickets>
<guar:auth>
<zuc:UserName>user</zuc:UserName>
<zuc:Password>password</zuc:Password>
</guar:auth>
<guar:tickets>
<zuc:Ticket>
<zuc:VenueCode>0061540214108</zuc:VenueCode>
<zuc:PerformanceDate>20140708</zuc:PerformanceDate>
<zuc:PerformanceTime>1500</zuc:PerformanceTime>
<zuc:TicketCode>19269503-1</zuc:TicketCode>
<zuc:TicketingCode>00000487</zuc:TicketingCode>
<zuc:TotalPrice>3510</zuc:TotalPrice>
<zuc:TicketStatus>VT</zuc:TicketStatus>
</zuc:Ticket>
</guar:tickets>
</guar:SetTickets>
</soap:Body>
</soap:Envelope>

4 SERVICES

Available services:

• SetPerformances
• GetPerformances

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 7 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

• DelPerformance
• SetSections
• GetSections
• DelSections
• SetTickets
• GetTickets

See Appendixes for data type and format descriptions.

4.1 SetPerformances

Adds or modifies one or more performances for the specified Ticketing System Code.
Each Performance is uniquely identified by the so-called ‘performance-id’, made up by the code
of the venue and the date/time of the performance.
For the same performance there can be more of one ticketing system for issuing tickets, in this
case the first three fields of performance-id will be the same and each ticketing system will refer
to their data identified by the TicketingCode field. Then the performance-id becomes:

VenueCode the code of the venue

PerformanceDate the original day of the performance

PerformanceTime the original time of day of the performance

TicketingCode the Ticketing System code

Note that each ticket is joined to a performance, then they must be sent after the creation of
their performance.

The fields PerformanceDate and PerformanceTime stand for the original date and time of the
performance and must never be changed, unless in case of error, because they are part of the
performance key. There are other fields (PerformanceStartDate and PerformanceStartTime) to
change in case of postponements or advances that define the real day of the performance.

4.1.1 SetPerformances - Input

Required
Occ. Type Note &Format
SIAE STD
Auth Y Y 1 A Auth Class Tag
Auth.UserName Y Y 1 s(80) Service Account
Service Account
Auth.Password Y Y 1 s(80)
Password

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 8 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

Required
Occ. Type Note &Format
SIAE STD
Insert-Only/Update
Overwrite N N 1 b
flag
Performance Y Y 1:n P Performance Class Tag
Performance.VenueCode Y Y 1 s(13) key field

Performance.PerformanceDate Y Y 1 s(8) key field -

yyyyMMdd
Performance.PerformanceTime Y Y 1 s(4) key field - HHmm
Performance.TicketingCode Y Y 1 s(8) key field
Performance.OrganizerCode Y N 1 s(16) SIAE compliant
Performance.OrganizerDescr Y N 1 s(30) SIAE compliant
Performance.OrganizerType N N 1 s(1) SIAE compliant
Performance.TicketingVatNumber Y N 1 s(16) SIAE compliant
Performance.PerformanceIntr Y N 1 s(1) SIAE compliant
Performance.PerformancePercIntr Y N 1 i SIAE compliant
Performance.VenueDescr Y Y 1 s(30)
Performance.PerformanceKind Y N 1 s(2) SIAE compliant
Performance.PerformanceDescr N N 1 s(40)
Performance.PerformanceAuthor N N 1 s(30) SIAE compliant
Performance.Performer N N 1 s(40) SIAE compliant
Performance.Country N N 1 s(4) SIAE compliant
Performance.PerformanceWorkNum N N 1 i SIAE compliant
Performance.TicketingTrad N N 1 s(1) SIAE compliant
Performance.PerformanceStartDate N N 1 s(8) yyyyMMdd
Performance.PerformanceStartTime N N 1 s(6) HHmmss
Performance.PerformanceEndDate N N 1 s(8) yyyyMMdd
Performance.PerformanceEndTime N N 1 s(6) HHmmss
Performance.Weekdays week days for
N N 1 i
repeated performance
Performance.BindingTime binding performance
N N 1 b
start/end datetime
Performance.ExtInfo N N 1 s(250) internal use
Performance.MandatoryHolderName Y N 1 b SIAE compliant

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 9 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.1.2 SetPerformances – Input Fields

4.1.2.1 Auth.UserName
the user name released by the web services administrator

4.1.2.2 Auth.Password
the account password released by the web services administrator

4.1.2.3 Overwrite
if FALSE, only insertions of new performances are allowed.
Set this flag to TRUE to update existing performances and insert new ones

4.1.2.4 Performance.VenueCode
key field - the agreed code of the Venue as a string of max 13 alphanumeric chars

4.1.2.5 Performance.PerformanceDate
key field - the original Performance date as a string of 8 char in the format ‘yyyyMMdd’

4.1.2.6 Performance.PerformanceTime
key field - the original Performance time as a string of 4 char in the format ‘HHmm’

4.1.2.7 Performance.TicketingCode
key field – the agreed code of the Ticketing System as a string of 8 alphanumeric chars

4.1.2.8 Performance.OrganizerCode
SIAE compliant field
TAX/VAT code of the performance organizer as a string of 16 alphanumeric chars
the default value for no-SIAE-compliant data is all zeroes

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 10 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.1.2.9 Performance.OrganizerDescr
SIAE compliant field
name / company of performance organizer as a string of max. 40 chars.
the default value for no-SIAE-compliant data is ‘Organizer’

4.1.2.10 Performance.OrganizerType
SIAE compliant field
Type of performance organizer as string of one char
the default value for no-SIAE-compliant data is blank

4.1.2.11 Performance.TicketingVatNumber
SIAE compliant field
TAX/VAT code of the Ticketing system as an alphanumeric string of 16 chars.
the default value for no-SIAE-compliant data is all zeroes

4.1.2.12 Performance.PerformanceIntr
SIAE compliant field string of one char
performance type: [S]pettacolo / [I]ntrattenimento / s[P]ettacolo con tit.digitali /
i[N]trattenimento con tit.digitali.
The default value for no-SIAE-compliant data is ‘S’

4.1.2.13 Performance.PerformancePercIntr
SIAE compliant field
performance entertainment percentage as integer
the default value for no-SIAE-compliant data is 0

4.1.2.14 Performance.VenueDescr
The name/description of the venue as a string of max 30 chars

4.1.2.15 Performance.PerformanceKind
SIAE compliant field
performance kind, a string of two chars as per SIAE reference codes.
The default value for no-SIAE-compliant data is all zeroes

4.1.2.16 Performance.PerformanceDescr
name or description of the performance a string of max 40 chars

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 11 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.1.2.17 Performance.PerformanceAuthor
SIAE compliant field
name of the performance author a string of max 30 chars
the default value for no-SIAE-compliant data is blank

4.1.2.18 Performance.Performer
SIAE compliant field
name of the performance performer a string of max 40 chars
the default value for no-SIAE-compliant data is blank

4.1.2.19 Performance.Country
SIAE compliant field
code of country of the performance author or performer a string of 4 chars
the default value for no-SIAE-compliant data is blank

4.1.2.20 Performance.PerformanceWorkNum
SIAE compliant field
Number of pieces of the performance as integer
the default value for no-SIAE-compliant data 1

4.1.2.21 Performance.TicketingTrad
SIAE compliant field
No digital tickets at all in the current performance a string of one char
the default value for no-SIAE-compliant data is blank

4.1.2.22 Performance.PerformanceStartDate
The real day of the performance as a 8 char string in the format ‘yyyyMMdd’
This date can differ from the original, and immutable, date (e.g for the postponements)
The default value is blank, that means the same value of the PerformanceDate field

4.1.2.23 Performance.PerformanceStartTime
The time of the performance day as a 6 char string in the format ‘HHmmss’
This time can differ from the original, and immutable, date/time
The default value is blank, that means the same value of the PerformanceTime field

4.1.2.24 Performance.PerformanceEndDate
The day when the performance will end as a 8 char string in the format ‘yyyyMMdd’
This date can differ from the original, and immutable, date (e.g for the postponements)
The default value is blank, that means the same value of the PerformanceDate field

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 12 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.1.2.25 Performance.PerformanceEndTime
The time when the performance will end as a 6 char string in the format ‘HHmmss’
This date can differ from the original, and immutable, date/time
The default value is blank, that means the same value of the PerformanceTime field

4.1.2.26 Performance.WeekDays
Weekdays enabled for repeated performance (not to be used in case of SIAE-compliant
performances).
Sunday=1, Monday=2, Tuesday=4, Wednesday=8, Thursday=16, Friday=32, Saturday=64
e.g. Saturday + Sunday=64 + 1=65

4.1.2.27 Performance.BindingTime
The Performance.StartDate, Performance.StartTime and Performance.EndDate,
Performance.EndTime are binding: no access allowed before StartDate,StartTime or after
EndDate,EndTime.
If “Performance.BindingTime=0”, Performance.StartTime and Performance.EndTime does not
affect access validity.

4.1.2.28 Performance.MandatoryHolderName
SIAE compliant field.
Set “Performance.MandatoryHolderName=true” in case of mandatory ticket holder name (as
per Prot.223774/2019 27/06/2019 Italian Revenue Agency regulation): ticket holder First
Name and Last Name must be specified for each ticket associated to this performance.

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 13 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.1.3 SetPerformances - Output

Occ. Type Note/Format

SetPerformancesResult 1 i Number of updated items

SetPerformanceFail 1:n SPF Error Class Tag
SetPerformanceFail.TicketingCode 1 s(8) the key-value of the record on
error
SetPerformanceFail.VenueCode 1 s(13) the key-value of the record on
error
SetPerformanceFail.PerformanceDate 1 s(8) the key-value of the record on
error
SetPerformanceFail.PerformanceTime 1 s(4) the key-value of the record on
error
SetPerformanceFail.Index 1 i Index of failed record
SetPerformanceFail.FailCode 1 i Code Error
SetPerformanceFail.FailDescr 1 s Description of the error
SetPerformanceFail.FailReason 1 s Reason of the error

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 14 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.2 GetPerformances

Fetch all performances that match the given conditions (if any).

4.2.1 GetPerformances - Input

Req. Occ. Type Note/Format

Auth Y 1 A Auth Class Tag

Auth.UserName Y 1 s(80) Service Account

Auth.Password Y 1 s(80) Service Account Password

VenueCode N 0:1 s(13) if not blank filters on value

PerformanceDate N 0:1 s(8) if not blank filters on value

PerformanceTime N 0:1 s(4) if not blank filters on value

TicketingCode N 0:1 s(8) if not blank filters on value

OrganizerCode N 0:1 s(16) if not blank filters on value

PerformanceStartDate N 0:1 s(8) if not blank filters on value
PerformanceStartTime N 0:1 s(6) if not blank filters on value
PagingKeyIn N 0:1 PGK PagingKey Class Tag
PagingKeyIn.PagingKey N 1 s(100) Paging key
PagingKeyIn.MaxRecords N 1 i Max records per page

4.2.2 GetPerformances – Input Fields

See the SetPerformances service field description for the common fields like TicketingCode,
PerformanceStartDate and so on.

4.2.2.1 PagingKeyIn.PagingKey
It’s an alphanumeric string of max. 100 chars to be provided to get the next page of records
following the last one according to the filters in being.

The value is returned by the output of the last GetPerformances call and should be supplied
as it is. On the first call this field must be blank.

4.2.2.2 PagingKeyIn. MaxRecords

It’s an integer number to define the max number of records returned by each service call.
If leaved blank the default value is 100 records per page.

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 15 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.2.3 GetPerformances - Output

Occ. Type Note/Format

GetPerformancesResult 1 i Number of fetched items

Performance 0:n P Performance Class Tag
Performance.VenueCode 1 s(13) see SetPerformances fields
Performance.PerformanceDate 1 s(8) see SetPerformances fields
Performance.PerformanceTime 1 s(4) see SetPerformances fields
Performance.TicketingCode 1 s(8) see SetPerformances fields
Performance.OrganizerCode 1 s(16) see SetPerformances fields
Performance.OrganizerDescr 1 s(30) see SetPerformances fields
Performance.OrganizerType 1 s(1) see SetPerformances fields
Performance.TicketingVatNumber 1 s(16) see SetPerformances fields
Performance.PerformanceIntr 1 s(1) see SetPerformances fields
Performance.PerformancePercIntr 1 i see SetPerformances fields
Performance.VenueDescr 1 s(30) see SetPerformances fields
Performance.PerformanceKind 1 s(2) see SetPerformances fields
Performance.PerformanceDescr 1 s(40) see SetPerformances fields
Performance.PerformanceAuthor 1 s(30) see SetPerformances fields
Performance.Performer 1 s(40) see SetPerformances fields
Performance.Country 1 s(4) see SetPerformances fields
Performance.PerformanceWorkNum 1 i see SetPerformances fields
Performance.TicketingTrad 1 s(1) see SetPerformances fields
Performance.PerformanceStartDate 1 s(8) see SetPerformances fields
Performance.PerformanceStartTime 1 s(6) see SetPerformances fields
Performance.PerformanceEndDate 1 s(8) see SetPerformances fields
Performance.PerformanceEndTime 1 s(6) see SetPerformances fields
Performance.Weekdays 1 i see SetPerformances fields
Performance.BindingTime 1 b see SetPerformances fields
Performance.ExtInfo 1 see SetPerformances fields
Performance.MandatoryHolderName 1 b see SetPerformances fields

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 16 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.3 DelPerformance

Delete a performance and all associated tickets.

4.3.1 DelPerformance - Input

Req. Occ. Type Note/Format

Auth Y 1 A Auth Class Tag

Auth.UserName Y 1 s(80) Service Account
Auth.Password Y 1 s(80) Service Account Password
VenueCode Y 1 s(13) key-field of the item to seek
PerformanceDate Y 1 s(8) key-field of the item to seek
PerformanceTime Y 1 s(4) key-field of the item to seek
TicketingCode Y 1 s(8) key-field of the item to seek

4.3.2 DelPerformance - Output

Occ. Type Note/Format

DelPerformanceResult 1 i Number of deleted items

DelPerformancesFail 1:n DPF Error Class Tag
DelPerformancesFail.VenueCode 1 s(13) the key-value of the record
on error
DelPerformancesFail.PerformanceDate 1 s(8) the key-value of the record
on error
DelPerformancesFail.PerformanceTime 1 s(4) the key-value of the record
on error
DelPerformancesFail.TicketingCode 1 s(8) the key-value of the record
on error
DelPerformancesFail.Index 1 i Index of failed record
DelPerformancesFail.FailCode 1 i Code Error
DelPerformancesFail.FailDescr 1 s Description of the error
DelPerformancesFail.FailReason 1 s Reason of the error

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 17 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.4 SetSections

Adds or modifies one or more Sections that grouping a set of seats/places with common
behaviour.
Usually the Ticketing System knows where people have to seat, while the Access Control have
to know where people can pass. Then Sections (or Ticketing Areas) are used to join the positions
of the seats with the rules (policies) to pass at the gates. Sections represent a complementary
table to setup the Access Control behaviour.
Each Section is identified by a unique code, and can refer to a parent Section that contains it. If
the parent is not defined the Section will be a child of the root section.
The code-id of Sections is an any string of 32 max. chars according to the Ticketing System
encoding
Note: at the moment all Sections refer to all defined performances, Ticketing Systems and
venues. The web services already provides the fields to distinguish between Section codes
defined from different Ticketing Systems, venues and performances, that will be supported soon.

4.4.1 SetSections- Input

Req. Occ. Type Note/Format

Auth Y 1 A Auth Class Tag

Auth.UserName Y 1 s(80) Service Account
Auth.Password Y 1 s(80) Service Account Password
Overwrite N 1 b Insert-Only/Update flag
Section Y 1:n SE Section Class Tag
Section.VenueCode N 1 s(13) Future use - key field
Section.PerformanceDate N 1 s(8) Future use - key field
Section.PerformanceTime N 1 s(4) Future use - key field
Section.TicketingCode N 1 s(8) Future use - key field
Section.SectionId Y 1 s(32) key field
Section.SectionDescr N 1 s(50)
Section.SectionParent N 1 s(32)

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 18 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.4.2 SetSections – Input Fields

4.4.2.1 Auth.UserName
the user name released by the web services administrator

4.4.2.2 Auth.Password
the account password released by the web services administrator

4.4.2.3 Overwrite
if FALSE, only insertions of new sections are allowed.
Set this flag to TRUE to update existing sections and insert new ones

4.4.2.4 Section.VenueCode
Performance-id Venue field – private section code of the suggested performance
string of max 13 alphanumeric chars

4.4.2.5 Section.PerformanceDate
Performance-id date field– private section code of the suggested performance
string of 8 char in the format ‘yyyyMMdd’

4.4.2.6 Section.PerformanceTime
Performance-id time field – private section code of the suggested performance
string of 4 char in the format ‘HHmm’

4.4.2.7 Section.TicketingCode
Performance-id Ticketing field– private section code of the suggested performance
string of 8 alphanumeric chars

4.4.2.8 Section.SectionId
key field – identify the section on the internal table
string of max. 32 alphanumeric chars

4.4.2.9 Section.SectionDescr
The section description - string of max. 50 alphanumeric chars

4.4.2.10 Section.SectionParent
optional section code identifying the parent of the current section
string of max. 32 alphanumeric chars

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 19 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.4.3 SetSections - Output

Occ. Type Note/Format

SetSectionsResult 1 i Number of updated items

SetSectionsFail 1:n SSF Error Class Tag
SetSectionsFail.VenueCode 1 s(13) the performance key-value of
the record on error
SetSectionsFail.PerformanceDate 1 s(8) the performance key-value of
the record on error
SetSectionsFail.PerformanceTime 1 s(4) the performance key-value of
the record on error
SetSectionsFail.TicketingCode 1 s(8) the performance key-value of
the record on error
SetSectionsFail.SectionId 1 s(32) the Section key-value of the
record on error
SetSectionsFail.Index 1 i Index of failed record
SetSectionsFail.FailCode 1 i Code Error
SetSectionsFail.FailDescr 1 s Description of the error
SetSectionsFail.FailReason 1 s Reason of the error

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 20 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.5 GetSections

Returns all sections matching the given conditions (if any).

4.5.1 GetSections - Input

Req. Occ. Type Note/Format

Auth Y 1 A Auth Class Tag

Auth.UserName Y 1 s(80) Service Account
Auth.Password Y 1 s(80) Service Account Password
VenueCode N 1 s(13) Future use
PerformanceDate N 1 s(8) Future use
PerformanceTime N 1 s(4) Future use
TicketingCode N 1 s(8) Future use
SectionIds N 0:n s(12) if not blank filters on values

4.5.2 GetSections - Output

Occ. Type Note/Format

GetSectionsResult 1 i Number of fetched items

Section 0:n SE Sections Class Tag
Section.VenueCode 1 s(13) see SetSections fields
Section.PerformanceDate 1 s(8) see SetSections fields
Section.PerformanceTime 1 s(4) see SetSections fields
Section.SectionId 1 s(32) see SetSections fields
Section.TicketingCode 1 s(8) see SetSections fields
Section.SectionDescr 1 s(50) see SetSections fields
Section.SectionParent 1 s(32) see SetSections fields

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 21 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.6 DelSections

Delete a performance and all associated tickets.

4.6.1 DelSections - Input

Req. Occ. Type Note/Format

Auth Y 1 A Auth Class Tag

Auth.UserName Y 1 s(80) Service Account
Auth.Password Y 1 s(80) Service Account Password
VenueCode N 1 s(13) Future use
PerformanceDate N 1 s(8) Future use
PerformanceTime N 1 s(4) Future use
TicketingCode N 1 s(8) Future use
SectionId N 1 s(32) The section code

4.6.2 DelSections - Output

Occ. Type Note/Format

DelSectionResult 1 i Number of deleted items

DelSectionsFail 1:n DPF Error Class Tag
DelSectionsFail.VenueCode 1 s(8) the key-value of the record
on error
DelSectionsFail.PerformanceDate 1 s(4) the key-value of the record
on error
DelSectionsFail.PerformanceTime 1 s(8) the key-value of the record
on error
DelSectionsFail.TicketingCode 1 s(13) the key-value of the record
on error
DelSectionsFail.SectionId 1 i the key-value of the record
on error
DelSectionsFail.Index 1 i Index of failed record
DelSectionsFail.FailCode 1 s Code Error
DelSectionsFail.FailDescr 1 s Description of the error
DelSectionsFail.FailReason 1 S Reason of the error

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 22 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.7 SetTickets

Adds or modifies one or more Ticket rows for the specified performance. It’s the main service to
feed data to the DB.
Remember the same valid ticket cannot appear more than once for the same performance and
that for the same performance, there may be more ticketing systems issuing tickets.
Then each ticket is uniquely identified by the so-called ‘ticket-id’, made up by the set of fields
according to the SIAE/NO-SIAE compliance:

Ticket-id fields for SIAE-compliant records

VenueCode
PerformanceDate
Performance-ID
PerformanceTime
TicketingCode SIAE-compliant mode
Ticket SmartCardCode

Ticket SmartCardProg

Ticket-id fields for No SIAE-compliant records

VenueCode
PerformanceDate
Performance-ID
PerformanceTime No SIAE-compliant mode
TicketingCode
Ticket Code

Note that on SIAE-compliant mode the Ticket Code (e.g. the barcode or whatever is read from
the ticket) does not occur on the ticket-id. Instead it’s a part of the ticket-id on no-SAIE-
compliant mode.
The Ticket SmartCardCode and SmartCardProg are used to distinguish from a SIAE/no-SIAE
compliant record: they must be provided only for SIAE-compliant records and in this case they
are two mandatory parts of the record key.
There are several other fields typical of the SIAE-compliance mode: all these fields are optional
for no-SIAE-compliant records, but if they are provided they must be coherent and they will be
used for displaying data on the access control system.
The SetTickets performs insertions of new records and updates of existing ones.

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 23 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.7.1 SetTickets - Input

Required
Occ. Type Note &Format
SIAE STD
Auth Y Y 1 A Auth Class Tag
Auth.UserName Y Y 1 s(80) Service Account
Auth.Password Y Y 1 s(80) Service Account Password
Ticket Y Y 1:n T Ticket Class Tag
Ticket.VenueCode Y Y 1 s(13) key field
Ticket.PerformanceDate Y Y 1 s(8) key field
Ticket.PerformanceTime Y Y 1 s(4) key field
Ticket.TicketingCode Y Y 1 s(8) key field
Ticket.SmartCardCode Y N 1 s(8) key field (**)
Ticket.SmartCardProg Y N 1 s(32) key field (**)
Ticket.TicketCode Y Y 1 s(32) key field (*)
Ticket.TicketCodeAlt N N 1 s(32)
Ticket.OrdineDiPosto Y N 1 s(2) OrdinePosto Table
‘UN’ if blank
Ticket.OrdineDiPostoCapacity N N 1 i
Ticket.RowSeat N N 1 s(6)
Ticket.SectionId N N 1 s(32) OrdinePosto if blank
Ticket.SectionParent N N 1 s(32)
Ticket.SmartCardCheckCode Y N 1 s(16)
Ticket.TicketIssueDate Y N 1 s(8) yyyyMMdd
“19000101” if blank
Ticket.TicketIssueTime Y N 1 s(4) HHmm - “0000” if blank
Ticket.TicketType Y N 1 s(2) Ticket Type Table
“I1” if blank
Ticket.TicketTypeDescr N N 1 s(32)
Ticket.TotalPrice Y N 1 i
Ticket.SeasonOrganizerCode N N 1 s(16)
Ticket.SeasonCode N N 1 s(8)
Ticket.SeasonProg N N 1 s(8)
Ticket.SeasonPerformancesNum N N 1 i
Ticket.VoidedDate N N 1 s(8) yyyyMMdd
Ticket.VoidedTime N N 1 s(4) HHmm
Ticket.VoidedSmartCardCode N N 1 s(8)

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 24 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

Required
Occ. Type Note &Format
SIAE STD
Ticket.VoidedSmartCardProg N N 1 i
Ticket.VoidedSmartCardCheckCode N N 1 s(16)
Ticket.TicketMedia N N 1 s(2) Ticket Media Table
Ticket.HolderLastName N N 1 s(40)
Ticket.HolderFirstName N N 1 s(30)
Ticket.HolderBirthDate N N 1 s(8) yyyyMMdd
Ticket.HolderBirthPlace N N 1 s(40)
Ticket.TicketStatus Y Y 1 s(2) Ticket Status Table
Ticket.EntryDate N N 1 s(8) yyyyMMdd
Ticket.EntryTime N N 1 s(6) HHmmss
Ticket.Notes N N 1 s(50)
Ticket.SignalCode N N 1 s(8)
Ticket.ExpirationDate N N 1 s(32) yyyyMMddHHmm

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 25 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.7.2 SetTickets – Input Fields

4.7.2.1 Auth.UserName
the user name released by the web services administrator

4.7.2.2 Auth.Password
the account password released by the web services administrator

4.7.2.3 Ticket.VenueCode
key field - the Venue part of the Performance-id of the ticket key

4.7.2.4 Ticket.PerformanceDate
key field - the date part of the Performance-id of the ticket key
a string of 8 char in the format ‘yyyyMMdd’

4.7.2.5 Ticket.PerformanceTime
key field - the time part of the Performance-id of the ticket key
a string of 4 char in the format ‘HHmm’

4.7.2.6 Ticket.TicketingCode
key field - the Ticketing System part of the Performance-id of the ticket key

4.7.2.7 Ticket.SmartCardCode
key field – the Smart Card part of the ticket-id key
this field is mandatory only for SIAE-compliant systems, otherwise it must be set to blank and
the ticket key will be completed by the Ticket.TicketCode field.
The Smart Card Code is a 8 chars alphanumeric string returned by the Smart Card

4.7.2.8 Ticket.SmartCardProg
key field – the Smart Card Sequence-Number part of the ticket-id key
this field is mandatory only for SIAE-compliant systems, otherwise it must be set to blank and
the ticket key will be completed by the Ticket.TicketCode field.
The Smart Card Sequence Number is a integer number returned by the Smart Card at the
issuing time

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 26 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.7.2.9 Ticket.TicketCode
key field - the barcode or whatever is read from the ticket at the control point.
For no-SIAE-compliant data this field is part of the ticket key instead of the couple
SmartCardCode/Prog.
The ticket code is an alphanumeric string of 32 max. chars containing any printable character,
spaces and punctuation marks included.

4.7.2.10 Ticket.TicketCodeAlt
A second barcode or whatever is read from the ticket at the control point.
For each ticket is allowed two identification codes according to the possibility of the used media
(e.g. RFID + barcode) or to allow two separate media with different codes (e.g. QR-code for
mobile and/or another barcode for the print-at-home paper.
Also this second ticket code is an alphanumeric string of 32 max. chars containing any printable
character, spaces and punctuation marks included.

4.7.2.11 Ticket.OrdineDiPosto
special encoding of sections based on two char ID as defined into the annexes of the Italian
SIAE /ADE regulation. That’s why the use of this field is relevant for SIAE-compliant systems.
For no-SIAE-compliant data the field can be omitted and the value ‘UN=Posto Unico’ (‘General
Admission’) will be used by the system

4.7.2.12 Ticket.OrdineDiPostoCapacity
Integer number of the capacity of the section. It’s a field requested for SIAE-compliant
Systems.

4.7.2.13 Ticket.RowSeat
row and seat number as a string of six chars as defined by the Italian SIAE /ADE regulation
(e.g. ‘R9 12’ as row 9, seat 12)
The field has meaning especially for SIAE-compliant systems, but if it is filled the data will be
handled and displayed when need.

4.7.2.14 Ticket.SectionId
alphanumeric string of 32 max. chars containing the Section code to identify the area where
the user can access or seat down. Note that this code might not refer to a real physical area,
but identify a grouping of the same behavior. For example the staffs of operators for
maintenance, for the arrangement of the performance, and the stewards are usually tickets
with a special areas (e.g Service, Maintenance, Organization etc.)
The code is added to the internal Section-Table if not found.
If this field is leaved blank it is filled in with the Ticket.OrdineDiPosto value

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 27 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.7.2.15 Ticket.SectionParent
alphanumeric string of 32 max. chars containing the Section code of the Parent area of
Ticket.SectionId. The usefulness of this field, usually blank, is to allow the system to handle a
new Ticket.SectionId by inheriting the behavior from its parent.

4.7.2.16 Ticket.SmartCardCheckCode
it’s the so called ‘Sigillo Fiscale’, a 16 chars hexadecimal string returned by the Smart Card at
the issuing time.
The field is mandatory only for SIAE-compliant data, otherwise it must be set to blank

4.7.2.17 Ticket.TicketIssueDate
The date of ticket issuing as a 8 char string in the format ‘yyyyMMdd’.
The system will verify that it is a “date”, without perform other validity checks (eg. no error
returned if TicketIssueDate+TicketIssueTime is greater than current date/time, probably due
to date/time sync issue between ticketing system and Access Control System).
The field is mandatory only for SIAE-compliant data, otherwise it can be set to blank, in his
case the default value of ‘19000101’ will be provided by the system

4.7.2.18 Ticket.TicketIssueTime
The day time of ticket issuing as a 4 char string in the format ‘HHmm’.
The system will verify that it is a “time”, without perform other validity checks (eg. no error
returned if TicketIssueDate+TicketIssueTime is greater than current date/time, probably due
to date/time sync issue between ticketing system and Access Control System).
The field is mandatory only for SIAE-compliant data, otherwise it can be set to blank, in his
case the default value of ‘’0000’ will be provided by the system

4.7.2.19 Ticket.TicketType
The ticket type as a two char encoding string according to the Ticket Types Table Appendix
specifications.
The field is mandatory only for SIAE-compliant data, otherwise it can be set to blank, in his
case the default value of ‘I1=Full Price’ will be provided by the system.
No-SIAE-compliant Ticketing Systems can use any other encoding based on 2 chars IDs

4.7.2.20 Ticket.TicketTypeDescr
The ticket type description as a 32 chars string. If not blank, the value of this field updates
the previous value found into the internal table of ticket types.

4.7.2.21 Ticket.TotalPrice
The total price of the ticket as the integer of cents of the used currency
The field is required only for SIAE-compliant data, otherwise it can be set to blank

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 28 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.7.2.22 Ticket.SeasonOrganizerCode
The well know code of the organizer of the season ticket.
The field is required only for SIAE-compliant data, otherwise it can be set to blank

4.7.2.23 Ticket. SeasonCode

the code of season ticket as a string of max. 8 chars.
The field is required only for SIAE-compliant data, otherwise it can be set to blank

4.7.2.24 Ticket. SeasonProg

the sequence number, as a string of 8 digit chars, of the season ticket if it is not a full season
subscription, but it’s an option-subscripion of a subset of performances of the season.
The field is required only for SIAE-compliant record in case of “Rateo di Abbonamento Turno
Fisso o Biglietto Abbonamento per Turno Libero/Open”, otherwise it can be set to blank

4.7.2.25 Ticket. SeasonPerformancesNum

the number of the optional available performances of the option-season ticket.
The field is required only for SIAE-compliant record in case of “Biglietto Abbonamento for
Turno Libero/Open”, otherwise it must be set to blank

4.7.2.26 Ticket. VoidedDate

The voided ticket date as a 8 char string in the format ‘yyyyMMdd’.
The system will verify that it is a “date”, and that VoidedDate+VoidedTime is greater than
TicketIssueDate+TicketIssueTime. No other validity checks performed (eg. no error returned
if VoidedDate+VoidedTime is greater than current date, probably due to date/time sync issue
between ticketing system and Access Control System).
The field is mandatory only for SIAE-compliant data, otherwise it can be set to blank.

4.7.2.27 Ticket. VoidedTime

The voided ticket date as a 4 char string in the format ‘HHmm’.
The system will verify that it is a “time”, and that VoidedDate+VoidedTime is greater than
TicketIssueDate+TicketIssueTime. No other validity checks performed (eg. no error returned
if VoidedDate+VoidedTime is greater than current date, probably due to date/time sync issue
between ticketing system and Access Control System).
The field is mandatory only for SIAE-compliant data, otherwise it can be set to blank.

4.7.2.28 Ticket. VoidedSmartCardCode

the code of the Smart Card that authenticated the voided ticket procedure
this field is mandatory only for SIAE-compliant systems, otherwise it must be set to blank.
The Smart Card Code is a 8 chars alphanumeric string returned by the Smart Card

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 29 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.7.2.29 Ticket. VoidedSmartCardProg

the Sequence-Number of the Smart Card that authenticated the voided ticket procedure
this field is mandatory only for SIAE-compliant systems, otherwise it must be set to blank.
The Smart Card Sequence Number is a integer number returned by the Smart Card at the
issuing time

4.7.2.30 Ticket. VoidedSmartCardCheckCode

it’s the so called ‘Sigillo Fiscale’, a 16 chars hexadecimal string returned by the Smart Card at
the procedure of authenticate the voided ticket.
The field is mandatory only for SIAE-compliant data, otherwise it must be set to blank

4.7.2.31 Ticket. TicketMedia

The media type as a two char encoding string according to the Ticket Media Table Appendix
specifications.
The field is mandatory only for SIAE-compliant data, otherwise it can be set to blank, in his
case the default value of ‘BT=Conventional Paper Ticket’ will be provided by the system.

4.7.2.32 Ticket. HolderLastName

the last name of the ticket holder as a string of 40 max chars.
The following rules must be fulfilled:
• Not NULL
• Length > 0 (without initial and ending ‘space’ chars)
• No unprintable characters
• No numbers allowed
• No punctuation or non-alphabetic type characters as
\|!”£$%&/()=?^<>[]*+@#§_,;.:{}
(allowed: space [ ], apex ['] , accent [`] and minus [-])
• Accented characters allowed
• The first non-space character cannot be: apex [‘],accent [`] or minus [–]
• The last non-space character cannot be minus [-]

The field is mandatory for SIAE-compliant data on performances with the requirement of
personal tickets (e.g. Performance.MandatoryHolderName=True), otherwise it can be set to
blank.
In any case the provided last name will be displayed where required.

4.7.2.33 Ticket.HolderFirstName
the first name of the ticket holder as a string of 30 max chars.
The same rules described for Ticket.HolderLastName must be fulfilled.
The field is mandatory for SIAE-compliant data on performances with the requirement of
personal tickets (e.g. Performance.MandatoryHolderName=True), otherwise it can be set to
blank.
In any case the provided name will be displayed where required.

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 30 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.7.2.34 Ticket.HolderBirthDate
the birth date the ticket holder as a string of 8 chars as ‘yyyMMdd’.
The field is mandatory for SIAE-compliant data on performances with the requirement of
personal tickets, otherwise it can be set to blank.
In any case the provided data will be displayed where required.

4.7.2.35 Ticket.HolderBirthPlace
the place of birth of the the ticket holder as a string of 40 max. chars
The field is mandatory for SIAE-compliant data on performances with the requirement of
personal tickets, otherwise it can be set to blank.
In any case the provided data will be displayed where required.

4.7.2.36 Ticket.TicketStatus
The ticket status as a two char encoding string according to the Ticket Status Table Appendix
specifications.
The field value defines the behavior of the ticket. It can be set to blank, in his case the default
value of ‘VT=Valid - standard Ticket’ will be provided by the system.

4.7.2.37 Ticket.EntryDate
The ticket use date as a 8 char string in the format ‘yyyyMMdd’
This value comes from the access control system and should not be changed. The access
control system will reject any non-compliant data.
The Ticketing Systems can acquire the use information date by this field.

4.7.2.38 Ticket.EntryTime
The ticket use time as a 6 char string in the format ‘HHmmss’
This value comes from the access control system and should not be changed. The access
control system will reject any non-compliant data.
The Ticketing Systems can acquire the use information time by this field.

4.7.2.39 Ticket.Notes
An alphanumeric string of max. 50 chars with some relevant information to be displayed at
the access control point at the reading time.

4.7.2.40 Ticket.SignalCode
An alphanumeric string of max. 8 chars with an agreed code to allow a different light signaling
on the access control point.
Some control devices handle different light signals with which the system can warn the steward
during the reading of the special tickets. This field can activate the signals related to the
previously defined codes.

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 31 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.7.2.41 Ticket.ExpirationDate
Expiration date as a string of 32 chars as ‘yyyMMddHHmm’, after which the ticket is no longer
valid.
Not required for SIAE-compliant record. If not required must be set to blank.

4.7.3 SetTickets - Output

Occ. Type Note/Format

SetTicketsResult 1 i Number of updated items

SetTicketsFail 1:n STF Error Class Tag
the key-value of the record on
SetTicketsFail.VenueCode 1 s(13)
error
the key-value of the record on
SetTicketsFail.PerformanceDate 1 s(8)
error
the key-value of the record on
SetTicketsFail.PerformanceTime 1 s(4)
error
the key-value of the record on
SetTicketsFail.TicketingCode 1 s(8)
error
the key-value of the record on
SetTicketsFail.SmartCardCode 1 s(8)
error
the key-value of the record on
SetTicketsFail.SmartCardProg 1 s(32)
error
the key-value of the record on
SetTicketsFail.TicketCode 1 s(32)
error
SetTicketsFail.Index 1 i Index of failed record
SetTicketsFail.FailCode 1 i Code Error
SetTicketsFail.FailDescr 1 s Description of the error
SetTicketsFail.FailReason 1 s Reason of the error

4.7.4 SetTickets - Cancellation/voiding procedure

Reference rules:
- the cancellation must refer to a previous issued ticket
- the cancellation cannot take place if the ticket has been used
- when in SIAE-compliance mode:
o the cancellation requires the simultaneous issue of ticket voiding data
(Ticket.VoidedDate, Ticket.VoidedTime, Ticket.VoidedSmartCardCode,
Ticket.VoidedSmartCardProg, Ticket.VoidedSmartCardCheckCode)
o once the ticket voiding data has been issued, the cancellation must be completed

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 32 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

It's not possible to cancel/void a ticket and then discover that its current status doesn't allow
that, therefore it is necessary to check that the ticket has not been used before cancel it.
If the access to the event has not yet started, the problem does not arise while if the access has
started the ticketing system must ask the CA system if the ticket is passed; this verification and
the consequent cancellation must take place in such conditions that between the verification and
the cancellation the ticket cannot be used, in particular the access must not be allowed until the
access control system receives the cancellation or an abort of the cancellation request.
The solution is to disable the ticket by setting its status as Black List so as to block access and
then carry out the appropriate operation, or abort and restore the validity of the ticket.

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 33 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.8 GetTickets

Fetch the ticket-records of a performance that match the given filter conditions (if any).

Filtering
To filter subsets of records you can insert one or more TicketFilter Class Tags with a set of single
field filters. The different TicketFilter Class Tags perform ORed conditions, whereas the different
items in the same TicketFilter Class Tag perform ANDed conditions.

Paging
This service returns a maximum number of records per time and implements a paging scheme
to fetch more items. The maximum number of record per page is defined by the input field
MaxTickets (with default 100). To get the next page of records, set the input field PagingKey
with the related value returned on the previous page.

4.8.1 GetTickets - Input

Req. Occ. Type Note/Format

Auth Y 1 A Auth Class Tag

Auth.UserName Y 1 s(80) Service Account
Auth.Password Y 1 s(80) Service Account Password
VenueCode Y 1 s(13) see SetTickets fields
PerformanceDate Y 1 s(8) see SetTickets fields
PerformanceTime Y 1 s(4) see SetTickets fields
TicketingCode Y 1 s(8) see SetTickets fields
yyyyMMddHHmmssfff,
lastUpdate N 1 s(17) yyyyMMddHHmmss, yyyyMMddHHmm,
yyyyMMdd
TicketFilter N 0:n TF TicketFilter Class Tag
TicketFilter.TicketCode N 1 s(32) if not blank filters on value
TicketFilter.SmartCardCode N 1 s(8) if not blank filters on value
TicketFilter.SmartCardProg N 1 s(32) if not blank filters on value
TicketFilter.TicketStatus N 1 s(2) if not blank filters on value
TicketFilter.TicketMedia N 1 s(2) if not blank filters on value
PagingKeyIn N 0:1 PGK PagingKey Class Tag
PagingKeyIn.PagingKey N 1 s(100) Paging key
PagingKeyIn.MaxRecords N 1 i Max records per page

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 34 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.8.2 GetTickets – Input Fields

See the SetTickets service field description for the common fields like TicketCode, TicketStatus
and so on.

4.8.2.1 PagingKeyIn.PagingKey
It’s an alphanumeric string of max. 100 chars to be provided to get the next page of records
following the last one according to the filters in being.

The value is returned by the output of the last GetTickets call and should be supplied as it is.
On the fist call this field must be blank.

4.8.2.2 PagingKeyIn. MaxRecords

It’s an integer number to define the max number of records returned by each service call. It
leaved blank the default value is 100 records per page.

4.8.2.3 lastUpdate
If specified, filters records that have been changed from the (>=) LastUpdate.
LastUpdate can be set in the following formats: yyyyMMddHHmmssfff, yyyyMMddHHmmss,
yyyyMMddHHmm, yyyyMMdd.

4.8.3 GetTickets - Output

Occ. Type Note/Format

GetTicketsResult 1 i Number of fetched items

PagingKeyOut 0:1 PGK PagingKey Class Tag
PagingKeyOut.PagingKey 1 s(100) Paging key to get the next page
PagingKeyOut.MaxTickets 1 i Max records per page
Ticket 0:n Ticket Class Tag
Ticket.VenueCode 1 s(13) key field
Ticket.PerformanceDate 1 s(8) key field
Ticket.PerformanceTime 1 s(4) key field
Ticket.TicketingCode 1 s(8) key field
Ticket.SmartCardCode 1 s(8) key field (**)
Ticket.SmartCardProg 1 s(32) key field (**)
Ticket.TicketCode 1 s(32) key field (*)

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 35 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

Occ. Type Note/Format

Ticket.TicketCodeAlt 1 s(32)

Ticket.OrdineDiPosto 1 s(2) OrdinePosto Table

Ticket.OrdineDiPostoCapacity 1 i

Ticket.RowSeat 1 s(6)

Ticket.SectionId 1 s(32)

Ticket.SectionParent 1 s(32)

Ticket.SmartCardCheckCode 1 s(16)

Ticket.TicketIssueDate 1 s(8) yyyyMMdd

Ticket.TicketIssueTime 1 s(4) HHmm

Ticket.TicketType 1 s(2) Ticket Type Table

Ticket.TicketTypeDescr 1 s(32)

Ticket.TotalPrice 1 i

Ticket.SeasonOrganizerCode 1 s(16)

Ticket.SeasonCode 1 s(8)

Ticket.SeasonProg 1 s(8)

Ticket.SeasonPerformancesNum 1 i

Ticket.VoidedDate 1 s(8) yyyyMMdd

Ticket.VoidedTime 1 s(4) HHmm

Ticket.VoidedSmartCardCode 1 s(8)

Ticket.VoidedSmartCardProg 1 i

Ticket.VoidedSmartCardCheckCode 1 s(16)

Ticket.TicketMedia 1 s(2) Ticket Media Table

Ticket.HolderLastName 1 s(40)

Ticket.HolderFirstName 1 s(30)

Ticket.HolderBirthDate 1 s(8) yyyyMMdd

Ticket.HolderBirthPlace 1 s(40)

Ticket.TicketStatus 1 s(2) Ticket Status Table

Ticket.EntryDate 1 s(8) yyyyMMdd

Ticket.EntryTime 1 s(6) HHmmss

Ticket.Notes 1 s(50)

Ticket.SignalCode 1 s(8)

Ticket.ExpirationDate 1 s(32)

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 36 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

4.8.4 GetTickets – Output Fields

See the SetTickets service for the common fields descriptions.

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 37 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

APPENDIX 1 - DATA TYPE

Abbr. Type

s(n) xs:string with max lenght of n chars

i xs:integer
b xs:boolean
A Zucchetti.Guardian.WebServices.Data.Auth
P Zucchetti.Guardian.WebServices.Data.Performance
SPF Zucchetti.Guardian.WebServices.Data.SetPerformanceFail
DPF Zucchetti.Guardian.WebServices.Data.DelPerformancesFail
SE Zucchetti.Guardian.WebServices.Data.Section
SSF Zucchetti.Guardian.WebServices.Data.SetSectionsFail
DSF Zucchetti.Guardian.WebServices.Data.DelSectionsFail
T Zucchetti.Guardian.WebServices.Data.Ticket
TF Zucchetti.Guardian.WebServices.Data.TicketFilter
PGK Zucchetti.Guardian.WebServices.Data.PagingKey
STF Zucchetti.Guardian.WebServices.Data.SetTicketsFail
VT Zucchetti.Guardian.WebServices.Data.VoidTicket
VTF Zucchetti.Guardian.WebServices.Data.VoidTicketsFail
CNT Zucchetti.Guardian.WebServices.Data.ChangeNameTicket
CNTF Zucchetti.Guardian.WebServices.Data.ChangeNameTicketsFail
CST Zucchetti.Guardian.WebServices.Data.ChangeStatusTicket
CSTF Zucchetti.Guardian.WebServices.Data.ChangeStatusTicketsFail

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 38 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

APPENDIX 2 – FAULT AND ERROR CONDITIONS

If some error occurred, the service returns the following tags:

Fault.faultcode Fault code (see error codes)

Fault.faultstring Fault description
Fault.detail Fault detail (useful information for service administrator)

Authentication error sample:

<s:Envelope xmlns:s="http:/ /schemas.xmlsoap.org/soap/envelope/">

<s:Body>
<s:Fault>
<faultcode>s:101</faultcode>
<faultstring xml:lang="en-US">Generic error: Access Denied: User or Password is
invalid</faultstring>
<detail>
<string
xmlns="http://schemas.microsoft.com/2003/10/Serialization/">GetPerformances:84510c27-0108-4d6f-956a-
7cbb79aada17</string>
</detail>
</s:Fault>
</s:Body>
</s:Envelope>

Error codes Table

The following error codes are used on fault data and on service fails data (ex:
SetTicketsFail.FailCode)

FailCode FailDescr
100 Generic error
101 Access Denied: User or Password is invalid
102 Access Denied: Operation not allowed
200 Generic database failure
210 Duplicate key
211 Key not found
220 Ticketing System code not valid
221 No Ticketing associated

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 39 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

FailCode FailDescr
310 The record cannot be edited
311 The record cannot be deleted
500 Invalid value
501 The field cannot be empty
502 Minimum length is not respected
503 Maximum length is not respected
504 Minimum value not respected
505 Maximum value not respected
600 The ticket cannot be changed
601 The ticket cannot be voided
702 Ticket already used
703 Ticket already voided

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 40 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

APPENDIX 3 - TICKET STATUS TABLE

Status. Description Ticket

VT Valid Ticket classical standard ticket

VD Valid Ticket digital ticket
ZT Used Ticket – on-line mode classical standard ticket
ZD Used Ticket – on-line mode digital ticket
MT Used Ticket – off-line mode classical standard ticket
MD Used Ticket – off-line mode digital ticket
DT Barred Entry classical standard ticket
DD Barred Entry digital ticket
FT Stolen Ticket classical standard ticket
FD Stolen Ticket digital ticket
AT Voided Ticket classical standard ticket
AD Voided Ticket digital ticket
BT Black List Ticket classical standard ticket
BD Black list Ticket digital ticket
PT Ticket to Refine classical standard ticket
PD Ticket to Refine digital ticket

Each status appears two times: the first for classical standard tickets (i.e. a paper or plastic
ticket is released by the issuer to the ticket holder at time of purchase) and the second for digital
tickets, i.e. access codes without a specific physical ticket issued at time of purchase. These last
kind of access codes are usually identified by special cards effectives for all the
venues/performances of a season, or by personal identification cards with RFID code. The
distinction between the two kind of codes is needed only for ‘SIAE-compliant’ tickets. For other
uses the first char of the status identifies the current condition of the ticket.

The ‘Used Status’ is divided also in on-line and off-line mode. The on-line mode take place when
the ticket has been authorized by the central system on-line, and the off-line mode when the
authorization has been done by the control device stand-alone. This splitting of the used status
comes from the italian SIAE regulation that contemplates a different handling for the two
validation method, but this information can come in handy also for non SIAE system.

The’ Barred Entry’ status comes from the DASPO italian police regulations for people that cannot
attend sport performances because of violence acts or disciplinary/administrative reasons.

The state ‘Ticket to Refine’ symbolizes a valid ticket with some missing data that must be
completed to be authorized for access the performance. It comes from the need to issue valid
tickets that will not be authorized until some its data will completed. An example are personal
and nominative tickets issued in advance for sponsors or for sportswriters of whom you do not
know the name before the performance day.

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 41 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

Note that the states

- Ax (Voided)
- Dx (Barred)
- Fx (Stolen)
- Bx (Black List)
- PD (to refine - to be enhanced)

are detailed states of a not authorization condition, useful to understand, especially to the gates,
the real reason of the permission denied.

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 42 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

APPENDIX 4 - TICKET MEDIA TABLE

This table provides the values for encode the kind of physical media of the ticket as defined into
the annexes of the ADE regulation 2008/22799 March 4th 2008 and subsequent amendments
and additions.

The real and correct value is mandatory only for SIAE-compliant data.

The default value, if the field is omitted, is ‘BT=Conventional Paper Ticket’

Description Ticket

BT Conventional Paper Ticket classical standard ticket

CC Credit Card digital ticket
CE Cellular Phone digital ticket
CI Identity Card digital ticket
DD Generic Digital Document digital ticket
FI Fidelity Card digital ticket
PB Passbook ® digital ticket
TC Municipal Service Card digital ticket
TF Supporter Card digital ticket
TS Health Insurance Card digital ticket

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 43 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

APPENDIX 5 - TICKET TYPES TABLE

This table provides the values for encode the kind of ticket types.

The encoding of is based on two char ID as defined into the annexes of the Italian ADE regulation
2004/137221 August 3rd 2004 and subsequent amendments and additions, and the use of real
and correct values is mandatory for SIAE-compliant Ticketing System. For the complete values
of the SIAE table, see the annexes of ADE regulations.

The default value, if the field is omitted, is ‘I1=Full Price’

No-SIAE-compliant Ticketing Systems can use any other encoding based on 2 chars IDs. If there
was a need of longer IDs, this constraint could be removed by an agreement to implement an
extended data length of this field

Description Notes

I1 Full Price
Ix Generic Full Price x in the range [2..9 A..Z]
R1 Reduced Price – Children / Military
R2 Military Reduced Price
R3 Children Reduced Price
R4 Senior Reduced Price
R5 Lady Reduced Price
R6 Club Reduced Price
Rx Generic Reduced Price x in the range [7..9 A..Z]
O1 Free Ticket – Children / Military digital ticket
O2 Military Free Ticket digital ticket
O3 Children Free Ticket digital ticket
O4 Senior Free Ticket digital ticket
O5 Lady Free Ticket digital ticket
O6 Club Free Ticket digital ticket
Ox Generic Free Ticket x in the range [7..9 A..Z]
Sx Service Pass x in the range [1..9 A..Z]
SA Authority Pass
SN Free Performance Pass for free performances for all
. . .

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 44 / 45

 GESACC V.2.2.2

GUARDIAN-W
WEB SERVICE SPECIFICATIONS 17 maggio 2023 REV.: 1

APPENDIX 6 – ORDINI DI POSTO (SIAE-SECTIONS) TABLE

This table provides the values for the SIAE encoding “Ordini di Posto”, i.e. the special encoded
Sections by the Italian SIAE.

The encoding of is based on two char ID as defined into the annexes of the Italian ADE regulation
2004/137221 August 3rd 2004 and subsequent amendments and additions, and the use of real
and correct values is mandatory for SIAE-compliant Ticketing System. For the complete values
of the SIAE table, see the annexes of ADE regulations.

The default value, if the field is omitted, is UN=’Posto Unico’ (‘General Admission’)

No-SIAE-compliant Ticketing Systems can use the default value (i.e. can omit the field)

Description Relationship

Ax Anello x Level x
Cx Curva x Stand Behind the Goal
Dx Distinti x Stalls x
Gx Gradinata x Bleacher x
Hx Galleria x Gallery x
Lx Loggione x Gods x
Mx Poltronissima x Top Tier Seats
Ox Poltrona x Seats
Px Palco x Box x
PR Prato Lawn
PT Platea Stall/Orchestra
Rx Parterre x Lawn/Parterre x
Sx Settore x Section x
Tx Tribuna x Gallery x
UN Posto Unico Open Seating
UP Posto in Piedi Standing Room
where x is in the range [A..Z]
except for Px
where x is in the range [A..P]

17/05/2023 Zucchetti-GESACC_v2.2.2-Guardian-W-Web Services Specification.docx pag. 45 / 45