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 для определения привилегий учетной записи.
2019-09-27 v.1.2.3
В метод DELETE /ticket можно передать сумму возврата, отличающуюся от номинальной стомости билета.
2022-08-01 v.1.2.3
Добавлена поддержка свободной рассадки
2025-12-22 v.1.2.4
У методов PUT /order и POST /order/sell изменениы коды ответов при ошибке (500 -ый код ошибки заменён на 4хх).

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

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

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

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

                

                    

                        Код ответа
                        Описание
                        Расшифровка ответа
                    

                    

                        200
                        ОК
                        Заказ успешно создан
                    

                    

                        400
                        Ошибка
                        Ошибка валидации заказа или Ошибка применения промокода
                    

                    

                        403
                        Ошибка
                        Ошибка кармы (карма слишком низкая)
                    

                    

                        404
                        Ошибка
                        Мероприятие  на найдено
                    

                    

                        423
                        Ошибка
                        Ошибка блокировки мест
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
            }
        }
    ]
}

                

                    

                        Код ответа
                        Описание
                        Расшифровка ответа
                    

                    

                        200
                        ОК
                        Оплата заказа успешно подтверждена
                    

                    

                        400
                        Ошибка
                        Ошибка валидации заказа
                    

                    

                        400
                        Ошибка
                        Передано более одного билета по заказу с пушкинской картой
                    

                    

                        400
                        Ошибка
                        Билет для мероприятия с id *** не может быть оплачен пушкинской картой
                    

                    

                        404
                        Ошибка
                        Заказ не найден
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"
}