Redirect API

Quick reference

Links from the website to the ticket shop Links from the ticket shop to the website Reloading data or visual items in the ticket shop
"Book now" button Static pages Standard technique for calls
"Select an option" button Product detailed sheet Modification detection
Accessing the client space from the website "What is your location?" link Loading product reloads
Accessing the client profile for edition from the website Language change
Displaying a shopping cart summary on the site
Redirect the client directly to the cart for a given order
Redirect the client directly to the checkout page for a given order

SecuTix makes a web API available for websites; it is currently in version number 1. It is self-documented and a demo account may be accessed from the URL address:

https://thecube-cube.demo-shop.secutix.com/api/1/

The most frequent methods are detailed below:

"Book now" button

A "book now" link displayed on the detailed sheet of a product (event, service, package…) gives access to the online shopping site.

The link should be displayed if and only if the following conditions are met:

  • The product is on sale;
  • The product is available.
Protocol HTTPS
Method GET
Domain *.shop.secutix.com
URI /api/1/redirect/product
Query String Parameter name Description
id Product identifier
code Product code (if the Id is unknown)
lang ISO 639-1 language code (optional)

Example: https://thecube-cube.demo-shop.secutix.com/api/1/redirect/product?id=1&lang=en

It is possible to access directly a performance of an event:
Protocol HTTPS
Method GET
Domain *.shop.secutix.com
URI /api/1/redirect/product/performance
Query String Parameter name Description
id Product identifier
lang ISO 639-1 language code (optional)

"Select an option" button

A "Select an option" link displayed on the detail sheet of a product (event, service, package…) gives access to the online buying site.

The link should be displayed if and only if the following conditions are met:

  • The user is in the catalogue for the "CE" universe;
  • The option request is authorized for the product.
Protocol HTTPS
Method GET
Domain (ticketing-pro).shop.secutix.com
URI /api/1/redirect/option
Query String Parameter name Description
productId Product identifier
lang ISO 639-1 language code (optional)

Example: http://thecube-cube.demo-shop.secutix.com/api/1/redirect/selectOption?productId=1&lang=en

Accessing the client space from the website

It is possible to access the home page of the client space in the ticket shop.

If the user is not authenticated, the ticket shop will redirect them to their authentication page.

Protocol HTTPS
Method GET
Domain espaceclient.secutix.com
URI /api/1/redirect/account
Query String Parameter name Description
lang ISO 639-1 language code (optional)

Accessing the client profile for edition from the website

It is possible to access the profile edition page of the client from the ticket shop.

If the user is not authenticated, the ticket shop will redirect them to their authentication page.

Protocol HTTPS
Method GET
Domain espaceclient.secutix.com
URI /api/1/redirect/account/edit
Query String Parameter name Description
lang ISO 639-1 language code (optional)

Displaying a shopping cart summary on the site

For every modification in the shopping cart made in the purchasing channel, the ticket shop writes the amount of items and the total sum in a domain cookie that is readable by the website if it is deployed in the same domain.

A domain cookie is applied on the complete domain, and so the cookie set by the ticket shop resa.stadefrance.com will be readable from accueil.stadefrance.com.

In order to compact the HTTP headers, only one cookie will be used, separating the values with a pipe ( | ).

Protocol COOKIE
Domain secutix.com or the client's
Key name Contents Description
stx_cartSummary_< organisation code >_< channel code > qty|amount|currency|expiration|orderId qty: number of articles in the cart
amount: total sum of the cart expressed in the purchasing currency, with a point ( . ) as decimal separator and no thousands separator.
currency: currency code with the ISO-4217 format
expiration: date when th current cart will be automatically abandonned
orderId: technical identifier of this order

Redirect the client directly to the cart for a given order

This redirect url is mainly useful if you try to access an order that has been created outside the usual pages of the Ticketshop (through webservices calls most of the time)

Protocol HTTPS
Method GET
Domain espaceclient.secutix.com
URI /api/1/redirect/cart
Query String Parameter name Description
orderId Id of the order (mandatory)
orderToken secret order id (scan be retrieved through calls to webservices where it is named secretOrderId)
lang ISO 639-1 language code (optional)
advantageId Long, optional: if voucher codes are passed, this must be the advantage id associated to those codes
oneTimeCodes List of strings, optional. Voucher codes to be redeemed during order closing. If they are passed, advantage id must be passed also.

Redirect the client directly to the checkout page for a given order

This redirect url is mainly useful if you try to access an order that has been created outside the usual pages of the Ticketshop (through webservices calls most of the time). This call skips the cart page and redirects to the shipment method selection.

If only one shipment method is available, user will be redirected directly to order summary page.

Protocol HTTPS
Method GET
Domain espaceclient.secutix.com
URI /api/1/redirect/checkout
Query String Parameter name Description
orderId Id of the order (mandatory)
orderToken secret order id (scan be retrieved through calls to webservices where it is named secretOrderId)
lang ISO 639-1 language code (optional)
advantageId Long, optional: if voucher codes are passed, this must be the advantage id associated to those codes
oneTimeCodes List of strings, optional. Voucher codes to be redeemed during order closing. If they are passed, advantage id must be passed also.

Static pages

The "internet" ticket shop references editorial contents. These contents are static HTML pages with their URL configured by the ticketing shop at the point of sales level.

This flexibility allows the client to modify these editorial pages with the help of the CMS used for the website without the intervention of a ticket shop operator.

Several pages are required:

  • General sales terms and conditions
  • Confidentiality and protection of personal data

Product detailed sheet

When the user is at the "internet" ticket shop, they can return to the detailed sheet of the event/product on the website. This URL address is configured at the product level.

As the event/product is common to the different sales channels, only one return URL to the website can be configured for each event.

For the website to take into account the request source when displaying the event details, the ticket shop dynamically adds the current sales channel ("INTERNET" or "CE") identifier ("salesChannelId") to the URL.

The website provides a URL address that allows users to view their location.
Protocol HTTPS
Method GET
Domain The website's
URI Supplied by the website
Query String Parameter name Description
lang ISO 639-1 language code (optional)
productId Product identifier
block Block identifier
row Row identifier
seat Seat identifier

Language change

If the user modifies the language in the "Internet" ticket shop, it is necessary that the links include an element specifying the current language so that the change is visible on the website.

If the {LANGUAGE} string is present in an external URL configured at the point of sales level, this character string will be replaced with the ISO 639-1 code for that language.

This is valid for all the ticket shop links to the website, including the general terms and conditions pages, the detail sheet of a product...

E.g.:

http://www.mysite.com/{LANGUAGE}/index.html becomes http://www.mysite.com/fr/index.html if the user is browsing in French.
http://www.mysite.com/{LANGUAGE}/index.html becomes http://www.mysite.com/fr/index.html if the user navigates in French.

Reloading data or visual items in the ticket shop

With a view to enriching the sales channel and/or dynamically modifying part of the display, the website has a chance to supply a webservice that SecuTix will call to retrieve data that will reload these configuration settings in the ticket shop.

This allows the ticket shop to skip retrieving the pictures for products that may not be necessary for the ticket selling operators; instead, it could define this picture for the website by the web copywriting team and see this same picture in the selling tunnel, therefore ensuring a homogeneous User eXperience.

This mechanism has a "sales channel" provision; therefore, if a channel has multiple points of sales (certain agencies, for example), the reload will be the same for all the points of sale of the said channel.

SecuTix will call this webservice in asynchronous mode and will save the data (including the pictures) in cache, so that both systems are completely disconnected from each other.

With a view to optimising the update speed while maintaining a reasonable charge on the website, the website will have to provide a second webservice that will reply whether the supplied data have changed or not.

Standard technique for calls

The protocol is REST.

The call is a GET HTTP command on http or https.

SecuTix supports the provision of a login name/password under the form of BASIC-AUTHENTICATION.

The result of the calls must be a HTTP 200 reply and the contents (excluding headers) should only be a JSON object.

The parameters of type "Date and time" must be coded in ECMAScript format, which derives from ISO 8601 (see http://es5.github.io/#x15.9.1.15). They are times UTC, with the following syntax: "YYYY-MM-DDTHH:mm:ss.sssZ".

Modification detection

Protocol HTTPS
Method GET
URI PREFIX/1/catalog/meta
Query String Parameter name Description
n/a
Result Parameter name Description
Date lastUpdate Date and time of last modification

The ticket shop will call this service very often (approx. every 1 - 5 minutes) and so it is advisable that this call is fast and "light" for the website.

The result will be saved by the ticket shop and, for every call that resends a higher value than the previous one, this will trigger the reloading of details since the lastUpdate date of all the products (method below).

The semantics of the result is irrelevant for the ticket shop; the website is free to use the maximum of last modification dates of the different entities, etc.

Example:

Request:
GET https://PREFIX/1/catalog/meta

Result:
{ "lastUpdate": "2013-02-25T09:46:54.010Z" }

This URL resends the product list with an Id for every one, a "SecuTix identifier" (code or Id), allowing SecuTix to identify them and a "lastUpdate" field, in the same way as for the global detection of changes in the catalogue. This allows you to precisely determine which product has been changed.

Protocol HTTPS
Method GET
URI PREFIX/1/catalog/meta/details
Query String Parameter name Description
n/a
Result Parameter name Description
List<ProductMeta> productsMetas
ProductMeta Parameter name Description
String(50) id Website identifier of this product
String(50) stxId SecuTix product identifier
String(17) stxCode Organisation code + | + season code + | + product code. Example "ORG|12-13|Trav "
Date lastUpdate Date and time of last modification

Example:

Request:
GET https://PREFIX/1/catalog/meta/details

Result:

{
"productMetas": [
          {"id": "ConcertU2:2102", "stxId": "1234567", "lastUpdate": "2013-02-25T09:46:54.010Z"},
          {"id": "894639304565", "stxCode": "ORG|2012-13|Rigolett", "lastUpdate": "2013-02-25T09:46:54.010Z"},
          {"id": "GUID:FE45-23AD-72F0-12CF-D98E", "stxCode": " ORG|2012-13|Prince", "lastUpdate": "2013-02-25T09:46:54.010Z"},
          ]
}

Loading product reloads

Once SecuTix has determined which products have been changed, it calls this url in a loop for every product and will save the retrieved data in its cache. If a picture is provided, it will also be downloaded and saved in cache. Pictures must be in JPEG format.

For every product, if a Product Overload field is supplied, it will be used for reloading that value in the ticket shop. Similarly, the fact of supplying a field with an "empty string" value (for example, "topic": "" ) will send an empty value.

If the site would not want to overcharge a value, then the field should not be supplied.

Reloaded fields may contain simple HTML code, namely the tags: <b> <i> <u> <table><tr><td><th><div>. ATTENTION: we are considering not asking for HTML but for Textile (which gives great flexibility while guaranteeing a good content layout). In this case, the text must contain the "!textile" tag as the only text on the first line.

The use of javascript is not allowed and the HTML code must be correctly formed (each open tag must be correctly closed).

Protocol HTTPS
Method GET
URI PREFIX/1/catalog/products/<id>
Query String Parameter name Description
n/a
Result Parameter name Description
String(50) id Website identifier of this product
String(50) stxId SecuTix product identifier
String(17) stxCode Organisation code + | + season code + | + product code. Example "ORG|12-13|Trav "
Date lastUpdate Date and time of last modification
Topic topic Arborescence of topic and subtopics, separated by pipes ( | ) Example: "topic": "Opéra|Baroque|18ème"
Multilingual name Product name
Multilingual description Product description
Multilingual nameAddOn Product name add-on ATTENTION: This is only applicable for «Event» or «Visit» products.
URL logo url address of the logo. A logotype is not downloaded again if its URL address changes
Location location A location. ATTENTION: This is only applicable for «Event» or «Visit» products.

Example:

Request: GET https://PREFIX/1/catalog/894639304565

Result:

{
  "id": "894639304565",
  "stxCode": "2012-13|Rigolett",
  "lastUpdate": "2013-02-25T09:46:54.010Z"},
  "topic": { "code": "OPERA|ROM|19E", "name": { "translations": [
          { "locale": "fr", "value": "Opéra|Romantique|19ème" },
          { "locale": "en", "value": "Opera|Romantic|19th" }
          ] } },
  "name": { "translations": [
          { "locale": "fr", "value": "<b>Rigoletto</b> de Verdi" },
          { "locale": "en", "value": "<b>Rigoletto</b> from Verdi" }
          ] },
  "location": {
          "siteCode": "BASTILLE",
          "spaceCode": "AMPHI",
          "siteName": { "translations": [
             { "locale": "fr", "value": "Opéra Bastille" },
             { "locale": "en", "value": "Opéra Bastille" }
          ] },
          "spaceName": { "translations": [
             { "locale": "fr", "value": "Amphithéâtre" },
             { "locale": "en", "value": "Amphiteatre" }
          ] },
  },
  "logo": "http://example.com/resources/img/hdt203ndxhze83.jpg?version=3"
}

It is also possible to submit all the products in one go, by not specifying the product identifier.

Protocol HTTPS
Method GET
URI PREFIX/1/catalog/products/
Query String Parameter name Description
n/a