26 KiB
Спецификация протокола взаимной продажи билетов на транзиные рейсы
Версия документа: 2.0
Дата изменения: 24.09.2018
Изменения в версии 2.0
- Уточнения в коментариях
- В ключ маршрута добавлен код перевозчика
- Метод редактирования билета
- Тип билета
Введение
Данный документ содержит спецификацию протокола AVS5RS, предназначенного для организации взаимной продажи билетов меджу автовокзалами на транзитные рейсы. Для унификации в протоколе используются термины UID остановочного пункта и ключ маршрута. UID остановочного пункта это ID станции одинаковый на всех вокзалах. Ключ маршрута это структура состоящая из:
- UID начальной станции
- UID конечной станции
- время выхода из начальной станции
- индивидуальный номер перевозчика (ИНН,РНН)
Описание протокола
Общие сведения
Обмен данными в протоколе AVS5RS производится через протокол HTTP. Передача и прием данных производится в формате XML, с использованием кодировки UTF-8.
Все запросы оправляются методом POST. Каждый метод протокола реализуется через отдельный URL, который строится относительно базового адреса сервиса, далее обозначаемого как [BASE_URL].
Доступ к веб-сервису, реализующему протокол AVS5RS, должен быть закрыт с применением Basic-аутентификации. Допускается использование протокола HTTPS, контроля доступа по IP, передача данных через VPN-соединение.
Общие форматы данных:
Формат даты: yyyy-MM-dd
, формат даты и времени:
yyyy-MM-dd'T'HH:mm:ss
. Пример:
2016-09-07T13:10:00 (символ T латинский, обязательный) (секунды
обязательны). Время указано в часовом поясе сервера который
предоставляет контент.
Числа с плавающий точко в качестве разделителя используют точку. Дробная часть не обязательна и не более 2 знаков.
Все идентификаторы сущностей (id и uid) это строки, произвольного формата, длинной до 36 символов. Разрешенные символы: цифры, латинские буквы в любом регистре, и символы -={}[]$ Могут быть как искусственными (sequence) так и реальными значениями (номер билета, номер места и.т.д.)
Форматы данных XML
Ответы с сервера должны поступать по протоколу HTTP c кодом 200 и HTTP-заголовком “Content-Type”, имеющим значение “application/xml; charset=UTF-8”.
Тело XML- ответа должно начинаться с объявления
<?xml version="1.0" encoding="UTF-8"?>
. Регистр
названий тегов и атрибутов должен совпадать с регистром из примеров.
XML-ответ в обязательном порядке имеет корневой тег, название которого должно соответствовать формату "<НазваниеМетодаResponse>" (например EchoResponse, SearchTripsResponse) Если ответ корректный, то данные ответа содержатся во вложенном теге <Body>. Если ответ не корректный, информация об ошибке должна находиться во вложенном теге <Error>, который состоит из кода ошибки в теге <code> и описания ошибки в теге <message>. Код ошибок в приложении. Описание - это произвольные текст на русском языке, поясняющий причину ошибки. Некоторые методы допускают пустой ответ. Пустой ответ содержит только корневой тег.
Пустой ответ:
<?xml version="1.0" encoding="UTF-8"?>
<UpdateTicketResponse>
</UpdateTicketResponse>
Пример ответа в случае успешной обработки запроса:
<?xml version="1.0" encoding="UTF-8"?>
<EchoResponse>
<Body>
<message>Test</message>
</Body>
</EchoResponse>
Пример ответа в случае обработки запроса с ошибкой:
<?xml version="1.0" encoding="UTF-8"?>
<BookResponse>
<Error>
<code>ERROR</code>
<message>Место 5 занято</message>
</Error>
</BookResponse>
Методы протокола
getFreeSeats
Получение списка свободных мест для рейса между указанными станциями. В параметре принимает ключ маршрута, дату и UIDы станции отправления и назначения пассажира. В случае если рейс начинается в одних сутка а заканчивается в других, необходимо передавать дату в которой рейс находится в станции отправления пассажира.
URL: [BASE_URL]/transit/getFreeSeats
Запрос:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GetFreeSeatsRequest>
<!-- ключ маршрута -->
<RouteKey>
<!-- UID станции отправления рейса -->
<dispatchStationUid>523243243209840293840293849895781093</dispatchStationUid>
<!-- UID конечной станции -->
<arrivalStationUid>90929359890589203498093209904288</arrivalStationUid>
<!-- время отправления со станции отпраления. в часовом поясе станции отправления. -->
<dispatchTime>10:00:00</dispatchTime>
<!-- ИНН перевозчика -->
<carrierCode>141478737450</carrierCode>
</RouteKey>
<!-- Дата отправления рейса со станции посадки поссажира -->
<date>2017-08-11</date>
<!-- UID станции посадки пассажира -->
<dispatchStationUid>hhwrl23kjhjj434kjljkshakjlk2j3l2</dispatchStationUid>
<!-- UID станции высадки пассажира -->
<arrivalStationUid>34l5klk435l435j34jjjk345jjk344CC</arrivalStationUid>
</GetFreeSeatsRequest>
Ответ:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GetFreeSeatsResponse>
<Body>
<TransitSeat>
<!-- ID места. Обязателен -->
<seatId>26</seatId>
<!-- Номер места места. Обязателен -->
<seatNum>26</seatNum>
</TransitSeat>
<TransitSeat>
<seatId>29</seatId>
<seatNum>29</seatNum>
</TransitSeat>
..............
<TransitSeat>
<seatId>47</seatId>
<seatNum>47</seatNum>
</TransitSeat>
</Body>
</GetFreeSeatsResponse>
book
Бронирование заказа. Бронь должна сохраняться в течение ограниченного времени, от 20 до 60 минут. Если в указанный период времени не поступает подтверждение оплаты через метод transit/confirm, то система реализующая протокол обязана отменить бронь. Допускается бронирование нескольких билетов в рамках одного заказа. В параметрах запроса передаются ключ маршрута, дата рейса идентификатор станции отправления, идентификатор станции назначения, информацию об агенте совершивший эту операцию. В случае если рейс начинается в одних сутка а заканчивается в других, необходимо передавать дату в которой рейс находится в станции отправления пассажира.
URL: [BASE_URL]/transit/bookOrder
Запрос:
<?xml version="1.0"?>
<TransitBookRequest>
<!-- ключ маршрута -->
<RouteKey>
<!-- UID станции отправления рейса -->
<dispatchStationUid>523243243209840293840293849895781093</dispatchStationUid>
<!-- UID конечной станции -->
<arrivalStationUid>90929359890589203498093209904288</arrivalStationUid>
<!-- время отправления со станции отпраления. в часовом поясе станции отправления. -->
<dispatchTime>10:00:00</dispatchTime>
<!-- ИНН перевозчика -->
<carrierCode>141478737450</carrierCode>
</RouteKey>
<!-- Дата отправления рейса со станции посадки поссажира -->
<date>2017-08-11</date>
<!-- UID станции посадки пассажира -->
<dispatchStationUid>hhwrl23kjhjj434kjljkshakjlk2j3l2</dispatchStationUid>
<!-- UID станции высадки пассажира -->
<arrivalStationUid>34l5klk435l435j34jjjk345jjk344CC</arrivalStationUid>
<Agent>
<!-- Имя агента. Не обязателен.-->
<name>ИП Твои билеты</name>
<!-- ИНН агента. Не обязателен.-->
<inn>2225555777</inn>
</Agent>
</TransitBookRequest>
Ответ:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TransitBookResponse>
<Body>
<TransitTicket>
<!-- ID билета на мастер сервере -->
<ticketId>25074373</ticketId>
<!-- Номер места -->
<seatNum>48</seatNum>
</TransitTicket>
</Body>
</TransitBookResponse>
confirm
URL: [BASE_URL]/transit/confirm
Подтверждение оплаты заказа. Переводит временную бронь созданную после операции book в постоянную.
Запрос:
<?xml version="1.0"?>
<TransitConfirmRequest>
<!-- ключ маршрута -->
<RouteKey>
<!-- UID станции отправления рейса -->
<dispatchStationUid>523243243209840293840293849895781093</dispatchStationUid>
<!-- UID конечной станции -->
<arrivalStationUid>90929359890589203498093209904288</arrivalStationUid>
<!-- время отправления со станции отпраления. в часовом поясе станции отправления. -->
<dispatchTime>10:00:00</dispatchTime>
<!-- ИНН перевозчика -->
<carrierCode>141478737450</carrierCode>
</RouteKey>
<Ticket>
<!-- ID билета. Обязательно -->
<ticketId>21326881</ticketId>
<Passenger>
<!-- Имя пассажира. Необязательно -->
<firstName>Ivan</firstName>
<!-- Фамилия пассажира. Необязательно -->
<lastName>Ivanov</lastName>
<!-- Отчество пассажира. Необязательно -->
<middleName>Ivanovich</middleName>
<!-- ID типа документа. Из справочника МИНТРАС. Необязательно -->
<docTypeId>0</docTypeId>
<!-- Номер документа. Необязательно -->
<docNum>0101</docNum>
<!-- Серия документа. Необязательно -->
<docSeries>010101</docSeries>
<!-- Дата рождения. Необязательно -->
<birthday>2000-01-01</birthday>
<!-- Пол. MALE FEMALE. Необязательно -->
<gender>MALE</gender>
</Passenger>
<!-- Серия билета. Необязательно -->
<ticketSeries>1232344</ticketSeries>
<!-- Номер билета. Необязательно -->
<ticketNumber>3432423423</ticketNumber>
<!-- Итоговая цена по которой продан билет. Необязательно -->
<price>1000</price>
<!-- Отношения между продовцом и поставщиком контента. OWN AGENT ATP. Необязательно -->
<relation>AGENT</relation>
</Ticket>
<Agent>
<!-- Имя агента. Не обязателен.-->
<name>ИП Твои билеты</name>
<!-- ИНН агента. Не обязателен.-->
<inn>2225555777</inn>
</Agent>
</TransitConfirmRequest>
Ответ:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TransitConfirmResponse/>
cancel
Отмена ранее забронированного места. Отмена билета допускается после оперций book и confirm.
URL: [BASE_URL]/transit/cancel
Запрос:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TransitCancelRequest>
<!-- ключ маршрута -->
<RouteKey>
<!-- UID станции отправления рейса -->
<dispatchStationUid>523243243209840293840293849895781093</dispatchStationUid>
<!-- UID конечной станции -->
<arrivalStationUid>90929359890589203498093209904288</arrivalStationUid>
<!-- время отправления со станции отпраления. в часовом поясе станции отправления. -->
<dispatchTime>10:00:00</dispatchTime>
<!-- ИНН перевозчика -->
<carrierCode>141478737450</carrierCode>
</RouteKey>
<!-- ID билета. Обязательно -->
<ticketId>4561143</ticketId>
<Agent>
<!-- Имя агента. Не обязателен.-->
<name>ИП Твои билеты</name>
<!-- ИНН агента. Не обязателен.-->
<inn>2225555777</inn>
</Agent>
</TransitCancelRequest>
Ответ:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TransitCancelResponse/>
getTripInfo
Возвращет информацию билетах на указанном рейсе. В выборку должны попасть билеты по следующему алгоритму.
from_st_uid = request.dispatchStationUid
to_st_uid = request.arrivalStationUid
indexs = словарь (UID станции) -> (Индекс станции в маршруте)
from_st_index = indexs(from_st_uid)
to_st_index = indexs(to_st_uid)
select *
from tickets t
where max(indexs(t.from_st_uid), from_st_index) <= min(indexs(t.to_st_uid), to_st_index)
and t.to_st_uid <> from_st_uid
В выборки первое условие находит пересечения отрезков:
- первый отрезок получен из индексов станций отправления и назначения билета
- второй отрезок получен из индексов станций параметров запроса
Второе условие отсекает билеты у которых станция назначения совпадает с станцией отправления из парамеров. В случае если рейс начинается в одних сутка а заканчивается в других, необходимо передавать дату в которой рейс находится в станции TransitTripInfoRequest/dispatchStationUid.
URL: [BASE_URL]/transit/getTripInfo
Запрос:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TransitTripInfoRequest>
<!-- ключ маршрута -->
<RouteKey>
<!-- UID станции отправления рейса -->
<dispatchStationUid>523243243209840293840293849895781093</dispatchStationUid>
<!-- UID конечной станции -->
<arrivalStationUid>90929359890589203498093209904288</arrivalStationUid>
<!-- время отправления со станции отпраления. в часовом поясе станции отправления. -->
<dispatchTime>10:00:00</dispatchTime>
<!-- ИНН перевозчика -->
<carrierCode>141478737450</carrierCode>
</RouteKey>
<!-- Дата отправления рейса со станции посадки поссажира -->
<date>2017-08-11</date>
<!-- UID станции посадки пассажира. Не обязательный. Если не указан, то равен станции отправления рейса -->
<dispatchStationUid>523243243209840293840293849895781093</dispatchStationUid>
<!-- UID станции высадки пассажира. Не обязательный. Если не указан, то равен конечной станции рейса -->
<arrivalStationUid>90929359890589203498093209904288</arrivalStationUid>
</TransitTripInfoRequest>
Ответ:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TransitTripInfoResponse>
<Body>
<Ticket>
<!-- UID станции посадки пассажира. -->
<dispatchStationUid>E19A767A4C4C43F3855E10DA31CD3749</dispatchStationUid>
<!-- UID станции высадки пассажира. -->
<arrivalStationUid>AE751908D644441298AEBD4001871311</arrivalStationUid>
<!-- ID билета. -->
<ticketId>4562182</ticketId>
<!-- серия билета. -->
<ticketSeries>2202022202</ticketSeries>
<!-- номер билета. -->
<ticketNumber>2457677</ticketNumber>
<!-- место билета. -->
<seatNum>3</seatNum>
<!-- цена билета. -->
<price>470</price>
</Ticket>
<Ticket>
<dispatchStationUid>AE751908D644441298AEBD4001871311</dispatchStationUid>
<arrivalStationUid>25CBF1CE4E224C0A85C4CCEAD3E4C537</arrivalStationUid>
<ticketId>4562669</ticketId>
<seatNum>3</seatNum>
</Ticket>
<Ticket>
<dispatchStationUid>E19A767A4C4C43F3855E10DA31CD3749</dispatchStationUid>
<arrivalStationUid>88184B22DA28440590D6202D2014E5F3</arrivalStationUid>
<Passenger>
<!-- Имя пассажира. Необязательно -->
<firstName>Ivan</firstName>
<!-- Фамилия пассажира. Необязательно -->
<lastName>Ivanov</lastName>
<!-- Отчество пассажира. Необязательно -->
<middleName>Ivanovich</middleName>
<!-- ID типа документа. Из справочника МИНТРАС. Необязательно -->
<docTypeId>0</docTypeId>
<!-- Номер документа. Необязательно -->
<docNum>0101</docNum>
<!-- Серия документа. Необязательно -->
<docSeries>010101</docSeries>
<!-- Дата рождения. Необязательно -->
<birthday>2000-01-01</birthday>
<!-- Пол. MALE FEMALE. Необязательно -->
<gender>MALE</gender>
</Passenger>
<ticketId>4553771</ticketId>
<ticketSeries>2202982202</ticketSeries>
<ticketNumber>41159</ticketNumber>
<seatNum>4</seatNum>
<price>167</price>
</Ticket>
<!-- Вместимость автобуса -->
<maxSeats>43</maxSeats>
<!-- Количество свободных мест между указанными станциями -->
<freeSeats>22</freeSeats>
<Carrier>
<!-- Имя перевозчика -->
<name>ПАП города N</name>
<!-- ИНН перевозчика -->
<inn>4534995945</inn>
</Carrier>
</Body>
</TransitTripInfoResponse>
getRouteInfo
Возвращает информацию по маршруту. Информация содержит название и описание остановочных пунктов маршрута.
URL: [BASE_URL]/transit/getRouteInfo
Запрос:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TransitRouteInfoRequest>
<!-- ключ маршрута -->
<RouteKey>
<!-- UID станции отправления рейса -->
<dispatchStationUid>523243243209840293840293849895781093</dispatchStationUid>
<!-- UID конечной станции -->
<arrivalStationUid>90929359890589203498093209904288</arrivalStationUid>
<!-- время отправления со станции отпраления. в часовом поясе станции отправления. -->
<dispatchTime>10:00:00</dispatchTime>
<!-- ИНН перевозчика -->
<carrierCode>141478737450</carrierCode>
</RouteKey>
</TransitRouteInfoRequest>
Ответ:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TransitRouteInfoResponse>
<Body>
<!-- Название маршрута. Обязательно -->
<name>Белокуриха - Рубцовск</name>
<RouteItem>
<!-- порядок остановочного пункта. Обязательно -->
<order>1</order>
<!-- Название остановочного пункта. Обязательно -->
<stationName>Белокуриха</stationName>
<!-- UID остановочного пункта. Обязательно -->
<stationUid>E19A767A4C4C43F3855E10DA31CD3749</stationUid>
<!-- Расстояние. Необязательно -->
<distance>0</distance>
</RouteItem>
<RouteItem>
<order>2</order>
<stationName>Быканов Мост</stationName>
<stationUid>0ae247cb-b7b3-41df-8814-04065f7867fc</stationUid>
<distance>10</distance>
</RouteItem>
.........
<RouteItem>
<order>17</order>
<stationName>Рубцовск</stationName>
<stationUid>25CBF1CE4E224C0A85C4CCEAD3E4C537</stationUid>
<distance>559</distance>
</RouteItem>
</Body>
</TransitRouteInfoResponse>
setStationInfo
Устанавливает UID для конкретной станции. ID станции может быть получен ранее использую протокол продажи AVS5RS
URL: [BASE_URL]/transit/setStationInfo
Запрос:
<?xml version="1.0" encoding="UTF-8"?>
<SetStationInfoRequest>
<stationId>423423</stationId>
<uid>25CBF1CE4E224C0A85C4CCEAD3E4C537</uid>
</SetStationInfoRequest>
Ответ:
<?xml version="1.0" encoding="UTF-8"?>
<SetStationInfoResponse/>
TransitUpdateTicket
Редактирование атрибутов билета. Пока реализовано только редактирование флага явки.
URL: [BASE_URL]/transit/updateTickets
Запрос:
<TransitUpdateTicketRequest>
<!-- ключ маршрута -->
<RouteKey>
<!-- UID станции отправления рейса -->
<dispatchStationUid>523243243209840293840293849895781093</dispatchStationUid>
<!-- UID конечной станции -->
<arrivalStationUid>90929359890589203498093209904288</arrivalStationUid>
<!-- время отправления со станции отпраления. в часовом поясе станции отправления. -->
<dispatchTime>10:00:00</dispatchTime>
<!-- ИНН перевозчика -->
<carrierCode>141478737450</carrierCode>
</RouteKey>
<Ticket>
<ticketId>5543543</ticketId>
<isGone>true</isGone>
</Ticket>
<Ticket>
<ticketId>545354</ticketId>
<isGone>false</isGone>
</Ticket>
</TransitUpdateTicketRequest>
Ответ:
<TransitUpdateTicketResponse>
</TransitUpdateTicketResponse>