Спецификация протокола взаимной продажи билетов на транзиные рейсы
===========================================================================
**Версия документа: 1.0**
**Дата изменения: 06.09.2017**
Введение
========
Данный документ содержит спецификацию протокола 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
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
2017-08-11
hhwrl23kjhjj434kjljkshakjlk2j3l2
34l5klk435l435j34jjjk345jjk344CC
ИП Твои билеты
2225555777
```
Ответ:
```xml
25074373
48
```
### confirm
**URL: \[BASE\_URL\]/transit/confirm**
Подтверждение оплаты заказа. Переводит временную бронь созданную после операции book в постоянную.
Запрос:
```xml
523243243209840293840293849895781093
90929359890589203498093209904288
10:00:00
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
4561143
ИП Твои билеты
2225555777
```
Ответ:
```xml
```
### getTripInfo
Возвращет информацию билетах на указанном рейсе.
В выборку должны попасть билеты у которых станции отправлени или назначения(не включительно) находятся между запрашиваемы станциями.
**URL: \[BASE\_URL\]/transit/getTripInfo**
Запрос:
```xml
523243243209840293840293849895781093
90929359890589203498093209904288
10:00:00
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
```
Ответ:
```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
```