Ticketland External API v.1.2

English - Русский

Index

Versions

2016-04-28 v.1.0
2016-05-24 v.1.1
1. Use DELETE requests instead of specific methods
2. "Customer" property in PUT /order request is optional
3. Changes at the selling scheme: instead of PUT /order -> GET /order -> POST /order/confirm now use PUT /order -> POST /order/sell (without payment information) -> GET /order
4. Fix formats in response (float values instead of strings, ticket object instead of array at order info)
2016-06-26 v.1.2
1. Added a new functionality that prevents multiple reservations without a purchase. Once a day (at 12:00AM) we consider the ratio of sold orders to create orders, if the created orders of 10 or more.
  • If ratio less than 0.3, then account gets ban for creating order until the next conversion (1006 "low karma" exception).
  • If ratio greater or equal to 0.3, then account has a standart set.
  • If ratio greater or equal to 0.7, the account has extended rights to set order expire time up to 24 hours.
  • If any orders has not been created per day, the ratio accept 0.5.
2. Added new optional parameter expireDateTime to method PUT /order, with which you can specify the desired cancellation datetime (but not later than 24 hours from current time).
2017-01-25 v.1.2.1
Use GET /service/karma for determining account privileges.
2017-04-24 v.1.2.2
We have first version of API Exceptions Document
2019-09-27 v.1.2.3
Method DELETE /ticket may consume return price that differs from nominal ticket price
2022-08-01 v.1.2.3
Add functionality for seatless sections

How to sell tickets

1 Browse performances using GET /repertoire method, and information about buildings (halls, sections etc.) using GET /constructive method.
1.1 There are data cache for repertoire information (30 minutes) and constructive information (60 minutes).
2 Get free tickets for performance using GET /ticket method.
2.1 There are caching on tickets states (5 minutes).
3 Create order with some tickets using PUT /order method.
3.1 Cancel non-confirmed orders (make locked places free) using DELETE /order method.
3.2 Places are automatically released after order expires.
4 Get information about order GET /order method.
5 Confirm order payment using POST /order/sell method. Tickets information (barcodes) will be provided in response.
5.1 To cancel a confirmed order, must be returned to each ticket sold separately in the order using DELETE /ticket method.
6 Get ticket barcodes using GET /order method after payment.
7 Change spectator data by order if necessary. PUT /spectator-info
scheme

Transport rules

Definitions

identity-id 2-chars identificator
control-hash-algorithm "D" (based on datetime value)
hash [int-unix-timestamp][sha-1-encrypted-value]
int-unix-timestamp 1461857409; service check for current time with some allowance
sha-1-encrypted-value result of SHA-1 string hashing "[salt][int-unix-timestamp]"
salt secret string

Request

GET|PUT|POST|DELETE /object[/action][?get-params=value]
Content-Type: application/json
Authorization: Bearer [identity-id][control-hash-algorithm][hash]

{"json-body": "for PUT or POST requests"}

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{"result": true, "tickets": []}

HTTP/1.1 401 Unauthorized
Content-Type application/json; charset=UTF-8
{"result": false, "code": 401, "message": "You are requesting with an invalid credential"}

HTTP/1.1 404 Not Found
Content-Type application/json; charset=UTF-8
{"result": false, "code": 404, "message": "Page not found."}

HTTP/1.1 405 Method Not Allowed
Content-Type application/json; charset=UTF-8
{"result": false, "code": 405, "message": ""}

Exceptions

PDF Document (v.240417)

Service objects

Repertoire

GET /repertoire
fromInclusive string with datetime format "yyyy-MM-ddTHH:mm:ss" optional
tillExclusive string with datetime format "yyyy-MM-ddTHH:mm:ss" optional 
GET /repertoire?fromInclusive=2016-05-01T00%3A00%3A00&tillExclusive=2016-06-01T00%3A00%3A00
{
    "result": true,
    "organizers": [
        {
            "id": 1031,
            "name": "Organizer name"
        }
    ],
    "shows": [
        {
            "id": 16578647,
            "name": "Show name",
            "type": "Show type",
            "minAge": "16+",
            "organizerId": 1031
        }
    ],
    "performances": [
        {
            "id": 24844994,
            "hallId": 31831,
            "showId": 19200279,
            "beginTime": "2016-04-30T19:00:00",
            "requiredSpectatorInfo": true
        },
        {
            "id": 24844992,
            "hallId": 31831,
            "showId": 16578648,
            "beginTime": "2016-04-28T19:00:00",
            "requiredSpectatorInfo": false
,    ]
}

Constructive

GET /constructive
hallId integer required
segment array of strings: [building|hall|sections|places] required 
GET /constructive?hallId=32068&segment[]=building&segment[]=hall&segment[]=sections&segment[]=places
{
    "hall": [
        {
            "id": 31831,
            "name": "Hall name",
            "buildingId": 4640,
            "isWithoutScheme": true
        }
    ],
    "building": [
        {
            "address": null,
            "buildingId": 4640,
            "buildingName": "Building name",
            "description": null,
            "metro": null,
            "ownerId": 1031,
            "path": null,
            "phone": null,
            "regionName": "Region name",
            "url": null,
            "workingHours": null
        }
    ],
    "sections": [
        {
            "id": 12567,
            "name": "Section name",
            "shortName": "SectName",
            "coordinates": null,
            "isSeatless": true
        }
    ],
    "places": [
        {
            "id": 3341302,
            "sectionId": 12567,
            "row": "--",
            "seat": "--",
            "coordinate": {
                "x": 200,
                "y": 250
            }
        }
    ]
}

Ticket

GET /ticket
performanceId integer required 
GET /ticket?performanceId=24856677
{
    "result": true,
    "tickets": [
        {
            "placeId": 3341306,
            "performanceId": 24844994,
            "price": 100.00,
            "taxId": 205814
        }
    ]
}
// for performances with free seating
{
    "result": true,
    "tickets": [
        {
            "placeId": 3341306,
            "performanceId": 24844994,
            "price": 100.00,
            "taxId": 205814
        }
    ],
    "sections": [
        {
            "sectionId": 123,
            "freeSeatsCount": 500,
            "price": 150.00,
            "taxId": 205814,
            "zoneId": 4,
            "performanceId": 24844994
        }
    ]
}
DELETE /ticket
id integer required
price float required
orderId integer required 
DELETE /ticket?id=999999&orderId=999&price=3500
{
    "result": true
}

Order

GET /order
id integer required 
GET /order?id=99999999
{
    "result": true,
    "id": 99999999,
    "expire": "2016-04-30T17:01:11",
    "performances": [
        {
            "performanceId": 24844284,
            "showName": "Show name",
            "dateStart": "2016-04-28T19:00:00"
        }
    ],
    "pinCode": null,
    "places": [
        {
            "ticket": {
                // this section will be displayed after the sale is completed by method /order/sell
                "barcode": "99192074",
                "blankNum": 0,
                "series": "*auto*",
                "ticketId": 99192074
            },
            "hallId": 563,
            "sectionId": 123, // only for performances with free seating
            "performanceId": 24844284,
            "placeId": 1352846,
            "placeName": "Place name",
            "price": 1800.00,
            "row": "3",
            "seat": "1",
            "sectionName": "Section name"
        }
    ],
    "isExpired": false
}
PUT /order
customer object Customer {"id":integer, "surname":string, "phone":string, "email":string} optional
If a customer object is passed, all fields are required but may be empty, id can be set in 0
tickets array of objects Ticket {"performanceId":integer, "placeId":integer, "price":float, "taxId":integer} required when sections is null
sections array of objects SeatlessSection {"performanceId":integer, "sectionId":integer, "freeSeatsCount":integer, "price":integer, "taxId":integer, "zoneId":integer} required when tickets is null
expireDateTime string with datetime format "yyyy-MM-ddTHH:mm:ss" optional
spectatorInfo Spectator information for DIT required, if the hall is included in the list of GBUK
spectatorsInfo Spectator information for DIT in the request for tickets with free seating required, if the hall is included in the list of GBUK
ditSpectatorId string (Spectator ID) required, if we transmit information about the spectator
surname string (Spectator surname) required, if we transmit information about the spectator
name string (Spectator name) required, if we transmit information about the spectator
middlename string (Spectator middlename) required, if we transmit information about the spectator
 
PUT /order
{
    "customer": {
        "id": 999,
        "surname": "Customer",
        "phone": "+79999999999",
        "email": "test@customer.ee"
    },
    "tickets": [
        {
            "performanceId": 24856677,
            "placeId": 3675264,
            "price": 4000,
            "taxId": 3531,
            "spectatorInfo":
              {
                "ditSpectatorId": "mts7755775",
                "surname": "Волков",
                "name": "Денис",
                "middlename": "Борисович"
              }
        }
    ],
    "expireDateTime": "2016-04-01T00:00:00"
}
// or Request for performances with free seating
{
    "customer": {
        "id": 999,
        "surname": "Customer",
        "phone": "+79999999999",
        "email": "test@customer.ee"
    },
    "sections": [
        {
            "performanceId": 24856677,
            "sectionId": 123,
            "freeSeatsCount": 5,
            "price": 500,
            "taxId": 3531,
            "zoneId": 1237831,
            "spectatorsInfo": [
                    {
                      "ditSpectatorId": "mts775577",
                      "surname": "Волков",
                      "name": "Денис",
                      "middlename": "Петрович"
                    },
                    {
                      "ditSpectatorId": "mts775578",
                      "surname": "Волкова",
                      "name": "Нина",
                      "middlename": "Петровна"
                    }
               ]
           }
       ],
    "expireDateTime": "2016-04-01T00:00:00",
    "promocode": "my-promo-code",
}

// Response with successfully created ticket
{
    "result": true,
    "locks": [
        {
            "exception": null,
            "price": 4000,
            "expireTime": '2022-07-29T15:18:47.543+03:00',
            "groupId": 321,
            "groupType": "Single",
            "performanceId": 24856677,
            "sectionId": 123, // only for performances with free seating
            "placeId": 3675264,
        }
    ],
    "order": {
        "orderId": 99999999,
        "expires": "2016-04-01T00:00:00"
    }
}

// Response with error (ticket not created, but "result" field is still "true" and order has ID)
{
    "result": true,
    "locks": [
        {
            "exception": {"some_error_message_property": "some value"},
            "performanceId": 24856677,
            "placeId": 3675264
        },
        {
            "exception": null,
            "performanceId": 24856677,
            "placeId": 3675265
        }
    ],
    "order": {
        "orderId": 99999999,
        "expires": "2016-04-01T00:00:00"
    }
}
POST /order/sell
id integer required
isPushkinCard boolean optional 
POST /order/sell
{
    "id": 999,
    "isPushkinCard": false,
}
{
    "result": true,
    "id": 999,
    "tickets": [
        {
            "performanceId": 20059,
            "placeId": 20049,
            "price": 2000.00,
            "sectionId": 123, // null|int
            "blank": {
                "barcode": "99192073",
                "blankNum": 0,
                "series": "*auto*",
                "ticketId": 99192073
            }
        }
    ]
}
PUT /spectator-info
orderId integer required
tickets array required
performanceId integer required
placeId integer required
ditSpectatorId string required
surname string required
name string required
middlename string optional 
PUT /spectator-info

{
  "orderId": "52403192",
  "tickets": [
    {
      "performanceId": "25931137",
      "placeId": "29737790",
      "spectatorInfo": {
        "ditSpectatorId": "mts2987233377",
        "surname": "Петров",
        "name": "Виктор",
        "middlename": "Николаевич"
      }
    }
  ]
}
                

{
  "result": true,
  "requestID": "67d29f784c26d"
}
DELETE /order
id integer required 
DELETE /order?id=999
{
    "result": true
}

Sales

GET /sales
fromInclusive string with datetime format "yyyy-MM-ddTHH:mm:ss" optional
tillExclusive string with datetime format "yyyy-MM-ddTHH:mm:ss", current time is maximum allowed value optional
*Time interval can not exceed 3 days
**If values not defined it returns previous day operations
 
GET /sales?fromInclusive=2016-05-30T00:00:00&tillExclusive=2016-05-31T00:00:00
{
    "tickets": [
        {
            "performanceId": 20059,
            "placeId": 20049,
            "orderId": 2049,
            "operationTime": "2015-05-30T15:45:23",
            "operationType": "sale",
            "price": 250.00,
            "sectionId": 123
        },
       {
            "performanceId": 20059,
            "placeId": 20049,
            "orderId": 2049,
            "operationTime": "2015-05-30T19:48:11",
            "operationType": "return",
            "price": 125.00,
            "sectionId": 123
        }
    ]
}

Service

GET /service/karma
karma: 1 account gets ban for creating order
karma: 2 account with default privileges
karma: 3 account with elevated privileges
 
GET /service/karma
{
    "account_id": 999,
    "karma": 3,
    "check_dt": "2016-10-17 21:00:01.000"
}