# Введение
**Версия документа: 1.2**
**Дата изменения: 16.09.2016**
Для возможности продажи с использованием протокола AVS5RS необходимо реализовать сервис с использованием протокола HTTP. Все запросы оправляются методом POST.
Методы включают в себя справочные методы и методы продажи. Продажа состоит из двух этапов резервирование и подтверждение продажи.
Протокол должен быть защищен авторизацией через логин и пароль. Так же необходимо чтобы трафик передавался по защищенному каналу связи с использованием SSL или VPN.
## Методы сервиса
Все запросы должны передаваться по протоколу HTTP методом пост. В теле POST запроса и ответа передается XML фиксированного формата.
Каждый метод имеет отдельный URL. Через HTTP заголовок Content-Type передается значение `application/xml; charset=UTF-8`.
Этот заголовок указывает на тип содержимого запроса и его кодировку. Необходимо использовать только кодировку UTF-8.
### Формат ответа
Корневой тег XML ответа Response. У него есть обязательный атрибут success, который указывает корректно выполнился запрос или нет, значения true - корректно, false - нет.
Если ответ корректный, то данные ответа содержатся во вложенном теге Body. Если ответ не корректный, тег Body будет проигнорирован, а информация об ошибке должна
находиться во вложенном теге Error. Который состоит из кода ошибки и описания. Коды ошибок не регламентируются. Описание это произвольные тест, поясняющий причину ошибки.
Регистр названий тегов и атрибутов должен совпадать с регистром из примеров.
Все ответы должны приходить с HTTP кодом 200. Все XML ответы должны начинаться с объявления `` в котором указана кодировка содержимого.
Формат даты `yyyy-MM-dd`, формат даты и времени `yyyy-MM-dd'T'HH:mm:ss`, пример 2016-09-07T13:10:00 (символ T латинский, обязательный) (секунды обязательны).
Время указано в часовом поясе сервера который предоставляет контент.
Все идентификаторы сущностей (id) это строки, произвольного формата, длинной до 36 символов.
Корректный ответ:
```xml
Test
```
Не корректный ответ:
```xml
ERROR
Место 5 занято
```
### echo
Метод принимает в параметра произвольную строку и возвращает её в теле ответа. Не выполняет ни какой логики. Необходим для проверки доступен ли сервис.
**URL: /sales/echo**
Запрос:
```xml
Test
```
Ответ:
```xml
Test
```
### getDispatchStations
Метод получения станций отправления.
Продажа происходит от станции отправления до станции назначения, поэтому метод должен вернуть хотя бы один элемент.
Обычно станциями отправления являются автовокзалы или автоматизированные остановочные пункты с функцией продажи билетов.
**URL: /sales/getDispatchStations**
Запрос:
```xml
```
Ответ:
```xml
983
ВДНХ АС
Москва
45000000000
853
Варшавская АС
Москва
45000000000
6
Красногвардейская АС
Москва
45000000000
```
### getArrivalStations
Метод получения станций назначения от станции отправления. В параметра принимает идентификатор станции отправления.
Станциями назначения могут быть любые остановочные пункты до которых есть хотя бы один рейс.
Если станций назначения нет вернуть пустой список.
**URL: /sales/getArrivalStations**
Запрос:
```xml
983
```
Ответ:
```xml
1069
Рыбинск
Ярославская область
78415000000
1018
Сергиев Посад
Московская область
46215501000
1084
Углич
Ярославская область
78420000000
1078
Утена
Литва
```
### searchTrips
Метод возвращает список рейсов от станции отправления до станции назначения на заданную дату.
В параметрах передается идентификатор станции отправления, идентификатор станции назначения и дата.
**URL: /sales/searchTrips**
Запрос:
```xml
983
678
2016-07-12
```
Ответ:
```xml
570104
000
ВДНХ АС - Пенза
2016-07-13T19:30:00
2016-07-14T05:30:00
983
ВДНХ АС
744
Пенза
1391
ИП Ерашова Валентина Анатольевна
ИНН 582700056092
49 Мест Категория ТС "М3"
true
INTERREGIONAL
ON_SALE
49
49
570105
000
ВДНХ АС - Пенза
2016-07-13T21:30:00
2016-07-14T07:30:00
983
ВДНХ АС
744
Пенза
1391
ИП Ерашова Валентина Анатольевна
ИНН 582700056092
49 Мест Категория ТС "М3"
true
INTERREGIONAL
ON_SALE
49
49
```
### getFreeSeats
Получение списка свободных мест для рейса.
В параметра принимает идентификатор рейса, идентификтор станции отправления и идентификатор станции назначения.
**URL: /sales/getFreeSeats**
Запрос:
```xml
570101
983
1080
```
Ответ:
```xml
17926
Место 1
Сидячее
17927
Место 2
Сидячее
17928
Место 3
Сидячее
```
### getTicketTypes
Получение списка типов билетов, доступных для продажи.
В параметра принимает идентификатор рейса, идентификатор станции отправления и идентификатор станции назначения.
**URL: /sales/getTicketTypes**
Запрос:
```xml
570101
983
1080
/GetTicketTypesRequest>
```
Ответ:
```xml
1#1#0
Полный
1391
PASSENGER
38#6#0
Детский
696
PASSENGER
0#0#0
Багажный
40
BAGGAGE
```
### getDocumentTypes
Получение списка типов документов, допустимых при оформлении билетов. Система должна предоставить хотя бы один тип документа.
Рекомендуется использовать документы из (приказа)[http://base.garant.ru/70229008/] в Таблице 1.
В параметра принимает идентификатор рейса, идентификатор станции отправления и идентификатор станции назначения.
**URL: /sales/getDocumentTypes**
Запрос:
```xml
570101
983
1080
```
Ответ:
```xml
1
Паспорт РФ
52
Паспорт иностранного гражданина
40
Удостоверение (Казахстан)
2
Свидетельство о рождении
4
Удостоверение личности военнослужащего
55
Временное удостоверение ОВД
```
### getTripStops
Метод возвращает список остановочных пунктов для рейса.
В параметра принимает идентификатор рейса.
Метод информационный.
**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: /sales/bookOrder**
Запрос:
```xml
570101
983
1080
25862
1#1#0
goxUEpWCud
sKZXIloHFn
pCaEgXgfWO
jwcmdIrmcc
iFAElsnFHn
1
1986-01-01
RU
MALE
ИП Твои билеты
2225555777
```
Ответ:
```xml
9828350
30
```
### getOrder
Получение информации о заказе. В параметрах принимает идентификатор заказа, полученный в результате bookOrder.
Метод должен вернуть такое же количество билетов сколько было передано при вызове bookOrder.
Метод должен работать на любом этапе жизни заказа т.е. после создания, подтверждения, отмены, возврата.
**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
0
0
0
0
0
0
СТРАХОВЩИК: ПАО "Росстрах"; 119991; г. Москва; ул. Большая Ордынка; д. 40; стр.
```
### confirmOrder
Подтверждение оплаты заказа. Данный метод должен вызываться только после того как заказ действительно был
оплачен покупателем. Метод не должен делать проверок корректности заказа. Все проверки должны делать в bookOrder
или updateTicket. Вызов этого метода означает, все данные заполнены правильно и деньги от покупателя получены.
В параметрах принимает идентификатор заказа, полученный в результате bookOrder и информацию об агенте который
совершил операцию
**URL: /sales/confirmOrder**
Запрос:
```xml
9828585
ИП Твои билеты
2225555777
```
Ответ:
Ответ аналогичен ответу на запрос [getOrder](#getorder)
### cancelTicket
Отмена билета. Техническая операция, выполняет полный возврат билета без удержаний.
Необходима при нештатных ситуациях например в случае сбоев ККМ или ошибки выбора рейса.
В параметрах принимает идентификатор билета и информацию об агенте который совершил операцию.
Можно выполнять после создания заказа и в течении 5-30 минут после подтверждения заказа.
**URL: /sales/cancelTicket**
Запрос:
```xml
12435434
ИП Твои билеты
2225555777
```
Ответ:
Ответ аналогичен ответу на запрос [getOrder](#getorder)
### returnTicket
Возврат билета. При возврате возможны удержания. В параметрах принимает идентификатор билета и информацию
об агенте который совершил операцию. Билет можно вернуть только после подтверждения confirmOrder.
**URL: /sales/returnTicket**
Запрос:
```xml
12435435
ИП Твои билеты
2225555777
```
Ответ:
Ответ аналогичен ответу на запрос [getOrder](#getorder)
### updateTicket
Изменение персональных данных пассажира в забронированном или проданном билете.
В параметрах принимает идентификатор билета, информацию о пассажире и информацию
об агенте который совершил операцию.
**URL: /sales/updateTicket**
Запрос:
```xml
12435438
goxUEpWCud
sKZXIloHFn
pCaEgXgfWO
jwcmdIrmcc
iFAElsnFHn
1
1986-01-01
RU
FEMALE
ИП Твои билеты
2225555777
```
Ответ:
```xml
```