API: Агенты
Терминология
- Событие - действие, происходящее в конкретное время и в конкретном месте, на которое могут продаваться билеты.
- Место - зрительское место на определенном событии. Именно на него продается билет.
- Предварительное бронирование (предбронь) – кратковременное закрепление за покупателем места на событии для предотвращения двойных продаж. Необходимо, чтобы клиент мог выбрать и купить несколько билетов на соседние места.
- Бронирование – долгосрочное закрепление места на событии за покупателем, предшествующее покупке билета. При бронировании места (мест) возникает Заказ, характеризующийся уникальным номером.
- Сессия – логически непрерывный акт взаимодействия с системой TicketSteam.
- Внешняя система – в данном документе сторонняя Информационная Система, которая взаимодействует по данному протоколу.
- Билетная система – система TicketSteam.
Транспортный протокол
В качестве транспортного протокола используется HTTPS. Файлы ключей на стороне агента не требуются.
Авторизация
Для идентификации работы внешней системы, с каждым запросом передается идентификатор, формируемый из логина и пароля, выданного при регистрации:
login : sha1( md5(password) timestamp ) : timestamp
Сессия
Под сессией понимается последовательность действий одного покупателя через внешнюю систему, приводящая к бронированию и покупке им билетов. Количество одновременных сессий специально не ограничивается. Билетная система различает сессии (т.е., фактически, одновременные действия разных покупателей) по уникальному номеру сессии, присваемому внешней системой. Номер сессии представляет собой строку символов не менее 20 символов.
Общие свойства сессии:
- Сессия практически не ограничена по времени, но время сохранения выбранных билетов в состоянии «предбронь» с данным идентификатором сессии ограничено (900 секунд). По истечении данного интервала для каждого конкретного билета запись о его предварительном бронировании удаляется (т.е. он «исчезает» из заказа). Детектирование и обработка этого обстоятельства (для предотвращения конфликтной ситуации) должны осуществляться в информационной системе агента.
- При оформлении заказа (твердое бронирование) список предварительной брони по данной сессии очищается.
Общая схема процесса бронирования билетов
Внешняя система получает информацию о имеющихся в продаже билетов с помощью информационных запросов к билетной системе. Внешняя система предоставляет эти билеты любым способом своим покупателям, и далее, предоставляет им возможность оформить заказ. В ходе приобретения выделяются следующие этапы:
Выбор мест на событии
При выборе мест Внешняя система выполняет запрос «Предбронь». Билетная система гарантирует, что билеты, на «Предбронь» которых им был дан положительный ответ, находятся в продаже в данный момент, и не будут предварительно забронированы или забронированы в других сессиях покупателей в течение 15 минут. Надо иметь в виду, что билеты могут быть в течение этого времени сняты с продажи оператором Билетной системы.
Оформление заказа
Происходит, когда покупатель определился с билетами, которые он хочет приобрести. В этот момент Внешняя система выполняет запрос «Бронь», в ответ на который Билетная система выдает номер заказа, однозначно идентифицируемый данный заказ, объединяющий билеты на выбранные покупателем места. Положительный ответ на «Бронь» означает, что включенные в заказ билеты не будут забронированы кем-либо еще, и «скорее всего» (т.е. за исключением особых обстоятельств) не будут сняты с продажи в ближайшее время.
Контекст
Все списки событий, мест на события выдаются с учетом доступности данных билетов для продажи данной внешней системе. Если внешняя система запрашивает существующий объект по идентификатору, но этот объект не попадает в зону видимости, то система возвращает ту же ошибку, что и при полном отсутствии объекта с таким идентификатором.
Форматы передаваемых данных
Основные свойства:
- Запрос передается БС в виде POST-запросов.
- При этом параметры кодируются в стандартном для HTTP виде.
- Ответы представляют собой текст в формате JSON.
- Везде используется кодировка UTF-8.
- Формат даты и времени (пример: 2011-02-28 22:54:00+0300, обратите внимание, что дата события отдается без указания временной зоны).
Формат запроса
URL запросов выглядит так:
Все запросы посылаются только к билетной системе. Обратных запросов нет.
Обязательные параметры, присутствующие в каждом запросе:
- action - идентификатор запроса
- auth - идентификатор внешней системы (формирование идентификатора см. в разделе Авторизация)
- city_id - идентификатор города (кроме запроса списка городов)
Формат ответа:
Сообщение об ошибке:
{ "status":"1", "description":"Описание ошибки" }
Успешный ответ сервера:
{ "status":"0", "result":"...Данные..." }
Информационные запросы
city.list: список городов
Входные параметры:
- updated_after - только измененные сущности после этой даты (не обязательно, формат YYYY-MM-DDThh:mm:ss±hh)
Возвращает массив объектов:
- id - идентификатор
- name - название
genre.list: список жанров
Возвращает массив объектов:
- id - идентификатор
- name - название
- parent_id - идентификатор родительского жанра (0 - для у родителя)
Включает только объекты с доступными для продажи событиями
venue.list: список мест проведения
Возвращает список мест проведения в связке с актуальной версией зала
Входные параметры:
- limit - (не обязательно)
- offset - (не обязательно)
- updated_after - только измененные сущности после этой даты (не обязательно, формат YYYY-MM-DDThh:mm:ss±hh)
Возвращает массив объектов:
- id - идентификатор
- name - название места проведения
- address - адрес
- city_id - идентификатор города
- versions - массив версий зала:
- id - идентификатор версии
- name - название
- type - тип: 1 - версия схемы зала, 2 - отдельный зал (Малая сцена)
Включает только объекты с доступными для продажи событиями
venue.detail: информация о месте проведения
Входные параметры:
- venue_id - идентификатор
Возвращает массив данных:
- id - идентификатор
- name - название места проведения
- descr - описание места проведения
- image - ссылка на изображение
- address - адрес
- city_id - идентификатор города
- coord - координаты места проведения
- similar - идентификаторы рекомендуемых мест проведения
- versions - массив версий зала:
- id - идентификатор версии
- name - название
- type - тип: 1 - версия схемы зала, 2 - отдельный зал (Малая сцена)
- svg - ссылка на SVG схему зала
- image - ссылка на изображение схемы зала
- show - тип отображения схемы зала
- 0 - сектора отображаются на одной схеме
- 1 - отображается список секторов
Включает только объекты с доступными для продажи событиями
activity.list: список мероприятий
Входные параметры:
- limit - (не обязательно)
- offset - (не обязательно)
Возвращает массив объектов:
- id - идентификатор
- name - название
- genres_id - массив идентификаторов жанров
- age - рекомендованный возраст
- image - ссылка на изображение
- image_list - ссылка на изображение для списков
- image_poster - ссылка на изображение постера
- description - описание
- city_id - идентификатор города
event.list: список событий
Входные параметры:
- limit - (не обязательно)
- offset - (не обязательно)
- venue_id - идентификатор места проведения (не обязательно)
- genre_id - идентификатор жанра (не обязательно)
- activity_id - идентификатор мероприятия (не обязательно)
- search - поиск по названию (не обязательно)
- start_date - от даты включительно (не обязательно, формат yyyy-mm-dd)
- end_date - до даты включительно (не обязательно, формат yyyy-mm-dd)
- updated_after - только измененные сущности после этой даты (не обязательно, формат YYYY-MM-DDThh:mm:ss±hh)
Возвращает массив объектов:
- id - идентификатор
- name - название
- venue_id - идентификатор места проведения
- venue - название места проведения
- version_id - идентификатор версии зала
- version - название версии зала
- date - дата события
- activity_id - идентификатор мероприятия
- widget - код виджета
- min_price - минимальная стоимость билета
- max_price - максимальная стоимость билета
- genres_id - массив идентификаторов жанров
- age - рекомендованный возраст
- image - ссылка на изображение
- image_list - ссылка на изображение для списков
- image_poster - ссылка на изображение постера
- city_id - идентификатор города
- close_to - кол-во часов, за которое до начала события прекратится продажа билетов
event.detail: информация о событии
Входные параметры:
- event_id - идентификатор события
- organizer - вернуть данные организатора (не обязательно)
- html - вернуть описание с html разметкой (не обязательно)
- discount - вернуть массив скидок для события (не обязательно)
Возвращает массив данных:
- id - идентификатор
- name - название
- venue_id - идентификатор места проведения
- venue - название места проведения
- version_id - идентификатор версии зала
- version_show - тип отображения схемы (0 - общая схема, 1-список секторов)
- version - название версии зала
- address - адрес места проведения
- date - дата события
- image - ссылка на изображение
- image_list - ссылка на изображение для списков
- image_poster - ссылка на изображение постера
- descr - описание события
- status - статус события: 0 - закрыто, 1 - в продаже
- activity_id - идентификатор мероприятия
- widget - код виджета
- min_price - минимальная стоимость билета
- max_price - максимальная стоимость билета
- organizer - массив данных организатора события (при параметре organizer):
- name - юридическое название
- address - юридический адрес
- inn - ИНН
- discounts - массив скидок для события (при параметре discount):
- start - дата начала скидки
- end - дата окончания скидки
- discount_percent - процент скидки с билета
- discount_sum - сумма скидки с билета
- genres_id - массив идентификаторов жанров
- age - рекомендованный возраст
- meta_title - заголовок страницы
- meta_descr - описание страницы
- meta_kw - ключевые слова
- close_to - кол-во часов, за которое до начала события прекратится продажа билетов
event.sector.list: список секторов с билетами для события
Входные параметры:
- event_id - идентификатор события
- show_all - добавить сектора где билеты закончились (не обязательно)
Возвращает массив объектов:
- id - идентификатор сектора
- name - название сектора
- type - тип мест (0 - ненумерованные, 1 - нумерованные места)
- min_price - минимальная стоимость билетов (номинальная)
- max_price - максимальная стоимость билетов (номинальная)
- min_full_price - минимальная стоимость билетов с сервисным сбором
- max_full_price - максимальная стоимость билетов с сервисным сбором
- tickets - количество доступных билетов
sector.list: список секторов версии зала
Входные параметры:
- version_id - идентификатор версии зала
Возвращает массив объектов:
- id - идентификатор сектора
- name - название сектора
- type - тип мест (0 - ненумерованные, 1 - нумерованные места)
sector.map: схема сектора
Входные параметры:
- sector_id - идентификатор сектора
Возвращает массив объектов:
- type - тип объекта
- id - идентификатор объекта
- x - координата X
- y - координата Y
- Для type = place (место в зале):
- row_num - номер ряда (например: А, 1, 2, 3….)
- row_name - название ряда (например: Литер, Ряд…)
- place_num - номер места (например: А, Б, 1, 2, 3….)
- place_name - название места (например: Место…)
- Для type = text (текстовая метка):
- text - текст
- size - размер текста
sector.groups: список групп мест в секторе
Входные параметры:
- sector_id - идентификатор сектора
Возвращает массив объектов:
- name - название группы
- places - массив идентификаторов мест на схеме
ticket.list: Список свободных билетов
Входные параметры:
- event_id - идентификатор события
- sector_id - идентификатор сектора (не обязательно)
- add_groups - признак необходимости добавить билеты находящиеся в группах
Возвращает массив объектов:
- id - идентификатор билета
- price - цена
- original_price - цена без скидки
- fee - сервисный сбор
- original_fee - сервисный сбор без скидки
- type - тип (0 - не нумерованное, 1 - нумерованное место)
- sector - название сектора
- sector_id - идентификатор сектора
- row - номер ряда
- place - номер места
- place_id - идентификатор места
- discount_price - скидка с номинала билета
- revaluation_prices - информация о первой ближайшей переоценке билета
- price - цена
- date - дата и время переоценки
- discount_percent - процент скидки с номинала (возвращает в случае, если скидка была задана процентом, а не суммой)
order.list: список заказов
Входные параметры:
- status - статус заказа (не обязательно)
- start_date - от даты включительно (не обязательно, формат yyyy-mm-dd)
- end_date - до даты включительно (не обязательно, формат yyyy-mm-dd)
- customer_id - идентификатор покупателя (не обязательно)
Если не указан период создания заказа, будет выдана последняя 1000 заказов.
Возвращает массив объектов:
- id - идентификатор
- status - статус заказа (0-аннулирован, 1-продан, 2-бронь, 3-на доставке)
- order_date - время создания заказа
- annulate_date - время аннуляции заказа
- utm_source - UTM метка в заказе
- tickets_count - количество билетов в заказе
- tickets_sum - сумма билетов в заказе
- tickets_fee - сумма сервисного сбора
order.info: информация о заказе
Входные параметры:
- id - идентификатор заказа (номер заказа)
Возвращает данные:
- id - идентификатор заказа (номер заказа)
- status - статус заказа (0-аннулирован, 1-продан, 2-бронь, 3-на доставке)
- order_date - время создания заказа
- annulate_date - время аннуляции заказа
- utm_source - UTM метка в заказе
- payment_id - идентификатор способа оплаты
- delivery_id - идентификатор варианта доставки
- address - адрес доставки
- customer - массив данных покупателя
- id - идентификатор покупателя
- name - имя
- phone - телефон
- tickets - массив билетов в заказе
- id - идентификатор билета
- status - статус (0-аннулирован, 1-активен)
- price - цена
- original_price - цена без скидки
- event_id - идентификатор события
- fee - сервисный сбор
- original_fee - сервисный сбор без скидки
- type - тип (0 - не нумерованное, 1 - нумерованное место)
- sector - название сектора
- sector_id - идентификатор сектора
- place_id - идентификатор места
- row - номер ряда
- place - номер места
- barcode - штрих код (для заказов в статусе продан или доставка)
- organizer - массив данных организатора для печати на билете
- name - юридическое название
- address - юридический адрес
- inn - ИНН организатора
order.ticket.list: список проданных билетов
Входные параметры:
- event_id - идентификатор события (не обязательно)
- start_date - от даты включительно (не обязательно, формат yyyy-mm-dd)
- end_date - до даты включительно (не обязательно, формат yyyy-mm-dd)
Если не указан фильтр, будет выдана последняя 1000 билетов.
Возвращает массив объектов:
- id - идентификатор билета
- order_id - идентификатор заказа
- barcode - штрихкод билета
- event_id - идентификатор события
- sale_date - дата продажи
- price - стоимость билета
- place_id - идентификатор места
Оформление заказа
Обязательные параметры, присутствующие в каждом запросе:
- uid - идентификатор сессии, постоянный для всей сессии (не менее 20 символов)
cart.add: предварительное бронирование билета
Билет в корзине находится 15 минут, затем аннулируется.
Входные параметры:
- id - идентификатор билета
Возвращает пустой ответ с успешным статусом
cart.remove: отмена предварительного бронирования билета
Входные параметры:
- id - идентификатор билета
Возвращает пустой ответ с успешным статусом
cart.detail: содержимое корзины
Возвращает массив билетов:
- id - идентификатор билета
- price - цена
- original_price - цена без скидки
- fee - сервисный сбор
- original_fee - сервисный сбор без скидки
- type - тип (0 - не нумерованное, 1 - нумерованное место)
- sector - название сектора
- sector_id - идентификатор сектора
- row - номер ряда
- place - номер места
- barcode - штрих код (для заказов в статусе продан или доставка)
- place_id - идентификатор места
- event_id - идентификатор события
cart.payments: список способов оплаты
Возвращает массив объектов:
- id - идентификатор способа оплаты
- title - название
- default - отмечен как по умолчанию (0 - нет, 1 - да)
- eticket - применяется при покупке электронного билета (0 - нет, 1 - да)
cart.deliveries: список вариантов доставки
Возвращает массив объектов:
- id - идентификатор варианта доставки
- title - название
- price - стоимость доставки
- type - тип (0 - самовыкуп, 1 - доставка, 2 - электронный билет, 3 - касса продаж)
- default - отмечен как по умолчанию (0 - нет, 1 - да)
- commission - минимальный сервисный сбор при данном способе доставки
- days - массив дней возможной доставки (при type = 1, в формате yyyy-mm-dd)
promocode.check: проверка возможности применения промокода к корзине
Входные параметры:
- code - промокод
Возвращает сумму скидки
order.create: оформить заказ
Входные параметры:
- name - имя покупателя
- phone - номер телефона покупателя
- email - электронный адрес покупателя (не обязательно)
- address - адрес доставки заказа (не обязательно)
- customer_id - идентификатор покупателя (не обязательно)
- utm_source - UTM метка (не обязательно)
- promocode - промокод (не обязательно)
- amount - сумма номинала билетов, для контроля (не обязательно)
- lang - язык покупателя: en, ee, ru - по умолчанию (не обязательно)
- payment_id - идентификатор способа оплаты (не обязательно)
- delivery_id - идентификатор варианта доставки (не обязательно)
- delivery_day - день доставки (не обязательно, в формате yyyy-mm-dd)
Возвращает данные:
- id - идентификатор заказа
Операции с заказом
order.ticket.remove: аннуляция билета в заказе
Входные параметры:
- id - идентификатор билета
- fine - значение штрафа (float, не обязательно)
Возвращает пустой ответ с успешным статусом
order.cancel: аннуляция заказа
Входные параметры:
- id - идентификатор заказа
- tickets - массив билетов в заказе (не обязательно)
- id - идентификатор билета
- fine - значение штрафа (float)
Массив tickets заполняется только, если вы хотите передать штрафы для каких-то билетов. Билеты соответственно тоже надо передавать не все, а только те, для которых хотите указать штраф. Если передан билет, которого нету в заказе, запрос вернет ошибку. Возвращает пустой ответ с успешным статусом
order.delivery: перевод заказа в режим доставки
Входные параметры:
- id - идентификатор заказа
Возвращает пустой ответ с успешным статусом
order.sold: продажа заказа
Входные параметры:
- id - идентификатор заказа
Возвращает пустой ответ с успешным статусом
order.payment: форма оплаты заказа
Входные параметры:
- id - идентификатор заказа
Возвращает HTML форму с кнопкой перехода на страницу оплаты
order.eticket: скачать электронный билет для заказа
Только для проданного заказа
Входные параметры:
- id - идентификатор заказа
- currency - валюта отображаемая в шаблоне билета (не обязательно)
- delimited - разделить билеты по файлам (не обязательно)
В ответ возвращается:
- в ответ отдается содержимое pdf файла закодированного в base64
- json массив pdf файлов закодированных в base64 (при переданном delimited)
order.eticket.send: отправка электронного билета покупателю
Только для проданного заказа
Входные параметры:
- id - идентификатор заказа
- currency - валюта отображаемая в шаблоне билета (не обязательно)
Возвращает пустой ответ с успешным статусом
Операции с пользователем
customer.auth: авторизация пользователя
Входные параметры для авторизации по логину и паролю:
- email - электронная почта
- password - пароль
Входные данные для авторизации через социальную сеть:
- social - идентификатор социальной сети
Возвращает объект пользователя:
- id - идентификатор пользователя
- name - имя
- phone - номер телефона
- email - электронная почта
- status - статус (0 - удален)
- subscription - подписка на рассылку (0 - не подписан)
- session - идентификатор сессии для авторизации
customer.recovery: отправить письмо восстановления пароля
Входные параметры:
- email - электронная почта
Возвращает пустой ответ с успешным статусом
customer.password: изменить пароль по токену из письма
Входные параметры:
- token - токен из письма восстановления пароля
- password - новый пароль
Возвращает объект пользователя:
- id - идентификатор пользователя
- name - имя
- phone - номер телефона
- email - электронная почта
- status - статус (0 - удален)
- subscription - подписка на рассылку (0 - не подписан)
- session - идентификатор сессии для авторизации
customer.edit: редактирование пользователя
Входные параметры:
- session - идентификатор сессии пользователя
- email - электронная почта (не обязательно)
- password - пароль (не обязательно)
- name - имя (не обязательно)
- phone - номер телефона (не обязательно)
- social - идентификатор социальной сети
- status - статус (0 - удален, 1 - активен, не обязательно)
- subscription - подписка на рассылку (0 - не подписан, 1 - подписан, не обязательно)
Возвращает пустой ответ с успешным статусом
customer.create: регистрация пользователя
Входные параметры:
- email - электронная почта (не обязательно)
- password - пароль (не обязательно)
- name - имя (не обязательно)
- phone - номер телефона (не обязательно)
- social - идентификатор социальной сети
- subscription - подписка на рассылку (0 - не подписан, 1 - подписан, по умолчанию)
Возвращает объект пользователя:
- id - идентификатор пользователя
- name - имя
- phone - номер телефона
- email - электронная почта
- status - статус (0 - удален)
- subscription - подписка на рассылку (0 - не подписан)
- session - идентификатор сессии для авторизации
customer.subscribe: подписать на рассылку
Входные параметры:
- email - электронная почта
Возвращает пустой ответ с успешным статусом
customer.unsubscribe: отписать от рассылки
Входные параметры:
- email - электронная почта
Возвращает пустой ответ с успешным статусом
Пример запроса к 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 'Ошибка запроса';
}