Q&A - integrate S-360 Access control API

This document assumes that you are trying to build a connection between your access control system and a S-360 ticketing instance.
Your client is the institution with code INSTIT. We will refer to it as "the institution"

What are the project steps to develop an access control interface with S-360?

The recommended steps are:

1. Read the online documentation about the interface here.
   1. An integration example is provided here.
   2. Technical descriptions of data fields are provided online here.
2. Develop a working interface with the sandbox test account, described online here.
   1. This test environment has the advantage of having tickets immediately available, in a stadium configuration. However, it is not your venue. It should be sufficient to understand the data formats and start on the development.
3. Set-up a VPN with the S-360 datacenters or ask S-360 to open ports in the datacentres’ firewalls to access the production environment interface.
4. Request S-360 to provide you with access to the pre-production/production environment interface.
5. Run some tests with the institution.
6. The institution will provide you with a variety of valid and invalid tickets, in various formats, from the production environment, to validate the 2-way interface is working correctly.
7. Use the system on event day.

Which interfaces are needed?

The access control supplier must develop a two-way interface:

1. Export of barcodes from S-360 to the access control system:
   1. Use the “exportList” function to obtain the GREY list of valid and invalid barcodes.
   2. Make sure you implement the pagination feature to be able to retrieve all the valid tickets (see documentation).
2. Report the controlled tickets from the access control system back to the ticketing platform.
   1. Use the “importControlledTicket” interface to return to S-360 the controlled tickets.

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 “seasonCode”, and
• The “productCode”

What are the production interface URLs?

The the institution production web service interface is available at:

https://INSTIT.ws.secutix.com/tnci/external-remoting/com.secutix.facade.control.v1_5.ExternalAccessControlService.webservice?wsdl

To access this web service, you will need a username and password, to be provided separately by the institution.

At what frequency should calls be made?

It is recommended to call the S-360 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 S-360 every minute, only the new recent controls should be returned, since the last call was made (not ALL controls).

Should the access control system store specific fields related to tickets?

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.

Is there any other unique identifier of ticket than barcode, both in data and printed on ticket, that is a human-readable number?

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).

What are the access control rules?

S-360 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.
S-360 does not return multiple entrance codes for a single seat.

Should the access control system return unreadable barcodes?

If the access control system reads barcodes that are not issued by S-360, if it not necessary to return them to S-360 through the interface. They will be ignored by S-360 if they are sent.

I tried to return a controlled ticket, but was not able to, why? Should I try again?

When you return controlled tickets to S-360, 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.