Summary§

Yesplan provides a generic ticketing integration plugin. Any (ticketing) service that offers the HTTP API described in this document can be integrated with Yesplan.

The HTTP server is expected to provide REST-style collections of “events” and “productions”. The server should specifically provide HTTP resources at URLs with the following forms, and should be prepared to handle HTTP requests on these URLs with the listed HTTP methods:

HTTP Resource URLs HTTP Methods
/events/{id} GET, PUT, DELETE
/events?year={year}&month={month} GET
/productions/{id} PUT, DELETE
/mappings GET

The process between Yesplan and ticketing§

All events (shows, performances, concerts, etc.) are added in Yesplan by a programmer, depending on the kind of organisation this happens between now and 2 years ahead. All those new events are in ‘Option’, meaning that there are still some negotiations about pricing, deals, number of performances, dates, etc. going on.

Once an agreement is reached, the events will be set to ‘Confirmed’. From this moment on it is possible to send the event to the ticketing system so tickets can be sold. Some crucial information will be sent like the name of the event, starttime and endtime and the location. It is possible to add more data depending on the customers wishes (and our own), but this is limited. (It is not the goal to manage your whole ticketing with Yesplan too, Yesplan is no ticketing software).

Whenever something is changed to data which is linked, all linked data will be sent as an update immediately. Note: for the data that will be sent from Yesplan to ticketing, Yesplan is leading. This means the data should be changed in Yesplan. Of course, specific cases like the change of a location will be impossible when tickets are sold.

Once the ticketing is set up or the events are linked in the ticketing software, it is possible to retrieve some information about the ticket sales: capacity, the number of sold tickets, number reserved tickets, number free tickets, number of blocked seats, the return (income), etc. However, the data which is retrieved by Yesplan should be the same for each event.

Definition: Event, Production§

An event is the show or performance on which tickets are sold. The calls specified below handling events are required.

Some ticketing software groups different events (shows) of the same production together at their side. For each of those events (shows) in that production tickets are sold. Yesplan can facilitate this concept of grouping with the productions call.

The use of production is not required. Also see Limited Implementations for more details.

Details§

JSON Data Types§

All data is exchanged using JSON. Yesplan identifiers and date-time values are exchanged as JSON strings that adhere to the following regular expressions:

The format <date-time string> is based on the ISO 8601 standard. For values sent by Yesplan, the UTC offset is always the offset applicable for the time zone of the Yesplan installation at the represented point in time, taking into account summer and winter time. For customers in central Europe, these offsets are +02:00 for summer time and +01:00 for winter time. Thus, the example 2017-10-29T02:30:00+02:00 represents the first time the clock indicated 02:30 at the changeover from summer time to winter time in 2017, while 2017-10-29T02:30:00+01:00 represents the second time the clock indicated 02:30. For Yesplan installations of customers in the United Kingdom, the equivalent examples are 2017-10-29T01:30:00+01:00 and 2017-10-29T01:30:00+00:00.

The members of some JSON objects are not limited to a fixed set of names. The notation <custom name/value pairs> is used to indicate a JSON object can have additional members besides the ones listed. For objects sent by Yesplan, these members are defined by the customer, based on custom data fields. The format for the values is the same as used in the HTTP API, more details can be found in the section “Custom Data Reference” of the HTTP API documentation.

For JSON objects sent to Yesplan, there can be custom name/value pairs as well. The values in this case are limited to null, strings and numbers. Booleans, arrays and objects are not allowed as values in this case.

Resources at URLs {…}/events/{id}§

HTTP Method: PUT§

Yesplan sends an HTTP PUT request to the configured url to publish or update an event. The body of the request is a JSON document as outlined below. A response code in the 2xx range lets Yesplan know that the event was correctly published. The response code can be 201 (“Created”) when the event has been created or 204 (“No Content”) when it has been updated. Yesplan doesn’t expect the response to include a body. Any response with status code outside of the 2xx range is considered as a publication failure.

Yesplan can send values defined in a Yesplan event’s custom data as custom-defined name/value pairs (indicated below with <custom name/value pairs>). The name of each pair can be determined in the Yesplan configuration settings and the value is identical to how the custom data field is exported by the Yesplan HTTP API.

Example URL: /api/events/{id}

The body (JSON) is a JSON object as follows:

{
    event-id: <id string>,
    production-id: <id string>,
    name: <string>,
    location: <string>,
    starttime: <date-time string>,
    endtime: <date-time string>,
    <custom name/value pairs>
}

HTTP Method: GET§

Yesplan triggers an HTTP GET request to the configured url to retrieve the (sales) data of a previously published event. The {id} is a required url parameter and Yesplan expects a response with code 200 and a JSON document as outlined below. Any response with status code outside of the 2xx range lets Yesplan know that an error occurred.

Yesplan expects the sales figures to appear in the <custom name/value pairs>. The value for the name ‘in-sale’ is expected to be true when the event is effectively in sale, meaning that there are useful values in the custom name/value pairs on sales figures. The value for the name ‘closed’ is expected to be true when the event’s provided data (from the ticketing service to Yesplan, i.e. sales figures) can no longer change.

mandatory url parameter: {id}

Example URL: /api/events/{id}

expected response body (JSON):

{
    production-id: <id string>,
    name: <string>,
    location: <string>,
    starttime: <date-time string>,
    endtime: <date-time string>,
    in-sale: <boolean>,
    closed: <boolean>,
    <custom name/value pairs>
}

HTTP Method: DELETE§

Yesplan triggers an HTTP DELETE request to the configured url to remove a previously published event. The {id} is a required url parameter. A response code of 204 lets Yesplan know that the event was correctly removed. Yesplan does not expect the response to include a body. Any response with a status code outside of the 2xx range is considered as a failure.

mandatory url parameter: {id}

Example URL: /api/events/{id}

Resources at URLs {…}/events?year={year}&month={month}§

HTTP Method: GET§

Yesplan triggers an HTTP GET request to the configured url to retrieve the (sales) data of a set of previously published events. The {year} and {month-number} parameters are required and Yesplan expects a response with code 200 and a JSON document as outlined below. Any response with status code outside of the 2xx range lets Yesplan know that an error occurred.

mandatory url parameters: {year},{month-number}

Example URL: /api/events?year={year}&month={month-number}

expected response body (JSON):

[
    {
        event-id: <id string>,
        production-id: <id string>,
        name: <string>,
        location: <string>,
        starttime: <date-time string>,
        endtime: <date-time string>,
        in-sale: <boolean>,
        closed: <boolean>,
        <custom name/value pairs>
    }
]

Resources at URLs {…}/productions/{id}§

HTTP Method: PUT§

Yesplan triggers an HTTP PUT request to the configured url to create an (empty) production in the ticketing service, or to update a production. There are no URL parameters and the body is a JSON document outlined below. A response status code of 201 (“Created”) lets Yesplan know that the production was correctly created, while a response status code of 204 (“No Content”) lets Yesplan know that it was updated. Any response with status code outside of the 2xx range is considered as a publication failure.

A production is a group of events with a name. Each individual event references its production by id. This request is used by Yesplan to create a production (or to update its name) on the ticketing server.

Yesplan can send values defined in a Yesplan production’s custom data as custom-defined name/value pairs (indicated below with <custom name/value pairs>). The name of each pair can be determined in the Yesplan configuration settings and the value is identical to how the custom data field is exported by the Yesplan HTTP API.

Example URL: /api/productions/{id}

The request body (JSON) is an array of objects as follows:

{
    production-id: <id string>,
    name: <string>,
    <custom name/value pairs>
}

HTTP Method: DELETE§

Yesplan triggers an HTTP DELETE request to the configured url to remove a previously created production. The {id} is a required url parameter. A response status code of 204 (“No Content”) lets Yesplan know that the event was correctly removed. Any response with status code outside of the 2xx range is considered as a failure.

mandatory url parameter: {id}

Example URL: /api/productions/{id}

Same value for event-id and production-id§

It may occur that the value of the event-id and production-id are the same on the events calls.

{
    "event-id":"3432391937-1483009247",
    "production-id":"3432391937-1483009247",
    "name":"Test Event",
    "location":"Concert hall",
    "starttime":"2016-12-31T10:00:00+01:00",
    "endtime":"2016-12-31T12:00:00+01:00"
}

This is possible in 2 cases:

  1. in Yesplan the event is not grouped in a production
  2. productions are not supported by the ticketing software

Resource at URL /mappings§

The ticketing system can provide a set of mappings to be used with dropdown custom data fields in Yesplan. Each mapping provides, on one hand, a list of options for a dropdown in Yesplan and, on the other hand, a corresponding value for each option that Yesplan should use in requests to the ticketing system. For example, a mapping can specify options “Large Concert Hall” and “Small Concert Studio” with corresponding API values “ID-4A5DB421” and “ID-BE8F73CA”. In Yesplan, a user will see “Large Concert Hall” and “Small Concert Studio” as the options in a dropdown custom data field, while Yesplan communicates the selected option to the ticketing system as respectively “ID-4A5DB421” or “ID-BE8F73CA”.

Yesplan will request the mappings through a GET request on the /mappings URL. The ticketing system should respond with status code 200 (“OK”), and a JSON body structured as in the following example:

{ "Venues": [
    { "option": "Large Concert Hall",
      "apivalue": "ID-4A5DB421" },
    { "option": "Small Concert Studio",
      "apivalue": "ID-BE8F73CA" } ],
  "Event Type": [
    { "option": "Pop Concert",
      "apivalue": "type_pop_concert" },
    { "option": "Piano Recital",
      "apivalue": "type_piano_recital" } ] }

The mappings are given as a JSON object with name/value pairs where the name is the name of each mapping. In the above example, two mappings are given: “Venues” and “Event Type”. For each mapping, the value of the name/value pair is a JSON array, consisting of JSON objects with name/value pairs for “option” and “apivalue”. The values for “option” and “apivalue” must be strings. The mapping “Event Type” in the example has two options, “Pop Concert” and “Piano Recital”, which are respectively mapped to “type_pop_concert” and “type_piano_recital”.

A few important points:

Limited Implementations§

Servers are allowed to implement only a subset of the protocol:

Authentication§

The current implementation of the protocol in Yesplan supports basic HTTP authentication: all requests include a header Authorization with the scheme “Basic”.