Ticketland External API v.1.2

English - Русский

Index

Версии

2016-04-28 v.1.0
2016-05-24 v.1.1
1. Используйте DELETE вместо специальных методов
2. Свойство "Customer" в запросе PUT /order стало необязательным
3. Изменения в схеме продажи: вместо PUT /order -> GET /order -> POST /order/confirm теперь используйте PUT /order -> POST /order/sell (без информации о платеже) -> GET /order
4. Исправления форматов в ответах (float вместо strings, ticket object вместо array в order info)
2016-06-26 v.1.2
1. Добавлен функционал правил, предотвращающих множественное бронирование без последующего выкупа. Один раз в сутки (в 0:00) мы считаем отношение проданных заказов к созданным, если созданных заказов 10 и более.
  • Если отношение строго меньше 0.3, для учетной записи вводится запрет на создание заказов до последующего пересчета (исключение 1006 "Low karma")
  • Если отношение больше или равно 0.3, учетная запись имеет право создавать заказы по стандартной схеме.
  • Если отношение больше или равно 0.7, учетная запись имеет право создавать заказы на срок до 24 часов.
  • Если ни одного заказа не было создано за прошедшие сутки, отношение считается равным 0.5.
2. В метод PUT /order добавлен необязательный параметр expireDateTime, с помощью которого можно указать желаемый срок аннулирования заказа (для учетной записи с соответствующим правом, и не более чем на 24 часа от текущего времени).
2017-01-25 v.1.2.1
Используйте GET /service/karma для определения привилегий учетной записи.
2017-04-24 v.1.2.2
Теперь у нас есть первая версия Документа по API Exceptions
2019-09-27 v.1.2.3
В метод DELETE /ticket можно передать сумму возврата, отличающуюся от номинальной стомости билета.
2022-08-01 v.1.2.3
Добавлена поддержка свободной рассадки

Как продавать билеты

1 Загрузите мероприятия с помощью метода GET /reperoire, а информацию о площадках (холлах, секциях и т.д.), используя метод GET /constructive
1.1 Существует кэш данных для информации о репертуаре (30 min) и информации о площадках (60 min).
2 Получите список билетов на свободные места, используя метод GET /ticket.
2.1 Существует кэш на статус билетов (5 min).
3 Создайте заказ с билетами, используя метод PUT /order.
3.1 Отмените неоплаченный заказ (сделайте заблокированные места свободными), используя метод DELETE /order.
3.2 Места автоматически освободятся после истеченния срока жизни заказа.
4 Получите информацию о заказе, используя метод GET /order.
5 Подтвердите оплату заказа, используя метод POST /order/sell. Информация о билетах (баркоды) будет присутствовать в ответе.
5.1 Чтобы отменить подтвержденный заказ, должен быть отдельно возвращен каждый его билет, используя метод DELETE /ticket.
6 Получите баркоды подтвержденного заказа так же можно, использовав метод GET /order после совершения оплаты.
7 Измените зрительские данные по заказу, если это необходимо. PUT /spectator-info
scheme

Протокол обмена

Определения

identity-id 2-х символьный идентификатор
control-hash-algorithm "D" (хеширование основано на текущей временной метке)
hash [int-unix-timestamp][sha-1-encrypted-value]
int-unix-timestamp 1461857409; сервис сверяет текущее время с некоторым допущением
sha-1-encrypted-value результат хэширования SHA-1 строки "[salt][int-unix-timestamp]"
salt секретная строка

Запрос

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"}

Ответ

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)

Сервисные объекты

Repertoire

GET /repertoire
fromInclusive string with datetime format "yyyy-MM-ddTHH:mm:ss" необязательный
tillExclusive string with datetime format "yyyy-MM-ddTHH:mm:ss" необязательный 
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 обязательный
segment array of strings: [building|hall|sections|places] обязательный 
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 обязательный 
GET /ticket?performanceId=24856677
{
    "result": true,
    "tickets": [
        {
            "placeId": 3341306,
            "performanceId": 24844994,
            "price": 100.00,
            "taxId": 205814
        }
    ]
}
// для свободной рассадки
{
    "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 обязательный
price float обязательный
orderId integer обязательный 
DELETE /ticket?id=999999&orderId=999&price=3500
{
    "result": true
}

Order

GET /order
id integer обязательный 
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, // только для свободной рассадки
            "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} необязательный
Если передается объект customer, все поля обязательны, но могут быть пустыми, id может быть 0.
tickets array of objects Ticket {"performanceId":integer, "placeId":integer, "price":float, "taxId":integer} обязательный, если не передан sections
sections array of objects SeatlessSection {"performanceId":integer, "sectionId":integer, "freeSeatsCount":integer, "price":integer, "taxId":integer, "zoneId":integer} обязательный, если не передан tickets
expireDateTime string with datetime format "yyyy-MM-ddTHH:mm:ss" необязательный
spectatorInfo Информация о зрителе для ДИТ обязательный, если площадка входит в список ГБУК-ов
spectatorsInfo Информация о зрителях для ДИТ в запросе для билетов со свободной рассадкой обязательный, если площадка входит в список ГБУК-ов
ditSpectatorId string (Уникальный идентификатор зрителя) обязательный, если передаем инфо о зрителе
surname string (Фамилия зрителя) обязательный, если передаем инфо о зрителе
name string (Имя зрителя) обязательный, если передаем инфо о зрителе
middlename string (Отчество зрителя) обязательный, если передаем инфо о зрителе
 
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"
}
// для свободной рассадки
{
    "customer": {
        "id": 999,
        "surname": "Customer",
        "phone": "+79999999999",
        "email": "test@customer.ee"
    },
    "sections": [
        {
            "performanceId": 24856677,
            "sectionId": 123,
            "freeSeatsCount": 2,
            "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",
}

// Ответ с успешно созданным билетом
{
    "result": true,
    "locks": [
        {
            "exception": null,
            "price": 4000,
            "expireTime": '2022-07-29T15:18:47.543+03:00',
            "groupId": 321,
            "groupType": "Single",
            "performanceId": 24856677,
            "sectionId": 123, // только для свободной рассадки
            "placeId": 3675264,
        }
    ],
    "order": {
        "orderId": 99999999,
        "expires": "2016-04-01T00:00:00"
    }
}

// Ответ с ошибкой (один билет не создан, но поле "result" возвращает "true", и заказ имеет идентификатор)
{
    "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 обязательный
isPushkinCard boolean необязательный 
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 обязательный
tickets array обязательный
performanceId integer обязательный
placeId integer обязательный
ditSpectatorId string обязательный
surname string обязательный
name string обязательный
middlename string необязательный 
PUT /spectator-info

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

{
  "result": true,
  "requestID": "67d29f784c26d"
}
DELETE /order
id integer обязательный 
DELETE /order?id=999
{
    "result": true
}

Sales

GET /sales
fromInclusive string with datetime format "yyyy-MM-ddTHH:mm:ss" необязательный
tillExclusive string with datetime format "yyyy-MM-ddTHH:mm:ss", current time is maximum allowed value необязательный
*Временной интервал не должен превышать 3-х дней
**Если значения не переданы, возвращаются операции за предыдущий день
 
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 для учетной записи введен запрет на создание заказов на сутки
karma: 2 учетная запись обладает стандартным набором привилегий
karma: 3 учетная запись обладает повышенным набором привилегий
 
GET /service/karma
{
    "account_id": 999,
    "karma": 3,
    "check_dt": "2016-10-17 21:00:01.000"
}