Спецификация на протокол AVS5RS продажи билетов для автотранспорта ================================================================== **Версия документа: 2.1** **Дата изменения: 06.09.2017** Введение ======== Данный документ содержит спецификацию протокола AVS5RS, предназначенного для организации удаленной продажи билетов на автотранспорте. Спецификация предназначена для унификации процесса обмена данными между перевозчиками, автовокзалами и агентами по продаже билетов. Описание протокола ================== Общие сведения -------------- Обмен данными в протоколе 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) это строки, произвольного формата, длинной до 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 занято ``` Методы протокола ---------------- ### echo Используется для проверки доступности сервиса. Метод принимает в параметре произвольную строку и возвращает её в теле ответа. **URL: \[BASE\_URL\]/sales/echo** Запрос: ```xml Test ``` Ответ: ```xml Test ``` ### getDispatchStations Метод получения станций отправления. Продажа происходит от станции отправления до станции назначения, поэтому метод должен вернуть хотя бы один элемент. Обычно станциями отправления являются автовокзалы или автоматизированные остановочные пункты с функцией продажи билетов. **URL: \[BASE\_URL\]/sales/getDispatchStations** Запрос: ```xml ``` Ответ: ```xml 983 ВДНХ АС Москва 45000000000 853 Варшавская АС Москва 45000000000 6 Красногвардейская АС Москва 45000000000 ``` ### getArrivalStations Метод получения станций назначения от станции отправления. В параметре принимает идентификатор станции отправления. Станциями назначения могут быть любые остановочные пункты до которых есть хотя бы один рейс. Если станций назначения нет, метод должен вернуть пустой список. В случае отсутствия станций назначения для указанной станции отправления возвращать пустой ответ. **URL: \[BASE\_URL\]/sales/getArrivalStations** Запрос: ```xml 983 ``` Ответ: ```xml 1069 Рыбинск Ярославская область 78415000000 1018 Сергиев Посад Московская область 46215501000 1084 Углич Ярославская область 78420000000 1078 Утена Литва ``` ### searchTrips Метод возвращает список рейсов от станции отправления до станции назначения на заданную дату. В параметрах передается идентификатор станции отправления, идентификатор станции назначения и дата. В случае отсутствия рейсов для указанных параметров возвращать пустой ответ. Рейсы должны быть отсортированы по дате отправления. **URL: \[BASE\_URL\]/sales/searchTrips** Запрос: ```xml 983 678 2016-07-12 ``` Ответ: ```xml 570104 000 d1e39ba7-b9d6-48f6-a4ba-03674a381c90 ВДНХ АС - Пенза 2016-07-13T19:30:00 2016-07-14T05:30:00 983 ВДНХ АС 744 Пенза 1391 ИП Ерашова Валентина Анатольевна ИНН 582700056092 49 Мест Категория ТС "М3" INTERREGIONAL ON_SALE REGULAR 49 49 d13945a8-7017-46ab-b1e6-ede1e89317ad 279e7c39-2570-44e0-83e6-d1f473d50e0f 10:00:00 570105 000 904ede1a-95af-4db3-928f-e9a2c6302278 ВДНХ АС - Пенза 2016-07-13T21:30:00 2016-07-14T07:30:00 983 ВДНХ АС 744 Пенза 1391 ИП Ерашова Валентина Анатольевна ИНН 582700056092 49 Мест Категория ТС "М3" INTERREGIONAL ON_SALE 49 49 ``` ### getFreeSeats Получение списка свободных мест для рейса. В параметре принимает идентификатор рейса, идентификатор станции отправления и идентификатор станции назначения. **URL: \[BASE\_URL\]/sales/getFreeSeats** Запрос: ```xml 570101 983 1080 ``` Ответ: ```xml 17926 1 17927 2 17928 3 ``` ### getTicketTypes Получение списка типов билетов, доступных для продажи. В параметре принимает идентификатор рейса, идентификатор станции отправления и идентификатор станции назначения. **URL: \[BASE\_URL\]/sales/getTicketTypes** Запрос: ```xml 570101 983 1080 ``` Ответ: ```xml 1#1#0 Полный 1391 PASSENGER 38#6#0 Детский 696 PASSENGER 0#0#0 Багажный 40 BAGGAGE ``` ### getDocumentTypes Получение списка типов документов, допустимых для удостоверения личности при оформлении билетов через интернет. Система должна предоставить хотя бы один тип документа. Допустимые идентификаторы и названия документов перечислены в таблице 1 Приказа Минтранса РФ от 19 июля 2012 г. N 243 "Об утверждении Порядка формирования и ведения автоматизированных централизованных баз персональных данных о пассажирах и персонале (экипаже) транспортных средств, а также предоставления содержащихся в них данных". Текст документа в системе ГАРАНТ: **URL: \[BASE\_URL\]/sales/getDocumentTypes** Запрос: ```xml 570101 983 1080 ``` Ответ: ```xml 0 Паспорт РФ 3 Паспорт иностранного гражданина 4 Свидетельство о рождении ``` Таблица 1. Коды документов, удостоверяющих личность, при передаче в АЦБПДП --------------------------------------------------------------- ------------------------------------------------------------------------- Код Наименование документа --- ------------------------------------------------------------------- 0 Паспорт гражданина Российской Федерации 1 Паспорт моряка 2 Общегражданский заграничный паспорт гражданина Российской Федерации 3 Паспорт иностранного гражданина 4 Свидетельство о рождении 5 Удостоверение личности военнослужащего 6 Удостоверение личности лица без гражданства 7 Временное удостоверение личности, выдаваемое органами внутренних дел 8 Военный билет военнослужащего срочной службы 9 Вид на жительство иностранного гражданина или лица без гражданства 10 Справка об освобождении из мест лишения свободы 11 Паспорт гражданина СССР 12 Паспорт дипломатический 13 Паспорт служебный (кроме паспорта моряка и дипломатического) 14 Свидетельство о возвращении из стран СНГ 15 Справка об утере паспорта -------------------------------------------------------------------------- ### getTripStops Метод возвращает список остановочных пунктов для рейса. В параметре принимает идентификатор рейса. Информация имеет справочный характер. **URL: \[BASE\_URL\]/sales/getTripStops** Запрос: ```xml 569839 ``` Ответ: ```xml 1011 Скопин (трасса) Рязанская область 2016-07-14T16:20:00 2016-07-13T21:00:00 10 260 1177 1010 Мичуринск (трасса) Тамбовская область 2016-07-14T16:20:00 2016-07-13T21:00:00 10 385 1177 818 Тамбов (трасса) Тамбовская область 2016-07-14T16:20:00 2016-07-13T21:00:00 10 455 1177 ``` ### bookOrder Бронирование заказа. Бронь должна сохраняться в течение ограниченного времени, от 20 до 60 минут. Если в указанный период времени не поступает подтверждение оплаты через метод confirmOrder(), то система реализующая протокол обязана отменить бронь. Метод должен выполнить все возможные проверки корректности переданных данных. Если это необходимо, система обязана самостоятельно проверить правильность ввода персональных данных. В случае ошибки заказ не должен быть создан. Допускается бронирование нескольких билетов в рамках одного заказа. В параметрах запроса передаются идентификатор рейса, идентификатор станции отправления, идентификатор станции назначения, информацию о бронируемых билетах, информацию об агенте совершивший эту операцию. Информации о бронируемых билетах включает в себя идентификатор типа билета, идентификатор места и информацию о пассажире. Информация об агенте включает в себя наименование и ИНН агента. **URL: \[BASE\_URL\]/sales/bookOrder** Запрос: ```xml 570101 983 1080 25862 1#1#0 goxUEpWCud sKZXIloHFn pCaEgXgfWO jwcmdIrmcc iFAElsnFHn 1 1986-01-01 RU MALE 999-888-77-66 NjaqSdsD SDdsqlkr JFn ИП Твои билеты 2225555777 ``` Ответ: ```xml 9828350 30 ``` ### getOrder Получение информации о заказе. В параметрах принимает идентификатор заказа, полученный в результате bookOrder. Метод должен вернуть такое же количество билетов сколько было передано при вызове bookOrder. Метод должен работать на любом этапе жизни заказа т.е. после создания, подтверждения, отмены, возврата. **URL: \[BASE\_URL\]/sales/getOrder** Запрос: ```xml 9828350 ``` Ответ: ```xml 9828350 12435438 2016-07-13T05:48:15 RESERVED PASSENGER 1#1#0 000 ВДНХ АС - Рыбинск 19 Мест Категория ТС "М3" ООО "ВВМЛ" ИНН 7610074937 Перрон 11 2016-07-13T12:20:00 ВДНХ АС пл.Шарля де Голля напротив Космонавтов2А, 2016-07-13T16:20:00 Углич 1 Ckayuukvgn Bgkzxffotu Isdikvryin PUPrvbqlgU fRHEoBHVbG 1 1985-01-01 RU MALE 999-888-77-66 FewwLks Mq 0 0 0 СТРАХОВЩИК: ПАО "Росстрах"; 119991; г. Москва; ул. Большая Ордынка; д. 40; стр. ``` ### confirmOrder Подтверждение оплаты заказа. Данный метод должен вызываться только после того как заказ действительно был оплачен покупателем. Метод не должен делать проверок корректности заказа, все проверки должны выполняться в bookOrder или updateTicket. Вызов этого метода означает подтверждение правильного приема данных и получение денег от покупателя. В параметрах принимает идентификатор заказа, полученный в результате bookOrder и информацию об агенте который совершил операцию. Агент может измениять тариф билета, только при наличии прямого договора между агентом и перевозчиком, и соответствующего разрешения у агента. В этом случае агент обязан передать новый тариф для каждого билета. **URL: \[BASE\_URL\]/sales/confirmOrder** Запрос: ```xml 9828585 ИП Твои билеты 2225555777 100 0000002681 ``` Ответ: Ответ аналогичен ответу на запрос [getOrder](#getorder) c именем корневого тега ConfirmOrderResponse ### cancelTicket Отмена одного или нескольких билетов. Техническая операция, выполняет полный возврат билета без удержаний. Необходима при нештатных ситуациях: в случае сбоев ККМ или обнаружения ошибки выбора рейса, персональных данных. В параметрах принимает идентификаторы билета и информацию об агенте который совершил операцию. Все билеты должны быть обработы в рамках одной транзакции. т.е. если было передано 2 билета, первый был обработан а при обработке второго возникла ошибка то обработка первого должна быть отменена. Можно выполнять после создания заказа и в течении 5-30 минут после подтверждения заказа. При интеграции с сервисом GDS гарантируется, что переданные ticketId будут принадлежать одному заказу. Решение допускать ли передачу Id билетов из разных заказов остается за вокзалом, который реализует данный протокол. **URL: \[BASE\_URL\]/sales/cancelTicket** Запрос: ```xml 34 36 ИП Твои билеты 2225555777 ``` Ответ: Ответ аналогичен ответу на запрос [getOrder](#getorder) c именем корневого тега CancelTicketResponse. В ответе необходимо возвращать информацию только по обработанным билетам. ### returnTicket Возврат одного или нескольких билетов. При возврате возможны удержания. В параметрах принимает идентификатор билета и информацию об агенте который совершил операцию. Все билеты должны быть обработы в рамках одной транзакции. т.е. если было передано 2 билета, первый был обработан а при обработке второго возникла ошибка то обработка первого должна быть отменена. Билет можно вернуть только после подтверждения confirmOrder. При интеграции с сервисом GDS гарантируется, что переданные ticketId будут принадлежать одному заказу. Решение допускать ли передачу Id билетов из разных заказов остается за вокзалом, который реализует данный протокол. **URL: \[BASE\_URL\]/sales/returnTicket** Запрос: ```xml 35 36 ИП Твои билеты 2225555777 ``` Ответ: Ответ аналогичен ответу на запрос [getOrder](#getorder) c именем корневого тега ReturnTicketResponse. В ответе необходимо возвращать информацию только по обработанным билетам. ### updateTicket Изменение персональных данных пассажира в забронированном или проданном билете. В параметрах принимает идентификатор билета, информацию о пассажире и информацию об агенте который совершил операцию. **URL: \[BASE\_URL\]/sales/updateTicket** Запрос: ```xml 12435438 goxUEpWCud sKZXIloHFn pCaEgXgfWO jwcmdIrmcc iFAElsnFHn 1 1986-01-01 RU FEMALE ИП Твои билеты 2225555777 ``` Ответ: ```xml ``` Отличия от версии 1 ------------------- * Удален атрибут success. Анализ ошибки проиводится по наличию тега Error * Изменено именования корневых тегов ответа. * Отмена или возврат нескольких билетов одновременно. * Поля * Trip * Добавлено platform * Seat * Добавлено num * Удалено name * Удалено type * Passenger * Добавлено info * Добавлено phone * Ticket * Дабавлено repayment * Удалено chargeFare * Удалено chargeOthers * Удалено repaymentFare * Удалено repaymentOthers * Мелкие уточнения