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

Links from the website to the ticket shop

S-360 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.

Links from the ticket shop to the website

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.

"What is your location?" link

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 S-360 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.

S-360 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.

S-360 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 "S-360 identifier" (code or Id), allowing S-360 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	S-360 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 S-360 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	S-360 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