Справочная информация предоставляется в открытом виде, по запросу на общедоступную ссылку, без секретного кода. Список справочной информации:.
Параметр S(key) – уникальный не секретный идентификатор агента. Выдается по запросу при заключении договора.
Тестовые параметры доступа S(key) = 168098425a026100, Password = 123. С данными параметрами доступны функции запроса информации о билетах (М1) и заказа билета (М2). Подробнее о функциях смотрите далее.
Заказ и получение билета осуществляется с использованием передачи следующих сообщений:
- Запрос информации о параметрах билетов (М1).
- Заказ билета (М2).
- Получение билета (М3).
- Аннуляция билета (М4).
На все сообщения платформа Voxxter формирует XML ответ. В качестве транспортного протокола используется протокол http.
URL для сообщений - http://api.voxxter.ru/agent/
Метод отправки сообщение - POST.
Список события и мест с продажей билетов
Информацию о работе со списками событий и мест смотри в разделе "Для информационных ресурсов"
Справочник параметров билета
Данные справочник содержит наименования всех параметров билетов, которые необходимо отображать клиенту при формировании заказа и при отображении приобретенного билета.
В ответ на запрос по адресу: http://api.voxxter.ru/export/xml/dict/?s=XXXXXX
Сервер Voxxter выдает XML-файл вида:
<voxxter>
<categories>
<category id="ID категории билета">
Название категории билета (взрослый,детский, льготный и тд.)
</category>
...
<category id="ID категории билета">
Название категории билета (взрослый,детский, льготный и тд.)
</category>
</categories>
<durations>
<duration id="ID длительности предоставляемой услуги">
Название длительности предоставляемой услуги (1 час, 2 часа, 24 часа, 3 дня и тд.)
</duration>
...
<duration id="ID длительности предоставляемой услуги">
Название длительности предоставляемой услуги (1 час, 2 часа, 24 часа, 3 дня и тд.)
</duration>
</durations>
<tarifs>
<tarif id="ID тарифа предоставляемой услуги">
Название тарифа предоставляемой услуги (Будние дни, Выходные дни, Будние до 18:00 и тд.)
</tarif>
...
<tarif id="ID тарифа предоставляемой услуги">
Название тарифа предоставляемой услуги (Будние дни, Выходные дни, Будние до 18:00 и тд.)
</tarif>
</tarifs>
<seances>
<seance id="ID сеанса услуги">
Название сеанса услуги (2013-05-27 19:15:00, Каждый день в 10.00 и тд.)
</seance>
...
<seance id="ID сеанса услуги" (regular="1") >
Название сеанса услуги (2013-05-27 19:15:00, Каждый день в 10.00 и тд.)
</seance>
</seances>
<error id="0"><error>
</voxxter>
Если запрос содержит ошибку, то ответ:
<voxxter>
<error id="Идентификатор ошибки">Текст ошибки<error>
</voxxter>
ВАЖНО: Справочник <seances> для отдельных сеансов может содержать
необязательный признак "regular="1" - данный признак означает, что сеанс задан регулряным
выражением (напрмер, каждый день в 10:00) и для получения информации о билетах по данному сеансу требуется
указывать дату.
Запрос информации о параметрах билетов (сообщение М1).
Запрос осуществляется путем отправки сообщения M1 по адресу: http://api.voxxter.ru/agent/
Параметры сообщения:
| Ключ |
Имя параметра |
Описание значения параметра |
| M |
Идентификатор сообщения |
= 1 |
| L |
ключ агента |
= S(key) – уникальный не секретный идентификатор агента. |
| Sid |
ID билета |
= ID билета (тэг <set>, блок <tickets>) справочника событий и мест. Подробнее о справочниках в разделе "Для информационных ресурсов". |
| Date |
Дата сеанса |
= Дата в формате "DD.MM.YYYY" - необязательный параметр. Необходим только для получения информации о наличии билетов для услуг с регулярными сеансами. Смомтри подробнее ниже. |
| S |
Подпись собщения |
= значение хеш -функции (SHA1) от секретного пароля агента (выдается при заключении договора) и всех указанных выше параметров сообщения. |
ВАЖНО: Через API можно приобретать как отдельные билеты, так и единые билеты Voxxter (подробнее
здесь). Значения Sid для единых билетов Voxxter указано в таблице:
| Sid |
Название единого билета |
| 2450 |
Паспорт Культурного Гражданина (18+) |
| 2451 |
Паспорт Культурного Школьника (6+) |
| 2452 |
Паспорт Культурного Туриста (18+) |
В ответ на отправку сообщения по адресу: http://api.voxxter.ru/agent/ cервер Voxxter выдает XML-файл вида:
<voxxter>
<set id="идентификатор билета">
<title>
Название услуги предоставляемой по билету
</title>
<prices>
<price
id="Идентификатор цены"
category="Идентификатор категории билета"
tarif="Идентификатор тарифа" {!необязательный параметр}
duration="Длительность услуги" {!необязательный параметр}
place_category="Категория места" {!необязательный параметр}
expday="Срок действия билета" {!необязательный параметр}
seances="Признак услуги по сеансам" {!необязательный параметр}
>Сумма цены в рублях</price>
...
<price id=...>Сумма цены в рублях</price>
</prices>
<qty>
<limit>Значение лимита билетов (Значения: >0; NO_LIMIT)</limit> {!необязательный блок}
<seances> {!необязательный блок. При наличии <price> с признаком seances="1"}
<seance
id="Идентификатор сеанса"
date="1" {!необязательный параметр, для регулярных сеансов}
seats="1" {!необазательный параметр, для услуг с местами}
>
Лимит мест на сеанс
(Значения: >0; NO_LIMIT;
"Требуется запрос даты сеанса" при наличии признакак date="1")
<seats>{!необазательный блок, при наличии признака seats="1"}
<seat id="Идентификатор места" price="Цена места в рублях">
Название места (Например, Партер >> Ряд 9 >> Место 7)
<.seat>
...
<seat id="Идентификатор места">Название места</seat>
</seats>
</seance>
...
<seance id=...>Лимит мест на сеанс</seance>
</seances>
<error>Билеты закончились</error>{!необязательный блок}
</qty>
<client_info>
<field id="Идентификатор поля">Название поля данных о клиенте</qty>
...
<field id="Идентификатор поля">Название поля данных о клиенте</qty>
<client_info>
</set>
<error id="0"><error>
</voxxter>
Если запрос содержит ошибку, то ответ:
<voxxter>
<error id="Идентификатор ошибки">Текст ошибки<error>
</voxxter>
Пояснения к параметрам и блокам ответа серверам Voxxter на сообщение M1:
| Блок/параметр |
Пояснение |
| Блок <prices> |
Данные блок обязательно должен содержать хотя бы 1 значение <price> |
| Параметр <price duration=""> |
Данный параметр указывает на длительно предоставления услуги по билету (например, для услуг с разной длительностью сеанса) |
| Параметр <price expday=""> |
Данный параметр указывает в днях срок действия билета после покупки. Данный параметр отображается для всех услуг без сеансов. |
| Параметр <price seances="1"> |
Данный параметр указывает на наличие сеансов по данной услуге |
| Блок <qty><limit> |
Блок содержит значение лимита билетов. Может быть числовым значением >0, либо NO_LIMIT - если нет ограничения на число билетов по данной услуге |
| параметр <seance seats="1"> |
Данный параметр указывает необходимости выбора места для покупки билета по данной услуге |
| параметр <seance date="1"> |
Данный параметр указывает необходимости выбора даты конкретного сеанса для регулярных сеансов (Например, сеанс "каждый день в 10:00") |
| Блок <client_info> |
Блок содержит перечень полей, которые нужно запросить у клиента для получения билета. Минимальный список из одного поля - email |
ВАЖНО: Элементы блока <client_info> ялвляются обязательными для запроса у клиента и передачи на сервер Voxxter. Минимальным параметром является e-mail.
Примеры
1) Ответ сервера Voxxter на запрос сообщения M1 для услуги, без дополнительных парметров цены, без сеансов, без лимитов продажи билетов.
<voxxter>
<set id="2786">
<title>
Государственный геологический музей им. В.И. Вернадского - Входной билет
</title>
<prices>
<price id="3973" category="1" expday="30">250</price>
<price id="3974" category="3" expday="30">150</price>
</prices>
<qty>
<limit>NO_LIMIT</limit>
</qty>
<client_info>
<field id="0">E-mail</qty>
<client_info>
</set>
<error id="0"><error>
</voxxter>
2) Ответ сервера Voxxter на запрос сообщения M1 для услуги, с дополнительным параметром "тариф", без сеансов, без лимитов продажи билетов.
<voxxter>
<set id="81">
<title>
Билет на гонку в картинг-клубе LeMans (10 минут)
</title>
<prices>
<price id="229" tarif="3" category="1" expday="30">750</price>
<price id="230" tarif="3" category="2" expday="30">500</price>
<price id="294" tarif="1" category="1" expday="30">500</price>
<price id="295" tarif="1" category="2" expday="30">400</price>
<price id="296" tarif="2" category="1" expday="30">600</price>
<price id="297" tarif="2" category="2" expday="30">450</price>
</prices>
<qty>
<limit>NO_LIMIT</limit>
</qty>
<client_info>
<field id="0">E-mail</qty>
<client_info>
</set>
<error id="0"><error>
</voxxter>
3) Ответ сервера Voxxter на запрос сообщения M1 для услуги, с дополнительным параметром "тариф", с сеансами, с лимитом продажи билетов по одному из регулярных сеансов.
<voxxter>
<set id="119">
<title>
Билет на смотровую площадку Останкинской телебашни
</title>
<prices>
<price id="316" tarif="18" category="1" seances="1">600</price>
<price id="317" tarif="19" category="1" seances="1">980</price>
<price id="318" tarif="20" category="1" seances="1">980</price>
<price id="321" tarif="18" category="2" seances="1">300</price>
<price id="319" tarif="19" category="2" seances="1">490</price>
<price id="320" tarif="20" category="2" seances="1">490</price>
</prices>
<qty>
<seances>
<seance id="3" date="1">Требуется запрос даты сеанса</seance>
<seance id="4">NO_LIMIT</seance>
<seance id="5">NO_LIMIT</seance>
<seance id="6">NO_LIMIT</seance>
<seance id="7">NO_LIMIT</seance>
<seance id="8">NO_LIMIT</seance>
</seances>
</qty>
<client_info>
<field id="0">E-mail</qty>
<client_info>
</set>
<error id="0"><error>
</voxxter>
4) Ответ сервера Voxxter на запрос сообщения M1 для услуги, с сеансами и местами.
<voxxter>
<set id="2774">
<title>
Театр имени М.А. Булгакова - Билет на спектакль "Мастер и Маргарита"
</title>
<prices>
<price id="3956" category="1" place_category="11165" seances="1">1500</price>
</prices>
<qty>
<seances>
<seance id="3" seats="1">
<seat id="11243">Расположение Партер >> Ряд 9 >> Место 7</seat>
<seat id="11244">Расположение Партер >> Ряд 9 >> Место 8</seat>
</seance>
</seances>
</qty>
<client_info>
<field id="0">E-mail</qty>
<client_info>
</set>
<error id="0"><error>
</voxxter>
5) Ответ сервера Voxxter на запрос сообщения M1 для услуги, по которой закончилась квота билетов.
<voxxter>
<set id="2772">
<title>
Автобусная экскурсия "Главные вещи советского авангарда"
</title>
<qty>
<error>Билеты закончились</error>
</qty>
</set>
<error id="0"><error>
</voxxter>
Заказ билета (сообщение М2).
Запрос осуществляется путем отправки сообщения M2 по адресу: http://api.voxxter.ru/agent/
1) Запрос билетов без мест. Параметры сообщения:
| Ключ |
Имя параметра |
Описание значения параметра |
| M |
Идентификатор сообщения |
= 2 |
| L |
ключ агента |
= S(key) – уникальный не секретный идентификатор агента. |
| Sid |
ID билета |
= ID билета (тэг <set>, блок <tickets>) справочника событий и мест. Подробнее о справочниках в разделе "Для информационных ресурсов". |
| Date |
Дата сеанса - необязательный параметр |
= Дата в формате "DD.MM.YYYY". Необходим только для получения информации о наличии билетов для услуг с регулярными сеансами. Смомтри подробнее ниже. |
| Pid |
ID цены |
= ID цены билета (<prices> <price id="">) из ответа сообщения M1. Допускается через запятую, не более 5 pid в одном запросе. |
| qty |
Количество билетов |
= число <= 10 . Должно быть указано столько же чисел, сколько в поле pid. Данный параметр не нужно указывать, если есть параметр plc (смотрит ниже). |
| snc |
ID сеанса - необязательный параметр |
= ID сеанса из(<seances><seance id="">) сообщения M1. Допускается только 1 значение сеанса в одном запросе. |
| btn |
Единый идентификатор события/места |
= button_id из(<event><button_id> или <place><button_id>) справочника событий и мест. Подробнее о справочниках в разделе "Для информационных ресурсов". |
| cif_0 |
E-mail клиента |
= E-mail клиента для отправки билета. |
| cif_XX |
Поле данных клиента |
= значение данных полученных от клиента. ХХ - ID поля данных из (<client_info><field id="ХХ">) сообщения М1. Необходимо передавать все указанные в сообщении M1 поля, формируя для каждого параметр вида cif_XX. |
| S |
Подпись собщения |
= значение хеш -функции (SHA1) от секретного пароля агента (выдается при заключении договора) и всех указанных выше параметров сообщения. |
2) Запрос билетов с местами. Параметры сообщения:
| Ключ |
Имя параметра |
Описание значения параметра |
| M |
Идентификатор сообщения |
= 2 |
| L |
ключ агента |
= S(key) – уникальный не секретный идентификатор агента. |
| Sid |
ID билета |
= ID билета (тэг <set>, блок <tickets>) справочника событий и мест. Подробнее о справочниках в разделе "Для информационных ресурсов". |
| Date |
Дата сеанса |
= Дата в формате "DD.MM.YYYY" - необязательный параметр. Необходим только для получения информации о наличии билетов для услуг с регулярными сеансами. Смомтри подробнее ниже. |
| snc |
ID сеанса |
= ID сеанса из(<seances><seance id="">) сообщения M1. Допускается только 1 значение сеанса в одном запросе. |
| plc |
ID места |
= ID места из(<seances><seance><seat id="">) сообщения M1. Через запятую может быть указано не более 5 мест. |
| btn |
Единый идентификатор события/места |
= button_id из(<event><button_id> или <place><button_id>) справочника событий и мест. Подробнее о справочниках в разделе "Для информационных ресурсов". |
| cif_0 |
E-mail клиента |
= E-mail клиента для отправки билета. |
| cif_XX |
Поле данных клиента |
= значение данных полученных от клиента. ХХ - ID поля данных из (<client_info><field id="ХХ">) сообщения М1. Необходимо передавать все указанные в сообщении M1 поля, формируя для каждого параметр вида cif_XX. |
| S |
Подпись собщения |
= значение хеш -функции (SHA1) от секретного пароля агента (выдается при заключении договора) и всех указанных выше параметров сообщения. |
В ответ на отправку сообщения по адресу: http://api.voxxter.ru/agent/ cервер Voxxter выдает XML-файл вида:
<voxxter>
<order id="Идентификатор заказа">Сумма заказа<order>
<exp>Дата:Время когда истекает срок действия заказа<exp>
<error id="0"><error>
</voxxter>
Если запрос содержит ошибку, то ответ:
<voxxter>
<error id="Идентификатор ошибки">Текст ошибки<error>
</voxxter>
ВАЖНО: Успешно сформированный заказ является основанием получения средств от клиента для оплаты билетов.
Время жизни заказа в неоплаченном состоянии ограничено в связи с необходимостью бронирования билета до его оплаты.
Осуществлять запрос на получение билетов (сообщение М3) нужно только после получения от клиента подтверждения об оплате билета.
Получение билета (сообщение М3).
Запрос осуществляется путем отправки сообщения M3 по адресу: http://api.voxxter.ru/agent/
Параметры сообщения:
| Ключ |
Имя параметра |
Описание значения параметра |
| M |
Идентификатор сообщения |
= 3 |
| L |
ключ агента |
= S(key) – уникальный не секретный идентификатор агента. |
| Oid |
ID заказа |
= ID заказа (<order id="">) из ответа сообщения M2. |
| S |
Подпись собщения |
= значение хеш -функции (SHA1) от секретного пароля агента (выдается при заключении договора) и всех указанных выше параметров сообщения. |
В ответ на отправку сообщения по адресу: http://api.voxxter.ru/agent/ cервер Voxxter выдает XML-файл вида:
<voxxter>
<tickets>
<ticket id="номер билета">
<code type="Тип кода">Код билета</code>
<set id="идентификатор билета">Название услуги предоставляемой по билету</set>
<ExDate from="DD.MM.YYYY HH:MM:SS" till="DD.MM.YYYY HH:MM:SS" />
<category id="ID тарифа предоставляемой услуги">
Название тарифа предоставляемой услуги
</category>
<tarif id="ID тарифа предоставляемой услуги"> {!необязательный параметр}
Название тарифа предоставляемой услуги
</tarif>
<duration id="ID длительности предоставляемой услуги">{!необязательный параметр}
Название длительности предоставляемой услуги
</duration>
<seance id="Идентификатор сеанса">{!необязательный параметр}
Дата сеанса
</seance>
<seat id="Идентификатор места">{!необязательный параметр}
Название места
</seat>
<price id="Идентификатор цены">
Сумма цены в рублях
</price>
<url>
Ссылка на билет на Voxxter.ru
</url>
</ticket>
...
<ticket id="номер билета">...</ticket>
</tickets>
<error id="0"><error>
</voxxter>
Если запрос содержит ошибку, то ответ:
<voxxter>
<error id="Идентификатор ошибки">Текст ошибки<error>
</voxxter>
ВАЖНО: Запрос сообщения М3 является основанием для списания средств с депозита агента по продаже билетов. Данное условие закрепляется положениями агентсткого договора.
Аннуляция билета (сообщение М4).
Запрос осуществляется путем отправки сообщения M4 по адресу: http://api.voxxter.ru/agent/
Параметры сообщения:
| Ключ |
Имя параметра |
Описание значения параметра |
| M |
Идентификатор сообщения |
= 4 |
| L |
ключ агента |
= S(key) – уникальный не секретный идентификатор агента. |
| tid |
ID билета |
= ID билета (<ticket id="">) из ответа сообщения M3. |
| S |
Подпись собщения |
= значение хеш -функции (SHA1) от секретного пароля агента (выдается при заключении договора) и всех указанных выше параметров сообщения. |
В ответ на отправку сообщения по адресу: http://api.voxxter.ru/agent/ cервер Voxxter выдает XML-файл вида:
<voxxter>
<ticket id="номер билета">
<code>Аннулирован</code>
<set id="идентификатор билета">Название услуги предоставляемой по билету</set>
</ticket>
<error id="0"><error>
</voxxter>
Если запрос содержит ошибку, то ответ:
<voxxter>
<error id="Идентификатор ошибки">Текст ошибки<error>
</voxxter>
ВАЖНО: Аннуляция билета возможна только для неактивированных билетов с неистекшим сроком действия. Для билетов с сеансами возврат билетов возможен не позднее 3х рабочих дней до сеанса.
