TICKETING SYSTEM PROTOCOL

API (All Powerful Incantation)
Release 14.12.2020

DESCRIPTION
GENERAL PROTOCOL USING PLAN
RESPONSE FORM
AUTHORIZATION (command = AUTH)
USER CREATION (command = CREATE_USER)*
GETTING THE LIST OF CITIES (command = GET_CITIES)
GETTING THE LIST OF VENUE TYPES (command = GET_VENUE_TYPES)
GETTING THE LIST OF VENUES (command = GET_VENUES)
GETTUNG THE LIST OF EVENTS (command = GET_ALL_ACTIONS)
GETTING THE LIST OF EVENTS (command = GET_ACTIONS_V2)
GETTING THE EVENT INFORMATION (command = GET_ACTION_EXT)
GETTING THE SEAT LIST BY THE SESSION ID (command = GET_SEAT_LIST)
GETTING SEAT COORDINATES BY THE SESSION ID (command = GET_SCHEMA)
ADDINF THE PROMOCODES (command = ADD_PROMO_CODES)
RESERVATION IN ASSIGNED SEATS (command = RESERVATION)
RESEVATION IN GENERAL ADMISSION (command = RESERVATION)
DELETE RESERVATION (command = RESERVATION)
GETTING THE LIST OF SEATS RESERVED (command = GET_CART)
CREATING AN ORDER (command = CREATE_ORDER)
CREATING AN ORDER (command = CREATE_ORDER_EXT)*
ORDER CANCELLING (command = CANCEL_ORDER)*
ORDER PAYMENT (command = PAY_ORDER)*
GETTING THE USER ORDERS (command = GET_ORDERS)
GETTING THE USER ORDERS (command = GET_ORDERS_EXT)
GETTING THE LIST OF SESSIONS WITH TICKETS SOLD (command = GET_ACTION_EVENTS_GROUPED_BY_TICKETS)
GETTING THE LIST OF TICKETS SOLD BY SESSION ID (command = GET_TICKETS_BY_ACTION_EVENT)
GETTING THE TICKETS SOLD BY ORDER ID (command = GET_TICKETS_BY_ORDER)
GETTING INFORMATION OF TICKETS SOLD DURING GIVEN DATE (command = GET_TICKETS_BY_DAY)
GETTING USER INFORMATION (command = GET_USER_INFO)
SENDING TICKETS BY EMAIL (command = SEND_TICKETS_TO_EMAIL)
DELETING (command = DELETE)
GETTING ORDER INFORMATION (command = GET_ORDER_INFO)
GETTING THE EMAIL ADDRESS (command = GET_EMAIL)
SENDING GCM TOKEN TO THE SERVER (command = SET_PUSH_TOKEN)
GETTING THE NEWS (command = GET_NEWS)
CHEKING THE EVENT ACCESS CODE (command = CHECK_KDP)
GETTING FILTER DATA (command = GET_FILTER)
BINDING THE EMAIL ADDRESS (command = BIND_EMAIL)
EMAIL ADDRESS CONFIRMATION (command = CONFIRM_EMAIL)
GETTING THE MOBILE ELECTRONIC CARDS (MEC) (command = GET_MECS)
GETTING THE PROMO CODES (command = GET_PROMO_CODES)
TICKET REFUNDING (command = REFUND_TICKETS)*
ORDER STATUS
PROTOCOL CHANGE LOG 09.05.2016
PROTOCOL CHANGE LOG 20.05.2016
PROTOCOL CHANGE LOG 15.06.2016
PROTOCOL CHANGE LOG 22.06.2016
PROTOCOL CHANGE LOG 23.06.2016
PROTOCOL CHANGE LOG 08.07.2016
PROTOCOL CHANGE LOG 22.07.2016
PROTOCOL CHANGE LOG 16.08.2016
PROTOCOL CHANGE LOG 02.09.2016
PROTOCOL CHANGE LOG 25.10.2016
PROTOCOL CHANGE LOG 25.11.2016
PROTOCOL CHANGE LOG 15.12.2016
PROTOCOL CHANGE LOG 27.12.2016
PROTOCOL CHANGE LOG 04.02.2017
PROTOCOL CHANGE LOG 05.05.2017
PROTOCOL CHANGE LOG 18.05.2017
PROTOCOL CHANGE LOG 08.06.2017
PROTOCOL CHANGE LOG 06.07.2017
PROTOCOL CHANGE LOG 13.07.2017
PROTOCOL CHANGE LOG 22.07.2017
PROTOCOL CHANGE LOG 09.08.2017
PROTOCOL CHANGE LOG 23.08.2017
PROTOCOL CHANGE LOG 02.10.2017
PROTOCOL CHANGE LOG 18.02.2018
PROTOCOL CHANGE LOG 01.03.2018
PROTOCOL CHANGE LOG 12.03.2018
PROTOCOL CHANGE LOG 19.08.2018
PROTOCOL CHANGE LOG 16.10.2018
PROTOCOL CHANGE LOG 06.12.2018
PROTOCOL CHANGE LOG 12.12.2018
PROTOCOL CHANGE LOG 23.04.2019
PROTOCOL CHANGE LOG 21.05.2019
PROTOCOL CHANGE LOG 10.06.2019
PROTOCOL CHANGE LOG 23.07.2019
PROTOCOL CHANGE LOG 13.08.2019
PROTOCOL CHANGE LOG 24.09.2019
PROTOCOL CHANGE LOG 11.06.2020

DESCRIPTION

Interaction is done by HTTPS POST requests in JSON format and encoded in UTF-8. Response is returned in JSON format and encoded in UTF-8. Test zone URL https://api.bil24.pro:1240/json
Real zone URL https://api.bil24.pro/json
Веб интерфейс для применения команд протокола

Field types:
int number – integer value ranged from -2 147 483 648 to 2 147 483 647
Uint nimber – unsigned integer value ranged from 0 to 2 147 483 647
long number – integer value ranged from -9 223 372 036 854 775 808 to 9 223 372 036 854 775 807
Ulong number – unsigned integer value ranged from 0 to 9 223 372 036 854 775 807
Cur number – real value, containg up to 2 sings after dot, e.g. 134.66
boolean – literal character, taking either true or false value
string – string value with unlimited length

This API is used by the following types of BIL24 agent interfaces types: Browser and Ticketing system.

GENERAL PROTOCOL USING PLAN

Protocol commands are split in sessional and non-sessional.
List of the non-sessional commands:
1. GET_FILTER
2. GET_CITIES
3. GET_VENUE_TYPES
4. GET_VENUES
5. GET_ALL_ACTIONS
6. GET_ACTIONS_V2
7. GET_ACTION_EXT
8. GET_SEAT_LIST
9. GET_TICKETS_BY_DAY

There is no necessity of using AUTH command before any of the commands listed. Session id (sessionId) is not needed for their performance.

Performing sessional commands requires session Id. It is initially received with command AUTH (CREATE_USER for ticketing systems). The user data received is recommended to be saved and re-used. User session is determined by sessionId and acts indefinitely.

Generally, sessionId would be needed before BIND_EMAIL (RESERVATION for ticketing systems).

You can use the fid, token, userId, and sessionId from the request examples when accessing the test zone at https://api.bil24.pro/json.

Interface "Ticketing system"
fid: 1184
token: 24d3b97b64dfab187a5f
userId: 18109
sessionId: d6035a755bd0862e713e03f337505bd0

Interface "Browser"
fid: 1185
token: 2f1173e2b12fd5a111b6
userId: 6104
sessionId: 19c517c212bf173b44558308149db8ca

RESPONSE FORM

Result in JSON format Is returned to all requests:
{
 "resultCode": 0,
 "description": "OK"
 "command": "COMMAND"
 …………………………
}

Field Type Required Description
resultCode Int Yes Result of request
description String Yes Description
command String Yes Command sent through the request

These fields are present in any response.
If resultCode isn’t 0, then description field contains error description. Other fields won’t be present.
ResultCode field values:

Value Description

-1

Unexpected error (protocol error, data transfer error, etc.), look up description in description field

0

Successful result

1

Session identifiers are wrong (userId or sessionId)

Messages displayed to user

101 Regular message
102 Email isn’t bound. Check during RESERVATION requests

DURING EVERY REQUEST these two fields are obligated to be indicated:

Field Type Required Description
fid Ulong Yes Interface id (frontend id)
token String Yes Interface token


AUTHORIZATION (command = AUTH)

Description: user authorization. Method CREATE_USER has to be used for Ticketing system interface type instead.
Request fields:

Field Type Required Description
command String Yes AUTH
userId Ulong Yes, if sessionId is present User id in ticketing system
sessionId String Yes, if userId is present User session id

Response fields content:

Field Type Required Description
userId Ulong Yes User id in ticketing system
sessionId String Yes User session id
frontendType Uint Yes Interface type

Request data is received through cookies, if given request happened before. If request happens for the first time, then userId and sessionId aren’t transferred through request.
Request example:
{
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "command": "AUTH",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}
Response example:
{
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "command": "AUTH",
 "frontendType": 4,
 "resultCode": 0,
 "description": "OK"
}
After getting the response, saving the data and using it in requests where this fields are necessary is required.

USER CREATION (command = CREATE_USER)*

Description: method creates new user, which can further be used for seat reservation, creating orders and paying for them. Method is used instead of AUTH method for Ticketing system interface type.
*only for the Ticketing system interface type

Request fields:

Field Type Required Description
command String Yes CREATE_USER

Response fields content

Field Type Required Description
userId Ulong Yes User id in ticketing system
sessionId String Yes User session id

Request example:
{
 "command": "CREATE_USER",
 "fid": 1184,
 "token": "24d3b97b64dfab187a5f"
}
Response example:
{
 "userId": 18109,
 "sessionId": "d6035a755bd0862e713e03f337505bd0",
 "command": "CREATE_USER",
 "resultCode": 0,
 "description": "OK"
}
After getting the response, saving the data and using it in requests where this fields are necessary is required.

GETTING THE LIST OF CITIES (command = GET_CITIES)

Description: getting the list of all the cities available in the system. In order to only get cities where actual events are scheduled GET_FILTER have to be used. Using the GET_FILTER method is preferable.
Request fields:

Field Type Required Description
command String Yes GET_CITIES

Response fields content:

Field Type Required Description
cityList Array Yes List of cities

cityList:

Field Type Required Description
cityId Ulong Yes City id in the ticketing system
cityName String Yes City name in the ticketing system

Request example:
{
 "command": "GET_CITIES",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}
Response example:
{
 "cityList": [
  {
   "cityId": 1,
   "cityName": "Sochi"
  },
  {
   "cityId": 2,
   "cityName": "Krasnodar"
  }
 ],
 "command": "GET_CITIES",
 "resultCode": 0,
 "description": "OK"
}

GETTING THE LIST OF VENUE TYPES (command = GET_VENUE_TYPES)

Descripton: Getting the list of all venue types available in the system.
Request fields:

Field Type Required Description
command String Yes GET_VENUE_TYPES

Response fields content:

Field Type Required Description
venueTypeList Array Yes List of venue types

venueTypeList:

Field Type Required Description
venueTypeId Uint Yes Venue type id
venueTypeName String Yes Venue type name


GETTING THE LIST OF VENUES (command = GET_VENUES)

Descripton: Getting the list of all venues, available in the system. In order to get actual venues, GET_FILTER have to be used.
Request fields:

Field Type Required Description
command String Yes GET_VENUES
cityId Ulong Yes City id in the ticketing system
venueTypeId Uint No Venue type id, if not present,
then response will contain all venues

Response fields content:

Field Type Required Description
venueList Array Yes List of venues

venueList:

Field Type Required Description
venueId Ulong Yes Venue id
venueName String Yes Venue name
venueTypeId Uint Yes Venue type id
venueTypeName String Yes Venue type name
address String Yes Venue address
geoLat String (##.######) Yes Venue latitude
geoLon String (##.######) Yes Venue longitude
imageUrl String Yes Link to the image of the venue
description String Yes Description of the venue


GETTING THE LIST OF EVENTS (command = GET_ALL_ACTIONS)

Descripton: Method returns all the data of method GET_FILTER and the list of all events available. Method allows not using of GET_FILTER, GET_ACTIONS_V2 and GET_ACTION_EXT.
*only for the Ticketing system interface type


Request fields:

Field Type Required Description
command String Yes GET_ALL_ACTIONS

Response fields content

Field Type Required Description
cityList Array Yes list of cities
kindList Array Yes list of kinds
actionList Array Yes list of events

cityList:

Field Type Required Description
cityId Ulong Yes City id
cityName String Yes City name
venueList Array Yes List of venues

venueList:

Field Type Required Description
venueId Ulong Yes Venue id
venueName String Yes Venue name
address String Yes Venue address
geoLat String (##.######) Yes Venue latitude
geoLon String (##.######) Yes Venue longitude
imageUrl String Yes Link to the image of the venue

kindList:

Field Type Required Description
kindId Uint Yes Kind id
kindName String Yes Kind name

actionList:

Field Type Required Description
actionId Ulong Yes Event id
actionName String Yes Event short title
fullActionName String Yes Event full title
kindId Uint Yes Kind id
kindName String Yes Kind name
organizerId Ulong Yes Event organizer id
organizerName String Yes Event organizer name
legalOwner String Yes Promoter
legalOwnerName String Yes Promoter name
legalOwnerInn String Yes Promoter ITN
legalOwnerPhone String Yes Promoter phone number
duration Uint Yes Duration of event (minutes)
posterName String Yes Poster name
description String Yes Descripton
smallPosterUrl String Yes Poster image url (320 x 335)
bigPosterUrl String Yes Poster image url (640 x 670)
bookletUrl String No Event brochure url
kdp* boolean Yes True: event has an access code
rating Uint Yes Rating from 0 to 10
age String Yes Age restriction
actionEventList Array Yes List of sessions

actionEventList:

Field Type Required Description
actionEventId Ulong Yes Session id
day String Yes Session date dd.MM.yyyy
time String Yes Session time HH:mm
cityId Ulong Yes City id
venueId Ulong Yes Venue id
seatingPlanId Ulong Yes Seating plan id
seatingPlanName String Yes Seating plan name
placementUrl String No Seating plan url. If field is empty, then it is general admission
eTicket boolean Yes If false, METs (Mobile Electronic Tickets) are not available
fullNameRequired boolean Yes if true, fullName (full customer name) is required during order
phoneRequired boolean Yes if true, phone (customer phone number) is required during order
tariffPlanList Array Yes Tariff plan list
categoryLimitList Array Yes Category list, grouped by limit size (general admission)

tariffPlanList:

Field Type Required Description
tariffPlanId Ulong Yes Tariff plan id
tariffPlanName String Yes Tariff plan name

categoryLimitList:

Field Type Required Description
remainder Uint No General seat limit by category list.
If empty, look availability
categoryList Array Yes Category list, grouped by same limit

categoryList:

Field Type Required Description
categoryPriceId Ulong Yes Category price id
categoryPriceName String Yes Price category name
price Cur Yes Price category cost
tariffIdMap Associative array Yes Tariff list, key – tariff id, value - cost
availability Int Yes Number of places available in the category




GETTING THE LIST OF SESSIONS (command = GET_ACTIONS_V2)

Descripton: method returns the list of sessions in the city. It is recommended to use GET_ALL_ACTIONS for the Ticketing system interface instead of this method.
Request fields:

Field Type Required Description
command String Yes GET_ACTIONS_V2
cityId Ulong Yes City id

Response fields content

Field Type Required Description
actionList Array Yes list of events

actionList:

Field Type Required Description
actionId Ulong Yes Event id
actionName String Yes Event short title
fullActionName String Yes Event full title
duration Uint Yes Duration of event (minutes)
kindId Uint Yes Kind id
kindName String Yes Kind name
posterName String Yes Poster name
smallPosterUrl String Yes Poster image url (320 х 335)
bigPosterUrl String Yes Poster image url (640 х 670)
minSum Cur Yes Minimal session price
firstEventDate String Yes First session date
lastEventDate String Yes Last session date
rating Uint Yes Rating from 0 to 10
kdp boolean Yes true - event has an access code*
cityId Ulong Yes City id, sent through the request
cityName String Yes City name
actionEventTime String No HH:mm format.
Field exists, if the all the sessions happen at the same time
venueMap Associative array Yes List of venues. key - venueId, value - venueName


* Access code information: Before opening the seating plan or pushing the reservation button (in general admission) user have to type in the access code (Method for checking access code - CHECK_KDP)
Request example:
{
 "cityId": 1,
 "command": "GET_ACTIONS_V2"
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}
Request example:
{
 "actionList": [
  {
    "actionId": 193,
    "actionName": "Lubov Uspenskaya",
    "fullActionName": "The Queen of city romance",
    "duration": 120,
    "kindId": 0,
    "kindName": "Events",
    "posterName": "Poster name",
    "smallPosterUrl": "https://api.bil24.pro:1240/image?type=smallPoster&actionId=193&hash=gznpw8zi9rog7k7e923ko32ap",
    "bigPosterUrl": "https://api.bil24.pro:1240/image?type=bigPoster&actionId=193&hash=hwyb7h53x926q0tiiopdgjpp0",
    "minSum": 1500,
    "firstEventDate": "27.05.2016",
    "lastEventDate": "27.05.2016",
    "rating": 10,
    "kdp": false,
    "cityId": 1,
    "cityName": "Sochi",
    "actionEventTime": "19:30",
    "venueMap": {
     "1": "Zimnii Theatre"
    }
  },
  {
    "actionId": 219,
    "actionName": "Karmen",
    "fullActionName": "Ice musical",
    "duration": 180,
    "kindId": 0,
    "kindName": "Events",
    "posterName": "Poster name",
    "smallPosterUrl": "https://api.bil24.pro:1240/image?type=smallPoster&actionId=219&hash=sc8zn3tgamlvtpdjbgprv3dy2",
    "bigPosterUrl": "https://api.bil24.pro:1240/image?type=bigPoster&actionId=219&hash=qwejy8em5q5clku76dyxshd58",
    "minSum": 1000,
    "firstEventDate": "10.06.2016",
    "lastEventDate": "02.10.2016",
    "rating": 10,
    "kdp": false,
    "cityId": 1,
    "cityName": "Sochi",
    "actionEventTime": "18:30",
    "venueMap": {
     "7": "\"Iceberg\" Ice Palace"
    }
  }
 ],
  "command": "GET_ACTIONS_V2",
  "resultCode": 0,
  "description": "OK"
}

GETTING SESSION INFORMATION (command = GET_ACTION_EXT)

Descripton: Method returns the information about event in the specific city, venues it is available and sessions. It is recommended to use GET_ALL_ACTIONS for the Ticketing system interface instead of this method.>
Request fields:

Field Type Required Description
command String Yes GET_ACTION_EXT
cityId Ulong Yes City id
actionId Ulong Yes Event id
userId* Ulong No User id


* userId - seating plan will have user seats colored
Response fields content

Field Type Required Description
action Object Yes Event

action:

Field Type Required Description
actionId Ulong Yes Event id
actionName String Yes Event short title
fullActionName String Yes Event full title
kindId Uint Yes Kind id
kindName String Yes Kind name
cityId Ulong Yes City id
cityName String Yes City name
organizerId Ulong Yes Event organizer id
organizerName String Yes Event organizer name
legalOwner String Yes Promoter
legalOwnerName String Yes Promoter name
legalOwnerInn String Yes Promoter ITN
legalOwnerPhone String Yes Promoter phone number
posterName String Yes Poster name
duration Uint Yes Duration of event (minutes)
description String Yes Descripton
smallPosterUrl String Yes Poster image url (320 x 335)
bigPosterUrl String Yes Poster image url (640 x 670)
bookletUrl String No Event brochure url
kdp* boolean Yes True: event has an access code
rating Uint Yes Rating from 0 to 10
age String Yes Age restriction
venueList Array Yes List of venues

*Access code: If true, then seats can only be reserved by entering access code.
venueList:

Field Type Required Description
venueId Ulong Yes Venue id
venueName String Yes Venue name
address String Yes Venue address
geoLat String (##.######) Yes Venue latitude
geoLon String (##.######) Yes Venue longitude
imageUrl String Yes Venue image url
description String Yes Venue description
cityPass boolean Yes If true, then discounts and
preferences are applied at this venue
actionEventList Array Yes List of sessions

actionEventList:

Field Type Required Description
actionEventId Ulong Yes Session id
day String Yes Session date dd.MM.yyyy
time String Yes Session time HH:mm
seatingPlanId Ulong Yes Seating plan id
seatingPlanName String Yes Seating plan name
placementUrl String No Seating plan url.
If not present, then it is general admission
eTicket boolean Yes If false, METs (Mobile Electronic Tickets) are not available
tariffPlanList Array Yes Tariff plan list
categoryLimitList Array Yes List of categories, grouped by limit
size (general admission)

There are 3 types of seating plans:
1. General admission only. placementUrl won’t be present, look up categoryLimitList
2. Assigned seats only. Look up placementUrl, categoryLimitList will be empty
3. Combined. Look up both placementUrl and categoryLimitList

tariffPlanList:

Field Type Required Description
tariffPlanId Ulong Yes Tariff plan id
tariffPlanName String Yes Tariff plan name



categoryLimitList:

Field Type Required Description
remainder Uint No General limit size by category list.
If not present, look up availability
categoryList Array Yes List of categories, grouped by same limit



categoryList:

Field Type Required Description
categoryPriceId Ulong Yes Category price id
categoryPriceName String Yes Price category name
price Cur Yes Price category cost
tariffIdMap Associative array Yes Tariff list, key – tariff id, value - cost
availability* Int Yes Number of places available in the category



*availability - number of seats available in the category. if remainder not present, we focus on availability. If remainder is present, then these parameters should be used carefully. For example, general limit of remainder on 3 categories may be 100, but the availability in every category may be 100 as well.

Session list actionEventList is returned sorted by date.

Request example:
{
 "cityId": 1,
 "actionId": 80,
 "userId": 6104,
 "command": "GET_ACTION_EXT",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}
Request example:
{
 "action": {
  "actionId": 193,
  "actionName": "Lubov Uspenskaya",
  "fullActionName": "The Queen of city romance",
  "kindId": 0,
  "kindName": "Events",
  "cityId": 1,
  "cityName": "Sochi",
  "duration": 120,
  "posterName": "The Queen of city romance ",
  "description": ""True love"",
  "smallPosterUrl": "https://api.bil24.pro:1240/image?type=smallPoster&actionId=193&hash=gznpw8zi9rog7k7e923ko32ap",
  "bigPosterUrl": "https://api.bil24.pro:1240/image?type=bigPoster&actionId=193&hash=hwyb7h53x926q0tiiopdgjpp0",
  "rating": 10,
  "kdp": false,
  "venueList": [
    {
    "venueId": 1,
    "venueName": "Zimnii Theatre",
    "address": "Sochi, Teatralnaya st., 2",
    "geoLat": "43.572313",
    "geoLon": "39.730626",
    "imageUrl": "https://api.bil24.pro:1240/image?type=venue&id=1&hash=rrre3fih28k8n68kmjwkdhe91",
    "description": "Every city has it’s business card.".",
    "actionEventList": [
     {
      "actionEventId": 681,
      "day": "27.05.2016",
      "time": "19:30",
      "placementUrl": "https://api.bil24.pro:1240/image?type=seatingPlan&userId=21173&actionEventId=681",
      "eTicket": true,
      "categoryLimitList": []
     }
     ]
   }
   ]
 },
 "command": "GET_ACTION_EXT",
 "resultCode": 0,
 "description": "OK"
}

GETTINT THE SEAT LIST BY THE SESSION ID (command = GET_SEAT_LIST)

Request fields:

Field Type Required Description
command String Yes GET_SEAT_LIST
actionEventId Ulong Yes Session id
availableOnly boolean No If present and true, only seats
available for purchase will be returned

Response fields content

Field Type Required Description
actionEventId Ulong Yes Session id
availableOnly boolean Yes If true, response only contains
seats available for purchase
tariffPlanList Array Yes Tariff plan list
categoryList Array Yes List of price categories
categoryLimitList Array No Category list, grouped by limit size (general admission)
seatList Array Yes List of seats

tariffPlanList:

Field Type Required Description
tariffPlanId Ulong Yes Tariff plan id
tariffPlanName String Yes Tariff plan name

categoryList:

Field Type Required Description
categoryPriceId Ulong Yes Category price id
categoryPriceName String Yes Price category name
price Cur Yes Price
tariffIdMap Associative array Yes Tariff list, key – tariff id, value - cost
availability Int Yes Number of places available in the category

categoryLimitList:

Field Type Required Description
remainder Uint No General limit size by category list. If not present, look up availability
categoryList Array Yes List of categories, grouped by the same limit size

seatList:

Field Type Required Description
seatId Ulong Yes Seat id
categoryPriceId Ulong Yes Category price id
price Cur Yes Price
placement boolean Yes If true then seat has coordinates
location Object Yes, if placement=true Seat coordinates
available boolean Yes If true then seat is available for purchase

location:

Field Type Required Description
sector String Yes Sector
row String Yes Row
number String Yes Number



GETTING THE SEAT COORDINATES BY THE SESSION ID (command = GET_SCHEMA)

Descripton: method returns information about all the assigned seats with coordinates of each in order to create new seating plan. It is recommended to use it only when you can’t use the prepared seating plans, which you can also receive via protocol.

Request fields:

Field Type Required Description
command String Yes GET_SCHEMA
actionEventId Ulong Yes Session id


Response fields content

Field Type Required Description
actionEventId Ulong Yes Session id
seatList Array Yes List of seats with their coordinates

seatList:

Field Type Required Description
seatId Ulong Yes Seat id
sector String Yes Sector
row String Yes Row
number String Yes Number
x String Yes Real value, coordinate on X-axis (from left to right)
y String Yes Real value, coordinate on Y-axis (top down)





ADDING THE PROMOCODES (command = ADD_PROMO_CODES)

Descripton: Adding the promo codes for user to apply. Up to 10 promo codes can be added per single action. Case of characters doesn’t matter. Response will contain same number of promo codes, written in the same case, split into 3 groups: new promo codes for user, already existing promo codes and promo codes with errors.

Request fields:

Field Type Required Description
command String Yes ADD_PROMO_CODES
userId Ulong Yes User id in the Ticketing system
sessionId String Yes User session id
promoCodeList Array Yes List of promo codes


Response fields content

Field Type Required Description
newPromoCodeList Array Yes List of new promo codes added
existPromoCodeList Array Yes List of already existing promo codes
errorPromoCodeList Array Yes List of promo codes with errors




RESERVATION IN ASSIGNED SEATS (command = RESERVATION)

Descripton: reservation in assigned seats. Before ordering at least one seat has to be reserved. If an error occurs, it is guaranteed, that no seat from the list was reserved (transactional features of reserving). If the list of seats contains seats which were successfully reserved earlier, they are removed from the list. All of the seats have to belong to the same session.

Request fields:

Field Type Required Description
command String Yes RESERVATION
userId Ulong Yes User id in the Ticketing system
sessionId String Yes User session id
seatList Array Yes List of every reserved seat id
tariffMap Associative array No Allows reserving of some seats from seatList using the tariff plan ,
key – seat id, value - tariff plan id
kdp Int No Access Code
type String Yes RESERVE_BY_PLACE


Response fields content

Field Type Required Description
type String Yes RESERVE_BY_PLACE
seatList Array Yes List of every seat reserved by user
cartTimeout Uint Yes The amount of time reservation is active,
after which all of the user reservations are dismissed


seatList:

Field Type Required Description
seatId Ulong Yes Seat id
categoryPriceId Ulong Yes Category price id
tariffPlanId Ulong No Tariff plan id, present if tariff plan is applied
price Cur Yes Price (considering the chosen tariff plan)
placement boolean Yes If true, then seat has coordinates
location Object Обязательное, если placement = true Seat coordinates
available boolean Yes true


location:

Field Type Required Description
sector String Yes Sector
row String Yes Row
number String Yes Number


Request example:
{
 "type": "RESERVE_BY_PLACE",
 "seatList": [
    100
 ],
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "command": "RESERVATION",
 "fid": 1185,
  "token": "2f1173e2b12fd5a111b6"
}
Request example:
{
 "type": "RESERVE_BY_PLACE",
 "command": "RESERVATION",
 "resultCode": 0,
 "description": "OK"
}

RESERVATION IN GENERAL ADMISSION (command = RESERVATION)

Descripton: Reservation in general admission. Before ordering at least one place has to be reserved. If an error occurs, it is guaranteed, that no place from the list was reserved (transactional features of reserving). Reserving is proceeded by indicating the price category and the number of seats in given category. While reserving seats in multiple price categories, all of the categories have to belong to the same session. Price categories have to be in general admission, either way the method of reserving assigned seats has to be used.

Request fields:

Field Type Required Description
command String Yes RESERVATION
userId Ulong Yes User id
sessionId String Yes User session id
categoryQuantityMap Associative array Yes key - category id,
value - number of places for reserving
tariffMap Associative array No Allows reserving of some
categories from categoryQuantityMap
using the tariff plan
key – category id, value – tariff plan id
kdp Int No Access Code
type String Yes RESERVE


Response fields content:

Field Type Required Description
type String Yes RESERVE
seatList Array Yes List of all seats reserved by user
cartTimeout Uint Yes The amount of time reservation is active,
after which all of the user reservations are dismissed


seatList:

Field Type Required Description
seatId Ulong Yes Seat id
categoryPriceId Ulong Yes Category price id
tariffPlanId Ulong No Tariff plan id, present if tariff plan is applied
price Cur Yes Price (considering tariff plan chosen)
placement boolean Yes If true, the seat has coordinates
location Object Yes, if placement = true Seat coordinates
available boolean Yes true


location:

Field Type Required Description
sector String Yes Sector
row String Yes Row
number String Yes Number


Request example:
{
 "type": "RESERVE",
 "categoryQuantityMap": {
   "1072": 1
 },
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "command": "RESERVATION",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6",
 "kdp": 123
}
Request example:
{
 "type": "RESERVE",
 "command": "RESERVATION",
 "resultCode": 0,
 "description": "OK"
}

DELETE RESERVATION (command = RESERVATION)

Request fields:

Field Type Required Description
command String Yes RESERVATION
userId Ulong Yes User id
sessionId String Yes User session id
actionEventId Ulong No Session id, used for type = UN_RESERVE_ALL
seatList Array Yes, if type = UN_RESERVE List of every seat id
type String Yes UN_RESERVE, UN_RESERVE_ALL


Response fields content

Field Type Required Description
type String Yes type, sent through the request
seatList Array Yes List of every seat reserved by user
cartTimeout Uint Yes The amount of time reservation is active,
after which all of the user reservations are dismissed


seatList:

Field Type Required Description
seatId Ulong Yes Seat id
categoryPriceId Ulong Yes Category price id
tariffPlanId Ulong No Tariff plan id, present if tariff plan is applied
price Cur Yes Price
placement boolean Yes If true, then seat has coordinates
location Object Yes, if placement-true Seat coordinates
available boolean Yes true


location:

Field Type Required Description
sector String Yes Sector
row String Yes Row
number String Yes Number


Example 1: delete all seats in reservation:
{
 "type": "UN_RESERVE_ALL",
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "command": "RESERVATION",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}
Example 2. delete all seats on a specific session in reservation:
{
 "type": "UN_RESERVE_ALL",
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "actionEventId": 5,
 "command": "RESERVATION"
}
Example 3. delete a list of seats in reservation:
{
 "type": "UN_RESERVE",
 "seatList": [
   4790
 ],
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "command": "RESERVATION",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}
Request example:
{
 "command": "RESERVATION",
 "type": "UN_RESERVE",
 "resultCode": 0,
 "description": "OK"
}

GETTING THE LIST OF SEATS RESERVED (command = GET_CART)

Descripton: method returns all the seats reserved by user, grouped by sessions.

Request fields:

Field Type Required Description
command String Yes GET_CART
userId Ulong Yes User id
sessionId String Yes User session id
rawCoordinates boolean No If present and true, then fields
sector, row, number, would have
standard values in response (like everywhere else).
It is recommended to always send “true”.


Response fields content:

Field Type Required Description
totalSum Cur Yes Total cost of all reservations
time Uint Yes The amount of time reservation is active,
after which all of the user reservations are dismissed
totalServiceCharge Cur Yes Total service charge in a cart
actionEventList Array Yes List of sessions with seats reserved on them


actionEventList:

Field Type Required Description
actionEventId Ulong Yes Session id
day String Yes Session date dd.MM.yyyy
time String Yes Session time HH:mm
actionId Ulong Yes Event id
actionName String Yes Event short title
fullActionName String Yes Event full title
smallPosterUrl String Yes Poster image url (320 х 335)
bigPosterUrl String Yes Poster image url (640 х 670)
cityId Ulong Yes City id
cityName String Yes City name
venueId Ulong Yes Venue id
venueName String Yes Venue name
seatList Array Yes List of seats reserved
serviceCharge Cur Yes Service charge on session
fullNameRequired boolean Yes if true, fullName (full customer name) is required during order
phoneRequired boolean Yes if true, phone (customer phone number) is required during order


seatList:

Field Type Required Description
seatId Ulong Yes Reserved seat id
categoryPriceId Ulong Yes Category price id
categoryPriceName String Yes Category price name
tariffPlanId Ulong No Tariff plan id. Is present if applied.
tariffPlanName String No Tariff plan name. Is present if applied.
sector* String No Sector
row* String No Row
number* String No Number
nominal Cur Yes Nominal cost (considering the chosen tariff plan)
price Cur Yes Price (including discount)
serviceCharge Cur Yes Service charge on the seat
discount boolean Yes Indicates whether or not discount was applied. If false, then price equals nominal. If true, then discountReason is present in the response.
discountReason String No The reason for discount, if discount is true.


*If seating plan is assigned seats then response will contain sector, row, number fields.

Request example:
{
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "command": "GET_CART",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}
Request example:
{
 "time": 588,
 "totalSum": 1200,
 "totalServiceCharge": 0,
  "actionEventList": [
  {
   "actionEventId": 344,
   "day": "02.06.2016",
   "time": "18:00",
   "actionName": "SOPRANO SHOW",
   "fullActionName": "Mihail Tureczky introduces the night of love",
   "smallPosterUrl": "https://api.bil24.pro:1240/image?type=smallPoster&actionId=80&hash=r9qfi771jid3pf0or7vxc8xrb",
   "bigPosterUrl": "https://api.bil24.pro:1240/image?type=bigPoster&actionId=80&hash=m3b37t9tynyes52fxx7zw6gdl",
   "cityId": 1,
   "cityName": "Sochi",
   "venueId": 10,
   "venueName": "Zimnii theatre",
   "serviceCharge": 0,
   "seatList": [
    {
      "seatId": 524692,
     "categoryPriceName": "Sixth",
     "price": 600,
     "sector": "Parterre sector",
     "row": "Row 9",
     "number": "Number 11",
     "serviceCharge": 0
     },
    {
     "seatId": 524691,
     "categoryPriceName": "Sixth",
      "price": 600,
     "sector": "Parterre sector",
     "row": "Row 9",
      "number": "Number 10",
     "serviceCharge": 0
    }
    ]
   }
  ],
 "command": "GET_CART",
 "resultCode": 0,
 "description": "OK"
}

CREATING AN ORDER (command = CREATE_ORDER)

Описание: creating an order of seats reserved. CREATE_ORDER_EXT method has to be used for the Ticketing system interface.

Request fields:

Field Type Required Description
command String Yes CREATE_ORDER
userId Ulong Yes User id in the Ticketing system
sessionId String Yes User session id
email String No Email to which tickets have to be sent.
(For ticketboxes and invitations only)
phone String No Customer phone number
fullName String No Customer full name which
would appear on the tickets.
successUrl String Yes Successful payment operation redirects to successUrl.
failUrl String Yes Unsuccessful payment operation redirects to failUrl.
discount Cur No Discount in %.
(For ticketboxes and invitations only)
serviceCharge Cur No Service charge in %.
(For ticketboxes only)

Response fields content:

Field Type Required Description
formUrl String Yes Payment link
orderId Ulong Yes Order id
paid Field is obsolete true – order is already paid for
status Int Yes Order status
statusExtStr String Yes Order status
statusExtInt Int Yes Order status

Request example:
{
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "successUrl": "https://site.ru/success.php",
 "failUrl": "https://site.ru/fail.php",
 "command": "CREATE_ORDER",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}
Request example:
{
 "formUrl": "https://test.paymentgate.ru/testpayment/merchants/bil24/mobile_payment_ru.html?mdOrder=b8bb4b76-3a73-4816-92d4-954aa7d01e&pageView=MOBILE",
 "statusExtStr": "NEW",
 "statusExtInt": 0,
 "command": "CREATE_ORDER",
 "resultCode": 0,
 "description": "OK"
}

CREATING AN ORDER (command = CREATE_ORDER_EXT)*

Descripton: Creating an order of seats reserved. Used instead of CREATE_ORDER for the Ticketing system interface. Receives the NEW status after creating an order.
*only for the Ticketing system Interface

Request fields:

Field Type Required Description
command String Yes CREATE_ORDER_EXT
userId Ulong Yes User id in the Ticketing system
sessionId String Yes User session id
longReservation boolean No True – long-term reservation
email String No Email to which tickets have to be sent.
phone String No Customer phone number
fullName String No Customer full name which will appear on the tickets
discountPercent Cur No Discount percentage from 0 to 100.
chargePercent Cur No Service charge percentage, no less than 0.

Response fields content

Field Type Required Description
orderId Ulong Yes Order id
externalOrderId Array Yes List of string order identifiers in External Ticketing systems
discount Cur Yes Discount in RUR
serviceCharge Cur Yes Service charge in RUR
sum Cur Yes Total nominal cost, without including
discount and service charge.
totalSum Cur Yes Total cost
quantity Uint Yes Number of tickets in order
orderTimeout Int Yes Order timeout in minutes.

Request example:
{
 "userId": 18109,
 "sessionId": "d6035a755bd0862e713e03f337505bd0",
 "command": "CREATE_ORDER_EXT",
 "fid": 1184,
 "token": "24d3b97b64dfab187a5f"
}
Request example:
{
 "orderId": 64,
 "discount": 10,
 "serviceCharge": 99,
 "sum": 1000,
 "totalSum": 1089,
 "quantity": 5,
 "command": "CREATE_ORDER_EXT",
 "resultCode": 0,
 "description": "OK"
}

ORDER CANCELLATION (command = CANCEL_ORDER)*

Descripton: Cancelling an earlier created order. Only orders with NEW status can be cancelled. Request will result in order having CANCELLING or CANCELLED status. If an attempt to cancel an order with status other than NEW happens, there’ll be no error, order status won’t change, and the actual order status will be received via response. When order status becomes CANCELLED then seats, reserved in order, become available.
*Only for the Ticketing system interface

Request fields:

Field Type Required Description
command String Yes CANCEL_ORDER
userId Ulong Yes User id in the Ticketing system
sessionId String Yes User session id
orderId Ulong Yes Order id

Response fields content:

Field Type Required Description
orderId Ulong Yes Order id
statusExtStr String Yes Order status
statusExtInt Int Yes Order status

Request example:
{
 "orderId": 64,
 "userId": 18109,
 "sessionId": "d6035a755bd0862e713e03f337505bd0",
 "command": "CANCEL_ORDER",
 "fid": 1184,
 "token": "24d3b97b64dfab187a5f"
}
Request example:
{
 "orderId": 64,
 "statusExtStr": "CANCELLED",
 "statusExtInt": -2,
 "command": "CANCEL_ORDER",
 "resultCode": 0,
 "description": "OK"
}

ORDER PAYMENT (command = PAY_ORDER)*

Descripton: payment of an earlier created order. Only an order with NEW status can be paid. Request will result in order having either PROCESSING or PAID status. If an attempt to cancel an order with status other than NEW happens, there’ll be no error, order status won’t change, and the actual order status will be received via response.
*Only for the Ticketing system interface

Request fields:

Field Type Required Description
command String Yes PAY_ORDER
userId Ulong Yes User id in the Ticketing system
sessionId String Yes User session id
orderId Ulong Yes Order id

Response fields content:

Field Type Required Description
orderId Ulong Yes Order id
statusExtStr String Yes order status
statusExtInt Int Yes order status

Request example:
{
 "orderId": 64,
 "userId": 18109,
 "sessionId": "d6035a755bd0862e713e03f337505bd0",
 "command": "PAY_ORDER",
 "fid": 1184,
 "token": "24d3b97b64dfab187a5f"
}
Request example:
{
 "orderId": 64,
 "statusExtStr": "PAID",
 "statusExtInt": 2,
 "command": "PAY_ORDER",
 "resultCode": 0,
 "description": "OK"
}

GETTING THE USER ORDERS (command = GET_ORDERS)

Request fields:

Field Type Required Description
command String Yes GET_ORDERS
userId Ulong Yes User id in the Ticketing system
sessionId String Yes User session id

Response fields content:

Field Type Required Description
orderList Array Yes List of orders

orderList:

Field Type Required Description
orderId Ulong Yes id заказа в БС
date String Yes Date of creating an order in datePattern format
datePattern String Yes Date pattern
discount Cur Yes Discount in RUR
serviceCharge Cur Yes Service charge in RUR
sum Cur Yes Total cost
quantity Uint Yes Number of tickets in order
userMessage String Yes Bank’s message to user
status Int Yes Order status
statusExtStr String Yes Order status
statusExtInt Int Yes Order status
formUrl String No Payment url

Request example:
{
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "command": "GET_ORDERS",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}
Request example:
{
 "orderList": [
  {
   "orderId": 64,
   "date": "06.08.2015 18:48",
   "datePattern": "dd.MM.yyyy HH:mm",
   "discount": 0,
   "serviceCharge": 0,
   "sum": 600,
   "quantity": 4,
    "statusExtStr": "PAID",
    "statusExtInt": 2,
    "formUrl": "https://test.paymentgate.ru/testpayment/merchants/bil24/mobile_payment_ru.html?mdOrder=2a2637b4-3d2b-44c4-b29f-4c3b39d17722&pageView=MOBILE",
  }
  ],
 "command": "GET_ORDERS",
 "resultCode": 0,
 "description": "OK"
}

GETTING THE USER ORDERS (command = GET_ORDERS_EXT)

Request fields:

Field Type Required Description
command String Yes GET_ORDERS_EXT
userId Ulong Yes User id in the Ticketing system
sessionId String Yes User session id
fromDate String Yes Date in
dd.MM.yyyy HH:mm:ss format
rawCoordinates boolean No If present and true, then fields
sector, row, number, would
have standard values in
response (like everywhere else).
It is recommended to always send “true”.

Response fields content:

Field Type Required Description
orderList Array Yes List of orders
orderDatePattern String Yes Order date pattern
ticketDatePattern String Yes Ticket date pattern

orderList:

Field Type Required Description
orderId Ulong Yes Order id in the Ticketing system
date String Yes Date of creating an order in
orderDatePattern format
discount Cur Yes Discount in RUR
serviceCharge Cur Yes Service charge in RUR
sum Cur Yes Total cost
quantity Uint Yes Number of tickets in order
ticketList Array Yes List of tickets
status Int Yes Order status
statusExtStr String Yes Order status
statusExtInt Int Yes Order status

Request example:
{
 "fromDate": "01.01.2016 00:00:00",
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "command": "GET_ORDERS_EXT",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}
Request example:
{
 "orderDatePattern": "dd.MM.yyyy HH:mm:ss",
 "ticketDatePattern": "dd.MM.yyyy HH:mm",
 "orderList": [
  {
   "orderId": 3037,
   "date": "12.12.2016 13:29:53",
   "discount": 0,
   "serviceCharge": 30.00,
   "sum": 630.00,
   "quantity": 2,
   "ticketList": [
    {
     "ticketId": 29965,
     "date": "09.01.2017 10:00",
     "actionName": "Star Wars: The Force Awakens",
     "venueName": "Luksor movie theatre",
     "sector": "Parterre sector",
     "row": "Row 2",
     "number": "Number 12",
      "categoryName": "Category: Third",
     "price": 300
    },
    {
     "ticketId": 29966,
     "date": "09.01.2017 10:00",
     "actionName": "Star Wars: The Force Awakens ",
     "venueName": "Luksor movie theatre",
     "sector": "Parterre sector",
     "row": "Row 1",
     "number": "Number 13",
     "categoryName": "Category: Third",
     "price": 300
    }
   ],
   "statusExtStr": "PAID",
   "statusExtInt": 2,
  },
  {
   "orderId": 2438,
   "date": "30.08.2016 00:14:55",
   "discount": 0,
   "serviceCharge": 0.00,
   "sum": 0.00,
   "quantity": 1,
   "ticketList": [
    {
     "ticketId": 29095,
     "date": "31.07.2017 09:00",
     "actionName": "LOVED ONES CLUB",
     "venueName": "territoriya Sochi",
     "categoryName": "Category: Gold",
     "price": 0
    }
   ],
   "status": 1
  }
 ],
 "command": "GET_ORDERS_EXT",
 "resultCode": 0,
 "description": "OK"
}

GETTING THE LIST OF SESSIONS WITH SOLD TICKETS (command = GET_ACTION_EVENTS_GROUPED_BY_TICKETS)

Request fields:

Field Type Required Description
command String Yes GET_ACTION_EVENTS_GROUPED_BY_TICKETS
userId Ulong Yes User id in the Ticketing system
sessionId String Yes User session id

Response fields content:

Field Type Required Description
list Array Yes List of sessions
dayPattern String Yes Session date pattern (dd.MM.yyyy)
timePattern String Yes Session time pattern (HH:mm)

list:

Field Type Required Description
actionEventId Ulong Yes Session id
actionName String Yes Event short title
fullActionName String Yes Event full title
day String Yes Session date in dayPattern format
time String Yes Session time in timePattern format
bigPosterUrl String Yes Big poster url
smallPosterUrl String Yes Small poster url
cityName String Yes City name
venueName String Yes Venue name
quantity Uint Yes Number of tickets
sum Cur Yes Total cost of tickets
ticketsUrl String Yes Link to the pdf tickets

Request example:
{
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "command": "GET_ACTION_EVENTS_GROUPED_BY_TICKETS",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}
Request example:
{
 "dayPattern": "dd.MM.yyyy",
 "timePattern": "HH:mm",
 "list": [
  {
   "actionEventId": 5,
   "actionName": "Sleeping Beauty ballet",
   "day": "28.09.2015",
   "time": "11:01",
   "bigPosterUrl": "https://api.bil24.pro:1240/image?type=bigPoster&actionId=2&hash=lpmbkeg1lae6najf2zd099kgs"
  },
  {
   "actionEventId": 22,
   "actionName": "Everest movie",
   "day": "30.09.2015",
   "time": "15:00",
   "bigPosterUrl": "https://api.bil24.pro:1240/image?type=bigPoster&actionId=11&hash=rf8qt7yz5z4s96hmko0kmkuf8"
  },
  {
   "actionEventId": 8,
   "actionName": "Scooter concert",
   "day": "12.10.2015",
   "time": "21:05",
   "bigPosterUrl": "https://api.bil24.pro:1240/image?type=bigPoster&actionId=3&hash=mtpqe8hih74wyla45p983zmt3"
  }
 ],
 "command": "GET_ACTION_EVENTS_GROUPED_BY_TICKETS",
 "resultCode": 0,
 "description": "OK"
}

GETTING THE LIST OF PAID TICKETS BY SESSION ID (command = GET_TICKETS_BY_ACTION_EVENT)

Request fields:

Field Type Required Description
command String Yes GET_TICKETS_BY_ACTION_EVENT
userId Ulong Yes User id
sessionId String Yes User session id
actionEventId Ulong Yes Session id
sizeQrCode Uint Yes QR-code size
(Length of any side;
picture is square-shaped)
widthBarCode Uint Yes Width of the Bar code
heightBarCode Uint Yes Height of the Bar code
type String Yes Image resolution. (Only PNG is acceptable at the moment).
rawCoordinates boolean No If present and true, then fields
sector, row, number, would
have standard values in
response (like everywhere else).
It is recommended to always send “true”.

Response fields content

Field Type Required Description
datePattern String Yes Date pattern in the ticket
(example: dd.MM.yyyy HH:mm)
actionId Ulong Yes Session id sent through the request
actionName String Yes Event name
ticketList Array Yes List of tickets

ticketList:

Field Type Required Description
ticketId Ulong Yes Ticket id
date String Yes Event date
venueName String Yes Venue name
venueAddress String Yes Venue address
actionName String Yes Event title
sector String No Sector
row String No Row
number String No Number
categoryName String Yes Information about the seat category
tariffPlanName String No Tariff plan name. Is present if applied.
price Cur Yes Ticket price
totalPrice Cur Yes Ticket cost including the service charge
serviceCharge Cur Yes Service charge
qrCodeImg String Yes QR-code in Base64 in the format
sent through request
barCodeImg String Yes Bar code in Base64 in the format
sent through request
barCodeNumber String Yes Bar code value
smallPosterUrl String Yes Poster url (320х335)
legalOwner String Yes Promoter data
legalOwnerName String Yes Promoter name
legalOwnerInn String Yes Promoter ITN
legalOwnerPhone String Yes Promoter phone number
age String Yes Age restriction

Request example:
{
 "actionEventId": 5,
 "sizeQrCode": 500,
 "widthBarCode": 500,
 "heightBarCode": 100,
 "type": "PNG",
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "command": "GET_TICKETS_BY_ACTION_EVENT",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}
Request example:
{
 "datePattern": "dd.MM.yyyy HH:mm",
 "actionEventId": 5,
 "actionName": "Karmen",
 "ticketList": [
   {
    "ticketId": 10075,
    "date": "28.09.2015 11:01",
    "venueName": "Zimnii theatre",
    "venueAddress": "Teatralnaya street, 2",
    "actionName": "Karmen",
    "sector": "Parterre sector",
    "row": "Row 1",
    "number": "Number 22",
    "categoryName": "Category Х",
    "price": 1000,
    "totalPrice": 0,
    "serviceCharge": 0,
    "qrCodeImg": "iVBORw0KGgoAAAANSUhEUgAAAfQAAAH0AQAAAADjreInAAACwElEQVR42u3dS27jMBBFUe2A+99l7YCdjmjWq6KCbiCjJ1zDA1n2YUaEWB8y1/zVKy53H9d+fX1eV2N9/XXx9/25s34mBI939zqVEse1J9c9xH2h979nDx5v7mPNijUxRv5uz6v91R76Jnj8e/z3/FkfZebk4+S+xuPf6sfMOTPLmml/xONf5WsonaulHUvcYCT+cf2Fx7v5jJ/jf98/xN94vJuv2VCNk/dESvmP/Cse7+ajpkTHLNGyhNY57h4Uj3+F32kjTZWWKFrvy1d4vLeXqHgVyXacMCVbOmSgkWkmPN7b6zpJEqalYNZWXJETCY+39zVI0OVRqyu3MkPmj",
    "barCodeImg": "iVBORw0KGgoAAAANSUhEUgAAAfQAAABkAQAAAABYvP/QAAAAYklEQVR42u3LsQ2AIBBG4TMWVzICm+hiJDAabMIIV1KY/GpcwuI1r3n5TFGyK3atLer0njQ1dNk6o5iPJ+qpmUZYXsd323urfCgMj8fj8Xg8Ho/H4/F4PB6Px+PxeDz+Z/4GLPLRZ1RHc5UAAAAASUVORK5CYII="
    "barCodeNumber": "0123456789123",
    "smallPosterUrl": "https://..."
    "legalOwner": "Promoter...",
    "age": "18+",
    }
 ],
 "command": "GET_TICKETS_BY_ACTION_EVENT",
 "resultCode": 0,
 "description": "OK"
}

GETTING THE TICKETS SOLD BY ORDER ID (command = GET_TICKETS_BY_ORDER)

Request fields:

Field Type Required Description
command String Yes GET_TICKETS_BY_ORDER
userId Ulong Yes User id in the Ticketing system
sessionId String Yes User session id
orderId Ulong Yes Order id
sizeQrCode Uint No QR-code size
(Length of any side;
picture is square-shaped)
widthBarCode Uint No Barcode width
heightBarCode Uint No Barcode height
type String No Image resolution. (Only PNG is acceptable at the moment).
rawCoordinates boolean No If present and true, then fields
sector, row, number, would
have standard values in
response (like everywhere else).
It is recommended to always send “true”.

Response fields content:

Field Type Required Description
corderDatePattern String Yes Order date pattern
(e.g. dd.MM.yyyy HH:mm:ss)
actionEventDatePattern String Yes Session date pattern in the ticket
(e.g. dd.MM.yyyy HH:mm)
orderId Ulong Yes Order id, sent rhrough request
date String Yes Order date in orderDatePattern format
discount Cur Yes Discount
serviceCharge Cur Yes Service charge
sum Cur Yes Cost without service charge
totalSum Cur Yes Total cost
quantity Uint Yes Number of tickets
status Int Yes Order status
statusExtStr String Yes order status
statusExtInt Int Yes order status
ticketList Array Yes List of tickets

ticketList:

Field Type Required Description
ticketId Ulong Yes Ticket id
seatId Ulong Yes Seat id
date String Yes Session date in
actionEventDatePattern format
venueName String Yes Venue name
venueAddress String Yes Venue address
actionName String Yes Event name
sector String No Sector
row String No Row
number String No Number
categoryName String Yes Information about seat price category
tariffPlanId Ulong No Tariff plan id, present if applied.
tariffPlanName String No Tariff plan name, present if applied
price Cur Yes Ticket price
totalPrice Cur Yes Price including service charge
serviceCharge Cur Yes Service charge
qrCodeImg String Yes QR-code in Base64 in the format
sent through request
barCodeImg String Yes Barcode in Base64 in the format
sent through request
barCodeNumber String Yes Barcode value
barCodeType String Yes Barcode type:
EAN_13, ITF, CODE_128A,
CODE_128B, CODE_128C,
CODE_39
smallPosterUrl String Yes Poster url (320х335)
legalOwner String Yes Promoter
legalOwnerName String Yes Promoter name
legalOwnerInn String Yes Promoter ITN
legalOwnerPhone String Yes Promoter phone number
age String Yes Age restriction
statusInt число Yes Ticket status
statusStr String Yes Ticket status

Ticket status:

statusInt statusStr
0 Not used
1 Entered
2 Exited
3 Ticket returned
4 Ticket returned in external ticketing system
5 Let in by the controler

Request example:
{
 "orderId": 5,
 "sizeQrCode": 500,
 "widthBarCode": 500,
 "heightBarCode": 100,
 "type": "PNG",
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "command": "GET_TICKETS_BY_ORDER",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}
Request example:
{
 "orderDatePattern": "dd.MM.yyyy HH:mm:ss",
 "actionEventDatePattern": "dd.MM.yyyy HH:mm",
 "orderId": 5,
 "date": "27.09.2015 10:01:01",
 "discount": 0,
 "serviceCharge": 0,
 "sum": 1000,
 "totalSum": 1000,
 "quantity": 5,
 "statusExtStr": "PAID",
 "statusExtInt": 2,
 "ticketList": [
    {
    "ticketId": 10075,
    "date": "28.09.2015 11:01",
    "venueName": "Zimnii theatre",
    "venueAddress": "teatralnaya st., 2",
    "actionName": "Karmen",
    "sector": "Parterre sector",
    "row": "Row 1",
    "number": "Number 22",
    "categoryName": "Category Х",
    "price": 1000,
    "totalPrice": 0,
    "serviceCharge": 0,
     "qrCodeImg": "iVBORw0KGgoAAAANSUhEUgAAAfQAAAH0AQAAAADjreInAAACwElEQVR42u3dS27jMBBFUe2A+99l7YCdjmjWq6KCbiCjJ1zDA1n2YUaEWB8y1/zVKy53H9d+fX1eV2N9/XXx9/25s34mBI939zqVEse1J9c9xH2h979nDx5v7mPNijUxRv5uz6v91R76Jnj8e/z3/FkfZebk4+S+xuPf6sfMOTPLmml/xONf5WsonaulHUvcYCT+cf2Fx7v5jJ/jf98/xN94vJuv2VCNk/dESvmP/Cse7+ajpkTHLNGyhNY57h4Uj3+F32kjTZWWKFrvy1d4vLeXqHgVyXacMCVbOmSgkWkmPN7b6zpJEqalYNZWXJETCY+39zVI0OVRqyu3MkPmj",
     "barCodeImg": "iVBORw0KGgoAAAANSUhEUgAAAfQAAABkAQAAAABYvP/QAAAAYklEQVR42u3LsQ2AIBBG4TMWVzICm+hiJDAabMIIV1KY/GpcwuI1r3n5TFGyK3atLer0njQ1dNk6o5iPJ+qpmUZYXsd323urfCgMj8fj8Xg8Ho/H4/F4PB6Px+PxeDz+Z/4GLPLRZ1RHc5UAAAAASUVORK5CYII="
    "barCodeNumber": "0123456789123",
    "smallPosterUrl": "https://..."
    "legalOwner": "Promoter...",
    "age": "18+",
    }
 ],
 "command": "GET_TICKETS_BY_ACTION_ORDER",
 "resultCode": 0,
 "description": "OK"
}

GETTING INFORMATION OF TICKETS SOLD DURIG GIVAN DATE (command = GET_TICKETS_BY_DAY)

Request fields:

Field Type Required Description
command String Yes GET_TICKETS_BY_DAY
date String Yes Date indd.MM.yyyy ormat

Response fields content

Field Type Required Description
date String Yes Date indd.MM.yyyy format
cityList Array Yes list of cities

cityList:

Field Type Required Description
cityId Ulong Yes City id
actionList Array Yes List of sessions

actionList:

Field Type Required Description
actionId Ulong Yes Event id
actionEventList Array Yes List of sessions

actionEventList:

Field Type Required Description
actionEventId Ulong Yes Session id
ticketList Array Yes List of tickets

ticketList:

Field Type Required Description
ticketId Ulong Yes Ticket id
seatId Ulong Yes Seat id
date String Yes Sale date in
dd.MM.yyyy HH:mm:ssformat
price Cur Yes Ticket price
discount Cur Yes Discount
serviceCharge Cur Yes Service charge
totalPrice Cur Yes Ticket price including discount and service charge
refunded boolean Yes If true - ticket refunded

Request example:
{
 "date": "08.06.2017",
 "command": "GET_TICKETS_BY_DAY",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}
Request example:
{
 "date": "07.06.2017",
 "cityList": [
  {
   "cityId": 3,
   "actionList": [
    {
     "actionId": 323,
     "actionEventList": [
      {
       "actionEventId": 1814,
       "ticketList": [
        {
         "ticketId": 30935,
         "seatId": 2943773,
         "date": "07.06.2017 12:57:01",
         "price": 3000,
         "discount": 0,
         "serviceCharge": 0,
         "totalPrice": 3000.00,
         "refunded": false
        },
       ]
      }
     ]
    }
   ]
  }
 ],
 "command": "GET_TICKETS_BY_DAY",
 "resultCode": 0,
 "description": "OK"
}

GETTING USER INFORMATION (command = GET_USER_INFO)

Request fields:

Field Type Required Description
command String Yes GET_USER_INFO
userId Ulong Yes User id in the Ticketing system
sessionId String Yes User session id

Response fields content

Field Type Required Description
seatInReserve Uint Yes Number of seats reserved
orderInWait Uint Yes Number of unfinished orders, which are waiting.

Request example:
{
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "command": "GET_USER_INFO",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}
Request example:
{
 "seatInReserve": 2,
 "orderInWait": 0,
 "command": "GET_USER_INFO",
 "resultCode": 0,
 "description": "OK"
}

SENDING TICKETS BY EMAIL (command = SEND_TICKETS_TO_EMAIL)

Request fields:

Field Type Required Description
command String Yes SEND_TICKETS_TO_EMAIL
userId Ulong Yes User id in the Ticketing system
sessionId String Yes User session id
email String Yes Email address
ticketIdList Array Yes Ticket id list

Request example:
{
 "email": "email@list.ru",
 "ticketIdList": [
  10261
 ],
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "command": "SEND_TICKETS_TO_EMAIL",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}

Request example:
{
 "command": "SEND_TICKETS_TO_EMAIL",
 "resultCode": 0,
 "description": "OK"
}

DELETING (command = DELETE)

Descripton: Method marks an order or ticket as deleted so it doesn’t have to be loaded in interfaces later on.

Request fields:

Field Type Required Description
command String Yes DELETE
userId Ulong Yes User id in the Ticketing system
sessionId String Yes User session id
id Ulong Yes Element id depending on destination
destination String Yes Can be one of ORDER, TICKET,
TICKETS_BY_ACTION_EVENT

* destination = TICKETS_BY_ACTION_EVENT - destination = TICKETS_BY_ACTION_EVENT – all tickets to the given session are marked as deleted.

Response fields content:

Field Type Required Description
id Ulong Yes Element id sent through request
destination String Yes destination sent through request

Order deleting example:
{
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "id": 1, //Order id
 "destination": "ORDER"
 "command": "DELETE",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}

Example of a response for a successful deleting:
{
 "command": "DELETE",
 "id": 1, //deleted order id
 "destination": "ORDER"
 "resultCode": 0,
 "description": "OK"
}

GETTING ORDER INFORMATION (command = GET_ORDER_INFO)

Request fields:

Field Type Required Description
command String Yes GET_ORDER_INFO
userId Ulong Yes User id in the Ticketing system
sessionId String Yes User session id
orderId Ulong Yes Order id

Response fields content:

Field Type Required Description
orderId Ulong Yes Order id, sent through request
status Int Yes Order status
statusExtStr String Yes order status
statusExtInt Int Yes order status
orderInfoList Array Yes

orderInfoList:

Field Type Required Description
actionId Ulong Yes Event id
actionName String Yes Event name
quantity Uint Yes Number of tickets
sum Cur Yes Total cost
smallPosterUrl String Yes Poster url (320х335)

Request example:
{
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "orderId": 829,
 "command": "GET_ORDER_INFO",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}

Request example:
{
 "orderId": 829,
 "statusExtStr": "NEW",
 "statusExtInt": 0,
 "orderInfoList": [
   {
     "actionId": 80,
     "actionName": "Into the heart of sea",
     "quantity": 1,
     "sum": 200,
     "smallPosterUrl": "https://api.bil24.pro:1240/image?type=smallPoster&actionId=80&hash=q823uap2k22aj0da1hbktd0ch"
   }
  ],
 "command": "GET_ORDER_INFO",
 "resultCode": 0,
 "description": "OK"
}

GETTING THE EMAIL ADDRESS (command = GET_EMAIL)

Request fields:

Field Type Required Description
command String Yes GET_EMAIL
userId Ulong Yes User id in the Ticketing system
sessionId String Yes User session id

Response fields content:

Field Type Required Description
email String Yes User’s email address
needSendTicketEmail boolean Yes If true, then it is needed to send tickets to given email address.

Request example:
{
"userId": 6104,
"sessionId": "19c517c212bf173b44558308149db8ca",
"command": "GET_EMAIL",
"fid": 1185,
"token": "2f1173e2b12fd5a111b6"
}

Request example:
{
"email": "westleyy@rambler.ru",
"needSendTicketEmail": true,
"command": "GET_EMAIL",
"resultCode": 0,
"description": "OK"
}

SENDING GCM TOKEN TO THE SERVER (command = SET_PUSH_TOKEN)

Request fields:

Field Type Required Description
command String Yes SET_PUSH_TOKEN
userId Ulong Yes User id in the Ticketing system
sessionId String Yes User session id
pushToken String Yes token

Request example:
{
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "pushToken": "ec7c5ae54051c60a219d672c4b7d743",
 "command": "SET_PUSH_TOKEN",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}

Request example:
{
 "command": "SET_PUSH_TOKEN",
 "resultCode": 0,
 "description": "OK"
}

GETTING THE NEWS (command = GET_NEWS)

Request fields:

Field Type Required Description
command String Yes GET_NEWS
userId Ulong Yes User id in the Ticketing system
sessionId String Yes User session id
time число long Yes Time the news came in ms
count Uint Yes Number of news (1 to 30)
cursorMode String Yes forward – later news
backward – older news

Response fields content:

Field Type Required Description
datePattern String Yes News date pattern
cursorMode String Yes cursorMode sent through request
serverUnixTime число long Yes Server time in ms
last boolean Yes If true, then this is the last news;
if false, it’s not
newsList Array Yes List of news

newsList:

Field Type Required Description
id Ulong Yes News id
unixTime число long Yes Time the news came in ms
date String Yes Date in datePattern format
header String Yes News header
fullDescription String Yes News content

Request example (to get 10 news later than the current date):
{
 "time": 0,
 "count": 10,
 "cursorMode": "backward",
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "command": "GET_NEWS",
 "fid": 11851,
 "token": "2f1173e2b12fd5a111b6"
}
* time is either 0, UnixTime of news received, or serverUnixTime. Never us local device time!

If time = 0, then current time is applied on the server

If cursorMode = forward, then news come sorted in ascending order of date.
Если cursorMode = backward, then news come sorted in descending order of date.

Request example:
{
 "datePattern": "dd.MM.yyyy HH:mm",
 "newsList": [
  {
   "id": 91,
   "unixTime": 1458571320000,
   "date": "21.03.2016 17:42",
   "header": "Title 1",
   "fullDescription": "Description 1"
  },
  {

   "id": 72,
   "unixTime": 1457989200000,
   "date": "15.03.2016 00:00",
   "header": "Title 2",
   "fullDescription": "Description 2"
  }
  ],
 "cursorMode": "backward",
 "serverUnixTime": 1459769342975,
 "last": false,
 "command": "GET_NEWS",
 "resultCode": 0,
 "description": "OK"
}

CHEKING THE EVENT ACCESS CODE (command = CHECK_KDP)

Request fields:

Field Type Required Description
command String Yes CHECK_KDP
userId Ulong Yes User id in the Ticketing system
sessionId String Yes User session id
actionId Ulong Yes Event id
kdp Int Yes Access code

Request example:
{
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "actionId": 10,
 "kdp": 12345,
 "command": "CHECK_KDP",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}

Positive response example:
{
 "command": "CHECK_KDP",
 "resultCode": 0,
 "description": "OK"
}

Example of response to a wrong Access code:
{
 "command": "CHECK_KDP",
 "resultCode": 101,
 "description": "wrong Access code"
}

GETTING FILTER DATA (command = GET_FILTER).

Request fields:

Field Type Required Description
command String Yes GET_FILTER

Response fields content:

Field Type Required Description
cityList Array Yes list of cities
kindList Array Yes list of kinds

cityList:

Field Type Required Description
cityId Ulong Yes City id
cityName String Yes City name
venueList Array Yes List of venues

venueList:

Field Type Required Description
venueId Ulong Yes Venue id
venueName String Yes Venue name
address String Yes Venue address
geoLat String (##.######) Yes Venue latitude
geoLon String (##.######) Yes Venue longitude
imageUrl String Yes Link to the image of the venue

kindList:

Field Type Required Description
kindId Uint Yes Kind id
kindName String Yes Kind name

Request example:
{
 "command": "GET_FILTER",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}

Request example:
{
 "cityList": [
   {
     "cityId": 1,
     "cityName": "Sochi",
     "venueList": [
       {
          "venueId": 1,
         "venueName": "Zimnii theatre"
       },
       {
         "venueId": 24,
         "venueName": "Green theatre of \"Riverra\" park "
       }
     ]
   },
   {
     "cityId": 2,
     "cityName": "Moscow",
     "venueList": [
       {
         "venueId": 4,
         "venueName": "Luzhniki Arena"
       },
        {
         "venueId": 20,
         "venueName": "SCANDINAVIA CLUB"
       }
     ]
   },
 ],
 "kindList": [
   {
     "kindId": 0,
     "kindName": "Events"
   },
    {
      "kindId": 1,
     "kindName": "Cards (MEC)"
   },
   {
     "kindId": 2,
     "kindName": "Excursions"
   },
   {
     "kindId": 3,
     "kindName": "Restaurants"
   },
   {
     "kindId": 4,
     "kindName": "Hotels"
   }
 ],
 "command": "GET_FILTER",
 "resultCode": 0,
 "description": "OK"
}

BINDING THE EMAIL ADDRESS (command = BIND_EMAIL)

For the email confirmation it is necessary to:
1. perform BIND_EMAIL method. Confirmation code will be delivered to the given email address.
2. perform CONFIRM_EMAIL with the code received. Response will contain data (userId, sessionId), which have this email successfully binded. All further requests have to use this data.

Request fields:

Field Type Required Description
command String Yes BIND_EMAIL
userId Ulong Yes User id
sessionId String Yes User session id
email String Yes email

Request example:
{
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "command": "BIND_EMAIL",
 "email": "email@list.ru",
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}

Positive response example:
{
 "command": "BIND_EMAIL",
 "resultCode": 0,
 "description": "OK"
}

EMAIL CONFIRMATION (command = CONFIRM_EMAIL)

Request fields:

Field Type Required Description
command String Yes CONFIRM_EMAIL
userId Ulong Yes User id
sessionId String Yes User session id
code Uint Yes Confirmation code

Response fields content:

Field Type Required Description
userId Ulong Yes User id
sessionId String Yes User session id
email String Yes Binded email

Request example:
{
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "command": "CONFIRM_EMAIL",
 "code": 123456,
 "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}

Positive response example:
{
 "command": "CONFIRM_EMAIL",
 "userId": 2,
 "sessionId": "2e4566051c60a219d672c4b7a12d129",
 "email": "email@list.ru",
 "resultCode": 0,
 "description": "OK"
}

GETTING THE MOBILE ELECTRONIC CARDS (MECs) (command = GET_MECS)

Request fields:

Field Type Required Description
command String Yes GET_MECS
userId Ulong Yes User id
sessionId String Yes User session id
mecId* Ulong No MEC id
sizeQrCode Uint Yes QR-code size
Length of any side;
picture is square-shaped)
widthBarCode Uint Yes Barcode width
heightBarCode Uint Yes Barcode height
rawCoordinates boolean No If present and true, then fields
sector, row, number, would have
standard values in response (like everywhere else).
It is recommended to always send “true”.

*mecId - Field is used to save traffic mostly on mobile frontend. If this field is sent through request, then response will have cards with id larger, then sent through request. It is supposed, that cards with id <= mecId are stored locally and don’t need additional loading.

Response field content:

Field Type Required Description
list Array Yes An array with cards data

list:

Field Type Required Description
actionEventId Ulong Yes Session id
actionName String Yes Event short title
fullActionName String Yes Event full title
bigPosterUrl String Yes ссылка на постер
smallPosterUrl String Yes ссылка на постер
cityId Ulong Yes City id
cityName String Yes City name
venueName String Yes Venue name
venueAddress String Yes Venue address
cityPass boolean Yes If true, then preferences and
discount are applied at the venue
quantity Uint Yes Number of MECs
totalSum Cur Yes Total cost of MECs
mecList Array Yes An array of MECs for the session

mecList:

Field Type Required Description
mecId Ulong Yes MEC id
categoryName String Yes Seat category information
price Cur Yes Ticket price
qrCodeImg String Yes QR-code in Base64 in the format
sent through request
barCodeImg String Yes Barcode in Base64 in the format
sent through request
barCodeNumber String Yes Barcode value

Request example:
{
 "mecId": 5,
 "sizeQrCode": 500,
 "widthBarCode": 500,
 "heightBarCode": 100,
 "userId": 6104,
 "sessionId": "19c517c212bf173b44558308149db8ca",
 "command": "GET_MECS",
  "fid": 1185,
 "token": "2f1173e2b12fd5a111b6"
}

Successful response example:
{
 "list": [
  {
  "actionEventId": 1178,
  "actionName": "Magnit card",
  "fullActionName": "Goods and services with a discount for network employees",
  "bigPosterUrl": "https://api.bil24.pro:1240/image?type=bigPoster&actionId=156&hash=ixr9rn1fmd1hssxl6k06q3png",
  "smallPosterUrl": "https://api.bil24.pro:1240/image?type=smallPoster&actionId=156&hash=k2tlcg2xsq82jynqo9yqkmr1q",
   "cityId": 1,
  "cityName": "Krasnodar",
   "venueName": "retail network Magnit",
   "venueAddress": "Krasnodar, Solnechnaya st., 15/5",
  "cityPass": false,
  "quantity": 2,
  "totalSum": 4645.00,
   "mecList": [
    {
    "mecId": 29096,
    "categoryName": "Category: Corporate",
    "price": 245,
    "qrCodeImg": "qrCodeImg",
    "barCodeImg": "barCodeImg",
    "barCodeNumber": "2400107290966"
    },
   {
    "mecId": 29097,
    "categoryName": "Category: Platinum",
    "price": 4400,
    "qrCodeImg": "qrCodeImg",
    "barCodeImg": "barCodeImg",
    "barCodeNumber": "2400107290973"
   }
  ]
   },
  {
   "actionEventId": 1380,
   "actionName": "LOVED ONES CLUB",
   "fullActionName": "Bonus program card",
   "bigPosterUrl": "https://api.bil24.pro:1240/image?type=bigPoster&actionId=201&hash=ohvtolmud5n3eacnl1ho1ysbe",
   "smallPosterUrl": "https://api.bil24.pro:1240/image?type=smallPoster&actionId=201&hash=gnoi2lhueiyx5d555gf8ziegt",
    "cityId": 2,
    "cityName": "Sochi",
    "venueName": "territoriya Sochi",
    "venueAddress": "Russia, Krasnodar region, Sochi",
    "cityPass": false,
   "quantity": 1,
    "totalSum": 0.00,
    "mecList": [
    {
     "mecId": 29102,
     "categoryName": "Category: Gold",
     "price": 0,
     "qrCodeImg": "qrCodeImg",
     "barCodeImg": "barCodeImg",
     "barCodeNumber": "2403107291025"
    }
    ]
  }
 ],
 "command": "GET_MECS",
 "resultCode": 0,
 "description": "OK"
}

GETTING THE PROMOCODES (command = GET_PROMO_CODES)

Request fields:

Field Type Required Description
command String Yes GET_PROMO_CODES
userId Ulong Yes User id
sessionId String Yes User session id

Response fields content:

Field Type Required Description
promoPackList Array Yes List of user promo packs

promoPackList:

Field Type Required Description
promoPackId Ulong Yes Promo pack id
name String Yes Promo pack name
description String Yes Promo pack description
startTime String Yes Date of promotion start
endTime String Yes Date of promotion end
activeNow boolean Yes If true, then promotion is active now
discountPercent Cur Yes Discount in %
maxDiscountSum Cur No Discount limit in RUR. If not present, then discount is unlimited.
maxTickets Uint No Limit of number of tickets to which discount can be applied. If not present, this number is unlimited.
minPrice Cur No If present, then tickets with price lower then minPrice can’t be discounted.
promoCodeList Array Yes СList of promo codes in promo pack.

promoCodeList:

Field Type Required Description
code String Yes Promo code value
used boolean Yes If true, then promo code is already used by this user
spent boolean Yes If true, then promo code is already used by this user or another

if used or spent is true, or activeNow is false, given user won’t be able to use given promocode.



TICKET REFUNDING (command = REFUND_TICKETS)*

Descripton: Ticket refunding.
*only for the Ticketing system Interface type.

Request fields:

Field Type Required Description
command String Yes REFUND_TICKETS
userId Ulong Yes User id
sessionId String Yes User session id
ticketIdSet Array Yes Ticket id list

Response fields content

Field Type Required Description
statusMap Associative array Yes key – ticket id, sent through request;
value – number, indicating refund status

Refund status:
1 – can’t be refunded
2 – refunding is in process
3 – ticket is refunded

Note: Repeated refunding request won’t respond in an error, but instead would respond with the current ticket status

Request example:
{
 "userId": 18109,
 "sessionId": "d6035a755bd0862e713e03f337505bd0",
 "command": "REFUND_TICKETS",
 "ticketIdSet": [1, 2, 3],
 "fid": 1184,
 "token": "24d3b97b64dfab187a5f"
}

Positive response example:
{
 "command": "REFUND_TICKETS",
  "statusMap": {
  "1" : 1,
  "2" : 2,
  "3" : 2
 }
 "resultCode": 0,
 "description": "OK"
}

ORDER STATUS

Some methods return order status in their response fields (statusExtStr and statusExtInt).

statusExtStr statusExtInt Description
NEW 0 New order/Waiting for payment
PROCESSING 1 Processing paid order
PAID 2 Order paid
CANCELLING -1 Cancelling unpaid order
CANCELLED -2 Cancelled

Order status can change in following sequences:
NEW → PROCESSING → PAID
NEW → CANCELLING → CANCELLED

In exceptional cases, caused by errors in external ticketing systems, order can be cancelled manually by system operator, in this case status will change like this:
PROCESSING → CANCELLED

PAID and CANCELLED statuses are final and can’t be changed. Getting tickets have to only be performed after an order getting PAID status.

PROTOCOL CHANGE LOG 09.05.2016

1. Method GET_VENUES
- cityId parameter added in object Venue in response cityName parameter is now required in the response.;
- fields: CITY_NAME is obsolete, DESCRIPTION value added.

2. Method GET_ACTIONS
- field dateFrom is added to request fields – not required (which date should be used to get the sessions);
- field actionEventTime is added to response fields - not required (will be present, if session always happens at the same time);
- field venueName is added to response fields – not required (will be present, session always happens at the same venue);
- field kdp is added to the response fields - required (kdp is Access Code).
*Before opening seating plan or pushing “Reserve” button (in general admission) User have to input Access Code (method for checking Access Code is CHECK_KDP)

3. Method GET_ORDERS
- in paymentOrder objest type field is obsolete.Field gateway is used instead;
- all present paymentOrder values are descripted.

4. Method GET_TICKETS_BY_ACTION_EVENT
- field actionName is added to the list of tickets;
- field smallPosterUrl is added to the list of tickets.

5. GET_TICKETS_BY_ORDER added
returns all the ticket data by the order.

6. Method CHECK_KDP added (see 2.)

7. Method CREATE_ORDER
- successUrl, failUrl field added – REQUIRED fields, indicating redirects after payment;
- field email added – not required parameter, indicating address to which tickets have to be sent after payment.

8. GET_FILTER method added.

9. Метод GET_ACTION_EVENTS_GROUPED_BY_TICKETS
fields added:
fullActionName – full session name;
cityName – city name;
venueName – venue name;
quantity – number of tickets;
sum – total cost.

10. Method GET_ACTION_EXT added
returns the information about session in given city, List of venues where it occures and list of sessions for each of them. Method is created to simplify programming. Before, 3 requests to the server had to be used instead: GET_VENUES, GET_ACTION, GET_ACTION_EVENTS.

11. Method GET_CART added
returns the list of seats reserved. Seats are grouped by sessions. GET_SEAT_IN_RESERVE method is obsolete, so don’t use it.

PROTOCOL CHANGE LOG 20.05.2016

1. Changes in method GET_ACTIONS (Method is obsolete. See 4.).
- required field kindId is added to response in actionList;
- required field kindName is added to response in actionList.

2. Changes in method GET_ACTION_EXT
- required field kindId is added to response in object action;
- required field kindName is added to response in object action;
- required field categoryList is added to response in object actionEventList.

3. Changes in method GET_ACTION (Method is obsolete)
- required field kindId is added to response in object action;
- required field kindName is added to response in object action.

4. Method GET_ACTIONS_V2 added
new method replacing GET_ACTIONS. Method allows to get sessions by city only. Other filters (venues, kind, dates) are applied by customer

5. 1003 methods CHANGE_PRIVATE_DATA, GET_PRIVATE_DATA have been seen on frontend. Methods are obsolete for 4 months already, so use SET_EMAIL, GET_EMAIL.

6. Method GET_TICKETS_BY_ACTION_EVENT
15.10.2015 seatInfo field is obsolete. 7.Method GET_SEAT_IN_RESERVE is obsolete. Replaced by GET_CART.

8. RESERVATION method (reserving in general admission)
fields quantity, categoryPriceId are obsolete. categoryQuantityMap has to be used instead.

9. Method GET_ORDERS
paymentOrder field is obsolete; formUrl is added to orderList (field transferred from paymentOrder).

PROTOCOL CHANGE LOG 15.06.2016

1. If session requires Access Code input, then parameter kdp=AccessCode has to be added in url suring seating plan requests.

2. Not required parameter kdp is added to “Reservation in general admission (command = RESERVATION)” request. Should be transferred if session requires entering Access Code.

3. Fields cityID and venueId are added to object actionEventList in GET_CART method.

PROTOCOL CHANGE LOG 22.06.2016

1. Requests GET_TICKETS_BY_ORDER и GET_TICKETS_BY_ACTION_EVENT now have in response fields legalOwner and age added to the ticket list.

PROTOCOL CHANGE LOG 23.06.2016

1. Method RESERVATION (type RESERVE, RESERVE_BY_PLACE). kdp parameter added. If session requires Access Code input, then parameter is required.

PROTOCOL CHANGE LOG 08.07.2016

1. actionId field added in response to request GET_CART in object actionEventList

2. phone field added in request CREATE_ORDER.

PROTOCOL CHANGE LOG 22.07.2016

1. Response to GET_CART request now has total service charge, by the session and by the seat.

2. Response to GET_ACTION_EXT request now has field categoryList moved to categoryLimitList.

There are 3 seating plans:
1. General admission. placementUrl won’t be present, see categoryLimitList.
2. Assigned seats. See placementUrl, categoryLimitList will be empty.
3. Combined. Look up both placementUrl and categoryLimitList.

PROTOCOL CHANGE LOG 16.08.2016

1. Response to GET_ORDERS request now has fields discount and serviceCharge. Values in RUR.

2. Request CREATE_ORDER now has fields discount and serviceCharge. Values in percentage.

3. Response to request AUTH now has field frontendType.

PROTOCOL CHANGE LOG 02.09.2016

1. Methods of binding email BIND_EMAIL, CONFIRM_EMAIL added.
Methods are only available in the test realm temporarily. Method SET_EMAIL is obsolete and doesn’t work in test realm anymore.

2. Separate method for getting MECs GET_MECS added.
Due to addition of thiss methods MECs are no longer returned by methods GET_ACTION_EVENTS_GROUPED_BY_TICKETS, GET_TICKETS_BY_ACTION_EVENT. These restrictions are only implied at the test realm at the moment. MECs aren’t returned in the mobile frontends in both test and real realms.

PROTOCOL CHANGE LOG 25.10.2016

1. Phone and email fields in CREATE_ORDER request are only available for the TICKETBOX and INVITATION interface types.

PROTOCOL CHANGE LOG 25.11.2016

1. Added method REFUND_TICKETS for ticket refunding.

2. Added status field in response to requests CREATE_ORDER and GET_ORDER_INFO.

3. Method CREATE_ORDER: paid field is obsolete and will be deleted 25.12.2016

PROTOCOL CHANGE LOG 15.12.2016

1. Method GET_ORDERS_EXT added.

2. Method GET_TICKETS_BY_ORDER. Added fields: orderDatePattern, actionEventDatePattern, totalPrice, serviceCharge. Deleted field: datePattern.

3. Method GET_TICKETS_BY_ACTION_EVENT. Fields added: totalPrice, serviceCharge.

PROTOCOL CHANGE LOG 27.12.2016

1. Field fullName is added to method CREATE_ORDER. Field is not required. The content of the field will be present on ticket.

PROTOCOL CHANGE LOG 04.02.2017

1. Method GET_ACTION_EXT. Parameter availability is added to the category; availability number of seats available in the category. if remainder not present, we focus on availability. If remainder is present, то нужно внимательно использовать эти парамеthese parameters should be used carefully. For example, general limit of remainder on 3 categories may be 100, but the availability in every category may be 100 as well.

2. Added resultCode 102 status, indicating that an email address has to be bound. Checking given code has to be done when responding to RESERVATION request.

3. Method GET_ACTION_EVENTS_GROUPED_BY_TICKETS. ticketsUrl field added- link to the tickets in pdf format (link to tickets bought since 27.02.2017. If ticket was purchased earlier, link won’t be sent).

PROTOCOL CHANGE LOG 05.05.2017

1. Method GET_CITIES is obsolete, GET_FILTER has to be used instead.

PROTOCOL CHANGE LOG 18.05.2017

1. Method GET_ACTION_EXT. Added parameter bookletUrl – link to the booklet of given session.

PROTOCOL CHANGE LOG 08.06.2017

1. Added status order fields (statusExtStr и statusExtInt) in responses to requests CREATE_ORDER, GET_ORDER_INFO, GET_ORDERS, GET_ORDERS_EXT, GET_TICKETS_BY_ORDER.

2. Field status is obsolete in CREATE_ORDER, GET_ORDER_INFO, GET_ORDERS, GET_ORDERS_EXT, GET_TICKETS_BY_ORDER methods.

3. CREATE_USER Method added.

4. GET_SEAT_LIST Method added.

5. CREATE_ORDER_EXT Method added.

6. CANCEL_ORDER Method added.

7. PAY_ORDER Method added.

8. New field age (age restriction) added in response of method GET_ACTION_EXT.

PROTOCOL CHANGE LOG 06.07.2017

1. Changed description of GET_CITIES method.

2. Method GET_VENUE_TYPES added.

3. Method GET_VENUES added.

PROTOCOL CHANGE LOG 13.07.2017

1. Changed description of reserving methods RESERVATION.

2. Added new field barCodeType (barcode type) in response of method GET_TICKETS_BY_ORDER.

3. Added new not required field longReservation in method CREATE_ORDER_EXT.

4. Added new field orderTimeout in response to method CREATE_ORDER_EXT.

PROTOCOL CHANGE LOG 22.07.2017

1. Added new fields (organizerId, organizerName, legalOwner) in response to method GET_ACTION_EXT.

2. Added method GET_TICKETS_BY_DAY.

PROTOCOL CHANGE LOG 09.08.2017

1. UserId fields in request GET_ACTION_EXT isn’t required anymore.

2. Added “General protocol using plan” section: protocol commands are split in sessional and non-sessional.
List of the non-sessional commands:
1. GET_ACTIONS_V2;
2. GET_ACTION_EXT;
3. GET_CITIES;
4. GET_VENUE_TYPES;
5. GET_VENUES;
6. GET_FILTER;
7. GET_SEAT_LIST;
8. GET_TICKETS_BY_DAY.

There is no necessity of using AUTH command before any of the commands listed.Session id (sessionId) is not needed for their performance.

Performing sessional commands requires session Id. It is initially received with command AUTH (CREATE_USER for ticketing systems). The user data received is recommended to be saved and re-used. User session in determined by sessionId and acts indefinetely.

Generally, sessionId would be needed before BIND_EMAIL (RESERVATION for ticketing systems).

PROTOCOL CHANGE LOG 23.08.2017

1. Added new field seatId in response of method GET_TICKETS_BY_ORDER.

PROTOCOL CHANGE LOG 02.10.2017

1. Added description of ticket statuses in method GET_TICKETS_BY_ORDER.

PROTOCOL CHANGE LOG 18.02.2018

1. Added new fields seatList and cartTimeout in response of method RESERVATION.

PROTOCOL CHANGE LOG 01.03.2018

1. Added new fields cityId and cityPass in response of method GET_MECS.

PROTOCOL CHANGE LOG 12.03.2018

1. Added new fields seatingPlanId and seatingPlanName in response of method GET_ACTION_EXT.

PROTOCOL CHANGE LOG 19.08.2018

1. Required field versionCode is removed from all requests. 2. Method SEND_WI_FLY_DATA removed.

PROTOCOL CHANGE LOG 16.10.2018

1. Server address changed to api.bil24.pro everywhere

2. Method GET_TICKETS_BY_ORDER now has the descriptions of different barcode types added.

3. Methods GET_CART, GET_MECS, GET_ORDERS_EXT, GET_TICKETS_BY_ACTION_EVENT, GET_TICKETS_BY_ORDER now have new not required field rawCoordinates added in request fields. Sending the value true correct incompatibilities of raw coordinate values (sector, row, number) and the name of the category categoryName.

PROTOCOL CHANGE LOG 06.12.2018

1. New field categoryList added in response of GET_SEAT_LIST method.



PROTOCOL CHANGE LOG 12.12.2018

1. New method GET_ALL_ACTIONS for the Ticketing system interfaces added.



PROTOCOL CHANGE LOG 23.04.2019

1. Added new method ADD_PROMO_CODES.
2. Added new method GET_PROMO_CODES.
3. Added new fields: categoryPriceId, nominal, discount и discountReason in response of method GET_CART.
4. Added new field externalOrderId в ответ методаin response of method CREATE_ORDER_EXT.




PROTOCOL CHANGE LOG 21.05.2019

1. Added new method GET_SCHEMA.




PROTOCOL CHANGE LOG 10.06.2019

1. New field minPrice added in response of method GET_PROMO_CODES.




PROTOCOL CHANGE LOG 23.07.2019

1. New not required field categoryLimitList added in response of GET_SEAT_LIST method.
2. New not required fields discountPercent and chargePercent added to request of method CREATE_ORDER_EXT.




PROTOCOL CHANGE LOG 13.08.2019

1. New fields fullNameRequired и phoneRequired added in response of GET_CART method.
2. New field phoneRequired added in response of GET_ALL_ACTIONS method.




PROTOCOL CHANGE LOG 24.09.2019

1. New fields legalOwnerName, legalOwnerInn, legalOwnerPhone added in responses of GET_ALL_ACTIONS, GET_ACTION_EXT, GET_TICKETS_BY_ACTION_EVENT, GET_TICKETS_BY_ORDER methods.
2. Field legalOwner became obsolete in responses of GET_ALL_ACTIONS, GET_ACTION_EXT, GET_TICKETS_BY_ACTION_EVENT, GET_TICKETS_BY_ORDER methods.




PROTOCOL CHANGE LOG 11.06.2020

1. New required fields tariffPlanList и tariffIdMap added to response of methods GET_ALL_ACTIONS, GET_ACTION_EXT, GET_SEAT_LIST
2. New not required field tariffMap added to response of method RESERVATION.
3. New not required field tariffPlanId added to response of method RESERVATION.
4. New not required fields tariffPlanId и tariffPlanName added to response of methods GET_CART и GET_TICKETS_BY_ORDER.
5. New not required field tariffPlanName added to response of method GET_TICKETS_BY_ACTION_EVENT.

PROTOCOL CHANGE LOG log 14.12.2020

1. New required fields address, geoLat, geoLon, imageUrl added in responses of GET_ALL_ACTIONS and GET_FILTER