Спецификация протокола взаимной продажи билетов на транзиные рейсы =========================================================================== **Версия документа: 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-ответ в обязательном порядке имеет корневой тег, название которого должно соответствовать формату "<НазваниеМетодаResponse>" (например EchoResponse, SearchTripsResponse) Если ответ корректный, то данные ответа содержатся во вложенном теге <Body>. Если ответ не корректный, информация об ошибке должна находиться во вложенном теге <Error>, который состоит из кода ошибки в теге <code> и описания ошибки в теге <message>. Код ошибок в приложении. Описание - это произвольные текст на русском языке, поясняющий причину ошибки. Некоторые методы допускают пустой ответ. Пустой ответ содержит только корневой тег. Пустой ответ: ```xml ``` Пример ответа в случае успешной обработки запроса: ```xml Test ``` Пример ответа в случае обработки запроса с ошибкой: ```xml ERROR Место 5 занято ``` Методы протокола ---------------- ### getFreeSeats Получение списка свободных мест для рейса между указанными станциями. В параметре принимает ключ маршрута, дату и UIDы станции отправления и назначения пассажира. В случае если рейс начинается в одних сутка а заканчивается в других, необходимо передавать дату в которой рейс находится в станции отправления пассажира. **URL: \[BASE\_URL\]/transit/getFreeSeats** Запрос: ```xml 523243243209840293840293849895781093 90929359890589203498093209904288 10:00:00 141478737450 2017-08-11 hhwrl23kjhjj434kjljkshakjlk2j3l2 34l5klk435l435j34jjjk345jjk344CC ``` Ответ: ```xml 26 26 29 29 .............. 47 47 ``` ### book Бронирование заказа. Бронь должна сохраняться в течение ограниченного времени, от 20 до 60 минут. Если в указанный период времени не поступает подтверждение оплаты через метод transit/confirm, то система реализующая протокол обязана отменить бронь. Допускается бронирование нескольких билетов в рамках одного заказа. В параметрах запроса передаются ключ маршрута, дата рейса идентификатор станции отправления, идентификатор станции назначения, информацию об агенте совершивший эту операцию. В случае если рейс начинается в одних сутка а заканчивается в других, необходимо передавать дату в которой рейс находится в станции отправления пассажира. **URL: \[BASE\_URL\]/transit/bookOrder** Запрос: ```xml 523243243209840293840293849895781093 90929359890589203498093209904288 10:00:00 141478737450 2017-08-11 hhwrl23kjhjj434kjljkshakjlk2j3l2 34l5klk435l435j34jjjk345jjk344CC ИП Твои билеты 2225555777 ``` Ответ: ```xml 25074373 48 ``` ### confirm **URL: \[BASE\_URL\]/transit/confirm** Подтверждение оплаты заказа. Переводит временную бронь созданную после операции book в постоянную. Запрос: ```xml 523243243209840293840293849895781093 90929359890589203498093209904288 10:00:00 141478737450 21326881 Ivan Ivanov Ivanovich 0 0101 010101 2000-01-01 MALE 1232344 3432423423 1000 AGENT ИП Твои билеты 2225555777 ``` Ответ: ```xml ``` ### cancel Отмена ранее забронированного места. Отмена билета допускается после оперций book и confirm. **URL: \[BASE\_URL\]/transit/cancel** Запрос: ```xml 523243243209840293840293849895781093 90929359890589203498093209904288 10:00:00 141478737450 4561143 ИП Твои билеты 2225555777 ``` Ответ: ```xml ``` ### 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 ``` В выборки первое условие находит пересечения отрезков: 1. первый отрезок получен из индексов станций отправления и назначения билета 2. второй отрезок получен из индексов станций параметров запроса Второе условие отсекает билеты у которых станция назначения совпадает с станцией отправления из парамеров. В случае если рейс начинается в одних сутка а заканчивается в других, необходимо передавать дату в которой рейс находится в станции TransitTripInfoRequest/dispatchStationUid. **URL: \[BASE\_URL\]/transit/getTripInfo** Запрос: ```xml 523243243209840293840293849895781093 90929359890589203498093209904288 10:00:00 141478737450 2017-08-11 523243243209840293840293849895781093 90929359890589203498093209904288 ``` Ответ: ```xml E19A767A4C4C43F3855E10DA31CD3749 AE751908D644441298AEBD4001871311 4562182 2202022202 2457677 3 470 AE751908D644441298AEBD4001871311 25CBF1CE4E224C0A85C4CCEAD3E4C537 4562669 3 E19A767A4C4C43F3855E10DA31CD3749 88184B22DA28440590D6202D2014E5F3 Ivan Ivanov Ivanovich 0 0101 010101 2000-01-01 MALE 4553771 2202982202 41159 4 167 43 22 ПАП города N 4534995945 ``` ### getRouteInfo Возвращает информацию по маршруту. Информация содержит название и описание остановочных пунктов маршрута. **URL: \[BASE\_URL\]/transit/getRouteInfo** Запрос: ```xml 523243243209840293840293849895781093 90929359890589203498093209904288 10:00:00 141478737450 ``` Ответ: ```xml Белокуриха - Рубцовск 1 Белокуриха E19A767A4C4C43F3855E10DA31CD3749 0 2 Быканов Мост 0ae247cb-b7b3-41df-8814-04065f7867fc 10 ......... 17 Рубцовск 25CBF1CE4E224C0A85C4CCEAD3E4C537 559 ``` ### setStationInfo Устанавливает UID для конкретной станции. ID станции может быть получен ранее использую протокол продажи AVS5RS **URL: \[BASE\_URL\]/transit/setStationInfo** Запрос: ```xml 423423 25CBF1CE4E224C0A85C4CCEAD3E4C537 ``` Ответ: ```xml ``` ### TransitUpdateTicket Редактирование атрибутов билета. Пока реализовано только редактирование флага явки. **URL: \[BASE\_URL\]/transit/updateTickets** Запрос: ```xml 523243243209840293840293849895781093 90929359890589203498093209904288 10:00:00 141478737450 5543543 true 545354 false ``` Ответ: ```xml ```