Access control API

Quick reference

API Type Latest version Test account Know how (s)
ExternalAccessControlService SOAP and REST 1.5 museums
sports
Q&A
Integration example

This document describes the public access control API of SecuTix 360.
This set of web services allows an external access control system to connect to SecuTix 360.

This API is for Access control only.
This Access control API is designed to link an access control system to SecuTix. If the purpose is to link something else than an access control system, please do not use this API.

One and only one WS client can handle access control for a given product
For legal and security reasons, SecuTix is setting a limit of one and only one access control system for a given product. That means that you can't use two different clients each one storing its own pagination data (see below exportList documention) for a given product.

Functional architecture

SecuTix manages tickets as “entry rights” and the unique identification key is its barcode. This means that a totally dematerialized ticket (e.g. an “RFID card based” ticket) still has its own barcode. Although this barcode will actually never be printed out, it will still enable the ticket to be identified among all other tickets associated to the same RFID card. Therefore, in tickets exports by list, the RFID ticket will be exported with its barcode AND its container’s ID (in this case, the RFID tag). While scanning this container, the access control system must find the valid ticket for the event and mark the associated barcode as “used”, then report it to SecuTix as “checked”. This fine granularity enables one container to be associated to several tickets for the same event and makes it possible to cancel (or transfer from one container to another) one of these tickets only.

Technical notes

  • All methods exposed in this document are transactional. This means that if an error occurs, none of the actions have been completed. For example, during the checks import, either all tickets have been imported or none of them. It is not possible that the action is only partially completed.
  • Before pursuing any further integration with SecuTix access control system, please check that your barcode prerequisites do match SecuTix barcode format.

SecuTix standard for web-services

Please refer to that document. Both SOAP and REST are available for these APIs.

Unless otherwise specified, all those methods are transactionnal and idempotent.

Non Functional consideration

Remember call rate limitation explained in API Terms and Conditions.

Error codes

Error codes are referenced here

Q&A

This page lists frequent questions and answers for integration.

Method description

getCatalog

This method returns a list of products handled by the current access control account. Most important fields are product codes and performance codes.

exportList

he retrieval of white/black lists of tickets sold in SecuTix (or via a sales partner but then reintegrated into SecuTix in the meantime) by the access control software is made possible through calling a Web Service.

The access control partner decides on the calling frequency.

Recommendation:

A maximum of 1 call per hour, except in case of urgent update during the day, or prior to the event. The frequency should never be higher than every minute.

This method sends a maximum of 5000 lines in order to avoid overloading our servers and the bandwidth necessary to the transfer. To get the rest of the list (=pagination), the user needs to use the same method and provide as parameters paginationStart=AccessControlListResult.paginationEnd. Only the very first call should be done without using the field paginationStart, all others must include it, otherwise the same data (the first 5000 lines) will always be sent back.

The sent back pagination data (AccessControlListResult.paginationEnd) is only valid for the same asked granularity (season or product list). Therefore, if a call with seasonCode=null ;productCode={P1,P2} sends back PE and the next call is made with seasonId=X ; productIds=null (or with seasonId=null ; productIds={Q1,…} ) with paginationStart =PE, then it is very likely that tickets that should have been returned are actually not.

Note 1: when using grey lists. The call returning CANCELLED tickets will always return the corresponding VALID ticket at the same time, just before in the list. If the valid ticket was already taken into account by the client, it can then be ignored.

Note 2: If neither seasonCode nor productCode are indicated as parameters, this method will send all tickets that are visible by the partner and have had a state change since paginationStart.

Note 3: although paginationStart/End look like a date, they must not be interpreted as a date but kept and sent as a string without any alteration.

importControlledTickets

In the view of carrying out BI analysis, it is relevant to report all tickets that have been checked, whether they are positive or negative checks.