Спецификация на протокол AVS5RS продажи билетов для автотранспорта
==================================================================
**Версия документа: 2.0**
**Дата изменения: 22.02.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. Коды документов, удостоверяющих личность, при передаче в АЦБПДП
---------------------------------------------------------------
-------------------------------------------------------------------------
Код Наименование документа
--- -------------------------------------------------------------------
00 Паспорт гражданина Российской Федерации
01 Паспорт моряка
02 Общегражданский заграничный паспорт гражданина Российской Федерации
03 Паспорт иностранного гражданина
04 Свидетельство о рождении
05 Удостоверение личности военнослужащего
06 Удостоверение личности лица без гражданства
07 Временное удостоверение личности, выдаваемое органами внутренних дел
08 Военный билет военнослужащего срочной службы
09 Вид на жительство иностранного гражданина или лица без гражданства
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
```
Ответ:
Ответ аналогичен ответу на запрос [getOrder](#getorder) c именем корневого тега ConfirmOrderResponse
### cancelTicket
Отмена одного или нескольких билетов. Техническая операция, выполняет полный возврат билета без
удержаний. Необходима при нештатных ситуациях: в случае сбоев ККМ или
обнаружения ошибки выбора рейса, персональных данных. В параметрах
принимает идентификаторы билета и информацию об агенте который совершил
операцию. Все билеты должны быть обработы в рамках одной транзакции.
т.е. если было передано 2 билета, первый был обработан а при обработке второго возникла ошибка
то обработка первого должна быть отменена.
Можно выполнять после создания заказа и в течении 5-30 минут
после подтверждения заказа.
**URL: \[BASE\_URL\]/sales/cancelTicket**
Запрос:
```xml
34
36
ИП Твои билеты
2225555777
```
Ответ:
Ответ аналогичен ответу на запрос [getOrder](#getorder) c именем корневого тега CancelTicketResponse. В ответе необходимо возвращать информацию только по обработанным билетам.
### returnTicket
Возврат одного или нескольких билетов. При возврате возможны удержания. В параметрах принимает
идентификатор билета и информацию об агенте который совершил операцию.
Все билеты должны быть обработы в рамках одной транзакции.
т.е. если было передано 2 билета, первый был обработан а при обработке второго возникла ошибка
то обработка первого должна быть отменена.
Билет можно вернуть только после подтверждения confirmOrder.
**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
* Мелкие уточнения