API: Агенты

Терминология

  1. Событие - действие, происходящее в конкретное время и в конкретном месте, на которое могут продаваться билеты.
  2. Место - зрительское место на определенном событии. Именно на него продается билет.
  3. Предварительное бронирование (предбронь) – кратковременное закрепление за покупателем места на событии для предотвращения двойных продаж. Необходимо, чтобы клиент мог выбрать и купить несколько билетов на соседние места.
  4. Бронирование – долгосрочное закрепление места на событии за покупателем, предшествующее покупке билета. При бронировании места (мест) возникает Заказ, характеризующийся уникальным номером.
  5. Сессия – логически непрерывный акт взаимодействия с системой TicketSteam.
  6. Внешняя система – в данном документе сторонняя Информационная Система, которая взаимодействует по данному протоколу.
  7. Билетная система – система TicketSteam.

Транспортный протокол

В качестве транспортного протокола используется HTTPS. Файлы ключей на стороне агента не требуются.

Авторизация

Для идентификации работы внешней системы, с каждым запросом передается идентификатор, формируемый из логина и пароля, выданного при регистрации:

login : sha1( md5(password) timestamp ) : timestamp

Сессия

Под сессией понимается последовательность действий одного покупателя через внешнюю систему, приводящая к бронированию и покупке им билетов. Количество одновременных сессий специально не ограничивается. Билетная система различает сессии (т.е., фактически, одновременные действия разных покупателей) по уникальному номеру сессии, присваемому внешней системой. Номер сессии представляет собой строку символов не менее 20 символов.

Общие свойства сессии:

  1. Сессия практически не ограничена по времени, но время сохранения выбранных билетов в состоянии «предбронь» с данным идентификатором сессии ограничено (900 секунд). По истечении данного интервала для каждого конкретного билета запись о его предварительном бронировании удаляется (т.е. он «исчезает» из заказа). Детектирование и обработка этого обстоятельства (для предотвращения конфликтной ситуации) должны осуществляться в информационной системе агента.
  2. При оформлении заказа (твердое бронирование) список предварительной брони по данной сессии очищается.

Общая схема процесса бронирования билетов

Внешняя система получает информацию о имеющихся в продаже билетов с помощью информационных запросов к билетной системе. Внешняя система предоставляет эти билеты любым способом своим покупателям, и далее, предоставляет им возможность оформить заказ. В ходе приобретения выделяются следующие этапы:

Выбор мест на событии

При выборе мест Внешняя система выполняет запрос «Предбронь». Билетная система гарантирует, что билеты, на «Предбронь» которых им был дан положительный ответ, находятся в продаже в данный момент, и не будут предварительно забронированы или забронированы в других сессиях покупателей в течение 15 минут. Надо иметь в виду, что билеты могут быть в течение этого времени сняты с продажи оператором Билетной системы.

Оформление заказа

Происходит, когда покупатель определился с билетами, которые он хочет приобрести. В этот момент Внешняя система выполняет запрос «Бронь», в ответ на который Билетная система выдает номер заказа, однозначно идентифицируемый данный заказ, объединяющий билеты на выбранные покупателем места. Положительный ответ на «Бронь» означает, что включенные в заказ билеты не будут забронированы кем-либо еще, и «скорее всего» (т.е. за исключением особых обстоятельств) не будут сняты с продажи в ближайшее время.

Контекст

Все списки событий, мест на события выдаются с учетом доступности данных билетов для продажи данной внешней системе. Если внешняя система запрашивает существующий объект по идентификатору, но этот объект не попадает в зону видимости, то система возвращает ту же ошибку, что и при полном отсутствии объекта с таким идентификатором.

Форматы передаваемых данных

Основные свойства:

  1. Запрос передается БС в виде POST-запросов.
  2. При этом параметры кодируются в стандартном для HTTP виде.
  3. Ответы представляют собой текст в формате JSON.
  4. Везде используется кодировка UTF-8.
  5. Формат даты и времени (пример: 2011-02-28 22:54:00+0300, обратите внимание, что дата события отдается без указания временной зоны).

Формат запроса

URL запросов выглядит так:

https://ticketsteam.ru/api/agent/

Все запросы посылаются только к билетной системе. Обратных запросов нет.

Обязательные параметры, присутствующие в каждом запросе:

  1. action - идентификатор запроса
  2. auth - идентификатор внешней системы (формирование идентификатора см. в разделе Авторизация)
  3. city_id - идентификатор города (кроме запроса списка городов)

Формат ответа:

Сообщение об ошибке:

{ "status":"1", "description":"Описание ошибки" }

Успешный ответ сервера:

{ "status":"0", "result":"...Данные..." }

Информационные запросы

city.list: список городов

Возвращает массив объектов:

genre.list: список жанров

Возвращает массив объектов:

Включает только объекты с доступными для продажи событиями

venue.list: список мест проведения

Возвращает список мест проведения в связке с актуальной версией зала

Входные параметры:

Возвращает массив объектов:

Включает только объекты с доступными для продажи событиями

venue.detail: информация о месте проведения

Входные параметры:

Возвращает массив данных:

Включает только объекты с доступными для продажи событиями

activity.list: список мероприятий

Входные параметры:

Возвращает массив объектов:

event.list: список событий

Входные параметры:

Возвращает массив объектов:

event.detail: информация о событии

Входные параметры:

Возвращает массив данных:

event.sector.list: список секторов с билетами для события

Входные параметры:

Возвращает массив объектов:

sector.list: список секторов версии зала

Входные параметры:

Возвращает массив объектов:

sector.map: схема сектора

Входные параметры:

Возвращает массив объектов:

sector.groups: список групп мест в секторе

Входные параметры:

Возвращает массив объектов:

ticket.list: Список свободных билетов

Входные параметры:

Возвращает массив объектов:

order.list: список заказов

Входные параметры:

Если не указан период создания заказа, будет выдана последняя 1000 заказов.

Возвращает массив объектов:

order.info: информация о заказе

Входные параметры:

Возвращает данные:

order.ticket.list: список проданных билетов

Входные параметры:

Если не указан фильтр, будет выдана последняя 1000 билетов.

Возвращает массив объектов:

Оформление заказа

Обязательные параметры, присутствующие в каждом запросе:

cart.add: предварительное бронирование билета

Билет в корзине находится 15 минут, затем аннулируется.

Входные параметры:

Возвращает пустой ответ с успешным статусом

cart.remove: отмена предварительного бронирования билета

Входные параметры:

Возвращает пустой ответ с успешным статусом

cart.detail: содержимое корзины

Возвращает массив билетов:

cart.payments: список способов оплаты

Возвращает массив объектов:

cart.deliveries: список вариантов доставки

Возвращает массив объектов:

promocode.check: проверка возможности применения промокода к корзине

Входные параметры:

Возвращает сумму скидки

order.create: оформить заказ

Входные параметры:

Возвращает данные:

Операции с заказом

order.ticket.remove: аннуляция билета в заказе

Входные параметры:

Возвращает пустой ответ с успешным статусом

order.cancel: аннуляция заказа

Входные параметры:

Возвращает пустой ответ с успешным статусом

order.delivery: перевод заказа в режим доставки

Входные параметры:

Возвращает пустой ответ с успешным статусом

order.sold: продажа заказа

Входные параметры:

Возвращает пустой ответ с успешным статусом

order.payment: форма оплаты заказа

Входные параметры:

Возвращает HTML форму с кнопкой перехода на страницу оплаты

order.eticket: скачать электронный билет для заказа

Только для проданного заказа

Входные параметры:

В ответ отдается pdf файл закодированный в base64

order.eticket.send: отправка электронного билета покупателю

Только для проданного заказа

Входные параметры:

Возвращает пустой ответ с успешным статусом

Операции с пользователем

customer.auth: авторизация пользователя

Входные параметры для авторизации по логину и паролю:

Входные данные для авторизации через социальную сеть:

Возвращает объект пользователя:

customer.recovery: отправить письмо восстановления пароля

Входные параметры:

Возвращает пустой ответ с успешным статусом

customer.password: изменить пароль по токену из письма

Входные параметры:

Возвращает объект пользователя:

customer.edit: редактирование пользователя

Входные параметры:

Возвращает пустой ответ с успешным статусом

customer.create: регистрация пользователя

Входные параметры:

Возвращает объект пользователя:

customer.subscribe: подписать на рассылку

Входные параметры:

Возвращает пустой ответ с успешным статусом

customer.unsubscribe: отписать от рассылки

Входные параметры:

Возвращает пустой ответ с успешным статусом

Пример запроса к API на PHP

# Данные для доступа
$login = 'LOGIN';
$password = 'PASSWORD';
$url = 'https://demo.ticketsteam.ru/api/agent/';

# Параметры запроса
$params = [];

# Идентификатор для авторизации
# login : sha1( md5(password) timestamp ) : timestamp 
$time = time();
$params['auth'] = $login.':'.sha1(md5($password).$time).':'.$time;

# Запрос списка городов
$params['action'] = 'city.list';

# Запрос к API
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
$rs = curl_exec($ch);
curl_close($ch);

# Вывод результата
$json = json_decode($rs, true);
if (json_last_error() == JSON_ERROR_NONE) {
    print_r($json);
} else {
    echo 'Ошибка запроса';
}