This document assumes that you are trying to build a connection between your access control system and a SecuTix ticketing instance.
Your client is the institution with code INSTIT. We will refer to it as "the institution"
The recommended steps are:
The access control supplier must develop a two-way interface:
For a single event, or for a few events in the same venue, it is unnecessary to develop an interface using the “getCatalog” function.
Instead, the institution will indicate to you the required input parameters of the “exportList” function, namely:
The the institution production web service interface is available at:
To access this web service, you will need a username and password, to be provided separately by the institution.
It is recommended to call the SecuTix servers a few times a day (with a maximum of one call per hour) in the lead-up to the event.
On event day, and only for the tickets relevant to the ongoing event, calls be increased in frequency, up to once per minute.
When making very frequent calls on event day, every minute:
The export of barcodes should be requested only for the newly created barcodes (not ALL barcodes), using the pagination feature described in the documentation.
When returning controlled tickets to SecuTix every minute, only the new recent controls should be returned, since the last call was made (not ALL controls).
audienceSubCategoryCode: This corresponds to the tariff at which the ticket was sold. It should be stored in the access control system in order to trigger special display modes on the access control devices. For example, if age of the ticket holder needs to be verified.
CancellationCause: The ticketing system will provide you with the reason the ticket was cancelled in the ticketing system in the cancellationCause field (for all CANCELLED tickets). It is desirable to store this in the access control system, in order to be able to inform the public in case of a dispute.
FIRSTNAME, LASTNAME, ID_NUMBER, BIRTHDATE, COUNTRY_CODE: the institution will decide whether to send these specific fields relating to the ticket holders to the access control system (first name, last name, passport/ID card number, birthday, and nationality country code). It is necessary to store them if they are sent.
Yes, the taxNumber is a short human-readable unique identifier of every ticket. It is generally printed on the tickets (and shown on mobile tickets).
SecuTix returns tickets that may have an “entranceCode”, which corresponds to the normal gate to access the venue.
If it is possible to access the seat from several gates, such rules must be configured directly within the access control system. These rules are not available through the interface.
SecuTix does not return multiple entrance codes for a single seat.
If the access control system reads barcodes that are not issued by SecuTix, if it not necessary to return them to SecuTix through the interface. They will be ignored by SecuTix if they are sent.
When you return controlled tickets to SecuTix, you may get the response 'Failed to import controlledTickets:7415628301550254'. This indicates that the relevant barcode is invalidated in the ticketing system (i.e. it is in the blacklist). Therefore it cannot be marked as controlled.
This may be a consequence of the fact that the interface is not running in near real-time: The ticket may have been retrieved as a white-list item, and it was later invalidated by the institution in the ticketing system.
In such cases, if the ticketing system reports an error, there is no point in trying again. Once a ticket is blacklisted, it is not possible to undo that action and make the ticket valid again, in order to control it.
If you have any technical questions on the access control interface, please contact firstname.lastname@example.org.
If you have questions on specific data elements, please contact the institution in the first instance.