Vous ne pouvez pas sélectionner plus de 25 sujets Les noms de sujets doivent commencer par une lettre ou un nombre, peuvent contenir des tirets ('-') et peuvent comporter jusqu'à 35 caractères.

597 lignes
26 KiB
Markdown

il y a 7 ans
Спецификация протокола взаимной продажи билетов на транзиные рейсы
il y a 7 ans
===========================================================================
**Версия документа: 2.0**
il y a 7 ans
**Дата изменения: 24.09.2018**
il y a 7 ans
Изменения в версии 2.0
======================
* Уточнения в коментариях
* В ключ маршрута добавлен код перевозчика
* Метод редактирования билета
* Тип билета
il y a 7 ans
Введение
========
Данный документ содержит спецификацию протокола AVS5RS, предназначенного
для организации взаимной продажи билетов меджу автовокзалами на транзитные рейсы.
Для унификации в протоколе используются термины UID остановочного пункта и ключ маршрута.
UID остановочного пункта это ID станции одинаковый на всех вокзалах.
Ключ маршрута это структура состоящая из:
* UID начальной станции
* UID конечной станции
* время выхода из начальной станции
* индивидуальный номер перевозчика (ИНН,РНН)
il y a 7 ans
Описание протокола
==================
Общие сведения
--------------
Обмен данными в протоколе 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 version="1.0" encoding="UTF-8"?>`. Регистр
названий тегов и атрибутов должен совпадать с регистром из примеров.
XML-ответ в обязательном порядке имеет корневой тег, название которого
должно соответствовать формату "&lt;НазваниеМетодаResponse&gt;" (например EchoResponse, SearchTripsResponse)
Если ответ корректный, то данные ответа содержатся во вложенном теге &lt;Body&gt;.
Если ответ не корректный, информация об ошибке должна находиться во
вложенном теге &lt;Error&gt;, который состоит из кода ошибки в теге
&lt;code&gt; и описания ошибки в теге &lt;message&gt;. Код ошибок в приложении.
Описание - это произвольные текст на русском языке,
поясняющий причину ошибки. Некоторые методы допускают пустой ответ.
Пустой ответ содержит только корневой тег.
Пустой ответ:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<UpdateTicketResponse>
</UpdateTicketResponse>
```
Пример ответа в случае успешной обработки запроса:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<EchoResponse>
<Body>
<message>Test</message>
</Body>
</EchoResponse>
```
Пример ответа в случае обработки запроса с ошибкой:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<BookResponse>
<Error>
<code>ERROR</code>
<message>Место 5 занято</message>
</Error>
</BookResponse>
```
Методы протокола
----------------
### getFreeSeats
Получение списка свободных мест для рейса между указанными станциями. В параметре принимает ключ маршрута, дату и UIDы станции отправления и назначения пассажира.
В случае если рейс начинается в одних сутка а заканчивается в других, необходимо передавать дату в которой рейс находится в станции отправления пассажира.
il y a 7 ans
**URL: \[BASE\_URL\]/transit/getFreeSeats**
Запрос:
```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GetFreeSeatsRequest>
il y a 7 ans
<!-- ключ маршрута -->
il y a 7 ans
<RouteKey>
<!-- UID станции отправления рейса -->
<dispatchStationUid>523243243209840293840293849895781093</dispatchStationUid>
<!-- UID конечной станции -->
<arrivalStationUid>90929359890589203498093209904288</arrivalStationUid>
<!-- время отправления со станции отпраления. в часовом поясе станции отправления. -->
<dispatchTime>10:00:00</dispatchTime>
<!-- ИНН перевозчика -->
<carrierCode>141478737450</carrierCode>
il y a 7 ans
</RouteKey>
<!-- Дата отправления рейса со станции посадки поссажира -->
<date>2017-08-11</date>
<!-- UID станции посадки пассажира -->
<dispatchStationUid>hhwrl23kjhjj434kjljkshakjlk2j3l2</dispatchStationUid>
<!-- UID станции высадки пассажира -->
<arrivalStationUid>34l5klk435l435j34jjjk345jjk344CC</arrivalStationUid>
</GetFreeSeatsRequest>
```
Ответ:
```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GetFreeSeatsResponse>
<Body>
<TransitSeat>
<!-- ID места. Обязателен -->
<seatId>26</seatId>
<!-- Номер места места. Обязателен -->
<seatNum>26</seatNum>
</TransitSeat>
<TransitSeat>
<seatId>29</seatId>
<seatNum>29</seatNum>
</TransitSeat>
..............
<TransitSeat>
<seatId>47</seatId>
<seatNum>47</seatNum>
</TransitSeat>
</Body>
</GetFreeSeatsResponse>
```
### book
Бронирование заказа. Бронь должна сохраняться в течение ограниченного времени,
от 20 до 60 минут. Если в указанный период времени не поступает
il y a 7 ans
подтверждение оплаты через метод transit/confirm, то система реализующая протокол
il y a 7 ans
обязана отменить бронь. Допускается бронирование нескольких билетов в рамках одного
il y a 7 ans
заказа. В параметрах запроса передаются ключ маршрута, дата рейса
il y a 7 ans
идентификатор станции отправления, идентификатор станции назначения,
информацию об агенте совершивший эту операцию.
В случае если рейс начинается в одних сутка а заканчивается в других,
необходимо передавать дату в которой рейс находится в станции отправления пассажира.
il y a 7 ans
**URL: \[BASE\_URL\]/transit/bookOrder**
Запрос:
```xml
<?xml version="1.0"?>
<TransitBookRequest>
il y a 7 ans
<!-- ключ маршрута -->
il y a 7 ans
<RouteKey>
<!-- UID станции отправления рейса -->
<dispatchStationUid>523243243209840293840293849895781093</dispatchStationUid>
<!-- UID конечной станции -->
<arrivalStationUid>90929359890589203498093209904288</arrivalStationUid>
<!-- время отправления со станции отпраления. в часовом поясе станции отправления. -->
<dispatchTime>10:00:00</dispatchTime>
<!-- ИНН перевозчика -->
<carrierCode>141478737450</carrierCode>
il y a 7 ans
</RouteKey>
<!-- Дата отправления рейса со станции посадки поссажира -->
<date>2017-08-11</date>
<!-- UID станции посадки пассажира -->
<dispatchStationUid>hhwrl23kjhjj434kjljkshakjlk2j3l2</dispatchStationUid>
<!-- UID станции высадки пассажира -->
<arrivalStationUid>34l5klk435l435j34jjjk345jjk344CC</arrivalStationUid>
<Agent>
<!-- Имя агента. Не обязателен.-->
<name>ИП Твои билеты</name>
<!-- ИНН агента. Не обязателен.-->
<inn>2225555777</inn>
</Agent>
</TransitBookRequest>
```
Ответ:
```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TransitBookResponse>
<Body>
<TransitTicket>
<!-- ID билета на мастер сервере -->
<ticketId>25074373</ticketId>
<!-- Номер места -->
<seatNum>48</seatNum>
</TransitTicket>
</Body>
</TransitBookResponse>
```
### confirm
**URL: \[BASE\_URL\]/transit/confirm**
Подтверждение оплаты заказа. Переводит временную бронь созданную после операции book в постоянную.
Запрос:
```xml
<?xml version="1.0"?>
<TransitConfirmRequest>
il y a 7 ans
<!-- ключ маршрута -->
il y a 7 ans
<RouteKey>
<!-- UID станции отправления рейса -->
<dispatchStationUid>523243243209840293840293849895781093</dispatchStationUid>
<!-- UID конечной станции -->
<arrivalStationUid>90929359890589203498093209904288</arrivalStationUid>
<!-- время отправления со станции отпраления. в часовом поясе станции отправления. -->
<dispatchTime>10:00:00</dispatchTime>
<!-- ИНН перевозчика -->
<carrierCode>141478737450</carrierCode>
il y a 7 ans
</RouteKey>
<Ticket>
<!-- ID билета. Обязательно -->
<ticketId>21326881</ticketId>
<Passenger>
<!-- Имя пассажира. Необязательно -->
<firstName>Ivan</firstName>
<!-- Фамилия пассажира. Необязательно -->
<lastName>Ivanov</lastName>
<!-- Отчество пассажира. Необязательно -->
<middleName>Ivanovich</middleName>
<!-- ID типа документа. Из справочника МИНТРАС. Необязательно -->
<docTypeId>0</docTypeId>
<!-- Номер документа. Необязательно -->
<docNum>0101</docNum>
<!-- Серия документа. Необязательно -->
<docSeries>010101</docSeries>
<!-- Дата рождения. Необязательно -->
<birthday>2000-01-01</birthday>
<!-- Пол. MALE FEMALE. Необязательно -->
<gender>MALE</gender>
</Passenger>
<!-- Серия билета. Необязательно -->
<ticketSeries>1232344</ticketSeries>
<!-- Номер билета. Необязательно -->
<ticketNumber>3432423423</ticketNumber>
<!-- Итоговая цена по которой продан билет. Необязательно -->
<price>1000</price>
<!-- Отношения между продовцом и поставщиком контента. OWN AGENT ATP. Необязательно -->
<relation>AGENT</relation>
</Ticket>
<Agent>
<!-- Имя агента. Не обязателен.-->
<name>ИП Твои билеты</name>
<!-- ИНН агента. Не обязателен.-->
<inn>2225555777</inn>
</Agent>
</TransitConfirmRequest>
```
Ответ:
```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TransitConfirmResponse/>
```
### cancel
Отмена ранее забронированного места. Отмена билета допускается после оперций book и confirm.
**URL: \[BASE\_URL\]/transit/cancel**
Запрос:
```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TransitCancelRequest>
il y a 7 ans
<!-- ключ маршрута -->
il y a 7 ans
<RouteKey>
<!-- UID станции отправления рейса -->
<dispatchStationUid>523243243209840293840293849895781093</dispatchStationUid>
<!-- UID конечной станции -->
<arrivalStationUid>90929359890589203498093209904288</arrivalStationUid>
<!-- время отправления со станции отпраления. в часовом поясе станции отправления. -->
<dispatchTime>10:00:00</dispatchTime>
<!-- ИНН перевозчика -->
<carrierCode>141478737450</carrierCode>
il y a 7 ans
</RouteKey>
<!-- ID билета. Обязательно -->
<ticketId>4561143</ticketId>
il y a 7 ans
<Agent>
<!-- Имя агента. Не обязателен.-->
<name>ИП Твои билеты</name>
<!-- ИНН агента. Не обязателен.-->
<inn>2225555777</inn>
</Agent>
il y a 7 ans
</TransitCancelRequest>
```
Ответ:
```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TransitCancelResponse/>
```
### getTripInfo
il y a 7 ans
Возвращет информацию билетах на указанном рейсе.
В выборку должны попасть билеты по следующему алгоритму.
```
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.
il y a 7 ans
**URL: \[BASE\_URL\]/transit/getTripInfo**
Запрос:
```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TransitTripInfoRequest>
il y a 7 ans
<!-- ключ маршрута -->
il y a 7 ans
<RouteKey>
<!-- UID станции отправления рейса -->
<dispatchStationUid>523243243209840293840293849895781093</dispatchStationUid>
<!-- UID конечной станции -->
<arrivalStationUid>90929359890589203498093209904288</arrivalStationUid>
<!-- время отправления со станции отпраления. в часовом поясе станции отправления. -->
<dispatchTime>10:00:00</dispatchTime>
<!-- ИНН перевозчика -->
<carrierCode>141478737450</carrierCode>
il y a 7 ans
</RouteKey>
<!-- Дата отправления рейса со станции посадки поссажира -->
<date>2017-08-11</date>
<!-- UID станции посадки пассажира. Не обязательный. Если не указан, то равен станции отправления рейса -->
<dispatchStationUid>523243243209840293840293849895781093</dispatchStationUid>
<!-- UID станции высадки пассажира. Не обязательный. Если не указан, то равен конечной станции рейса -->
<arrivalStationUid>90929359890589203498093209904288</arrivalStationUid>
</TransitTripInfoRequest>
```
Ответ:
```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TransitTripInfoResponse>
<Body>
<Ticket>
<!-- UID станции посадки пассажира. -->
<dispatchStationUid>E19A767A4C4C43F3855E10DA31CD3749</dispatchStationUid>
<!-- UID станции высадки пассажира. -->
<arrivalStationUid>AE751908D644441298AEBD4001871311</arrivalStationUid>
<!-- ID билета. -->
<ticketId>4562182</ticketId>
<!-- серия билета. -->
<ticketSeries>2202022202</ticketSeries>
<!-- номер билета. -->
<ticketNumber>2457677</ticketNumber>
<!-- место билета. -->
<seatNum>3</seatNum>
<!-- цена билета. -->
<price>470</price>
</Ticket>
<Ticket>
<dispatchStationUid>AE751908D644441298AEBD4001871311</dispatchStationUid>
<arrivalStationUid>25CBF1CE4E224C0A85C4CCEAD3E4C537</arrivalStationUid>
<ticketId>4562669</ticketId>
<seatNum>3</seatNum>
</Ticket>
<Ticket>
<dispatchStationUid>E19A767A4C4C43F3855E10DA31CD3749</dispatchStationUid>
<arrivalStationUid>88184B22DA28440590D6202D2014E5F3</arrivalStationUid>
<Passenger>
<!-- Имя пассажира. Необязательно -->
<firstName>Ivan</firstName>
<!-- Фамилия пассажира. Необязательно -->
<lastName>Ivanov</lastName>
<!-- Отчество пассажира. Необязательно -->
<middleName>Ivanovich</middleName>
<!-- ID типа документа. Из справочника МИНТРАС. Необязательно -->
<docTypeId>0</docTypeId>
<!-- Номер документа. Необязательно -->
<docNum>0101</docNum>
<!-- Серия документа. Необязательно -->
<docSeries>010101</docSeries>
<!-- Дата рождения. Необязательно -->
<birthday>2000-01-01</birthday>
<!-- Пол. MALE FEMALE. Необязательно -->
<gender>MALE</gender>
</Passenger>
<ticketId>4553771</ticketId>
<ticketSeries>2202982202</ticketSeries>
<ticketNumber>41159</ticketNumber>
<seatNum>4</seatNum>
<price>167</price>
</Ticket>
<!-- Вместимость автобуса -->
<maxSeats>43</maxSeats>
<!-- Количество свободных мест между указанными станциями -->
<freeSeats>22</freeSeats>
<Carrier>
<!-- Имя перевозчика -->
<name>ПАП города N</name>
<!-- ИНН перевозчика -->
<inn>4534995945</inn>
</Carrier>
</Body>
</TransitTripInfoResponse>
```
### getRouteInfo
il y a 7 ans
Возвращает информацию по маршруту. Информация содержит название и описание остановочных пунктов маршрута.
il y a 7 ans
**URL: \[BASE\_URL\]/transit/getRouteInfo**
Запрос:
```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TransitRouteInfoRequest>
il y a 7 ans
<!-- ключ маршрута -->
il y a 7 ans
<RouteKey>
<!-- UID станции отправления рейса -->
<dispatchStationUid>523243243209840293840293849895781093</dispatchStationUid>
<!-- UID конечной станции -->
<arrivalStationUid>90929359890589203498093209904288</arrivalStationUid>
<!-- время отправления со станции отпраления. в часовом поясе станции отправления. -->
<dispatchTime>10:00:00</dispatchTime>
<!-- ИНН перевозчика -->
<carrierCode>141478737450</carrierCode>
il y a 7 ans
</RouteKey>
</TransitRouteInfoRequest>
```
Ответ:
```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TransitRouteInfoResponse>
<Body>
<!-- Название маршрута. Обязательно -->
<name>Белокуриха - Рубцовск</name>
<RouteItem>
<!-- порядок остановочного пункта. Обязательно -->
<order>1</order>
<!-- Название остановочного пункта. Обязательно -->
<stationName>Белокуриха</stationName>
<!-- UID остановочного пункта. Обязательно -->
<stationUid>E19A767A4C4C43F3855E10DA31CD3749</stationUid>
<!-- Расстояние. Необязательно -->
<distance>0</distance>
</RouteItem>
<RouteItem>
<order>2</order>
<stationName>Быканов Мост</stationName>
<stationUid>0ae247cb-b7b3-41df-8814-04065f7867fc</stationUid>
<distance>10</distance>
</RouteItem>
.........
<RouteItem>
<order>17</order>
<stationName>Рубцовск</stationName>
<stationUid>25CBF1CE4E224C0A85C4CCEAD3E4C537</stationUid>
<distance>559</distance>
</RouteItem>
</Body>
</TransitRouteInfoResponse>
il y a 7 ans
```
### setStationInfo
Устанавливает UID для конкретной станции. ID станции может быть получен ранее использую протокол продажи AVS5RS
**URL: \[BASE\_URL\]/transit/setStationInfo**
Запрос:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<SetStationInfoRequest>
<stationId>423423</stationId>
<uid>25CBF1CE4E224C0A85C4CCEAD3E4C537</uid>
</SetStationInfoRequest>
```
Ответ:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<SetStationInfoResponse/>
```
### TransitUpdateTicket
Редактирование атрибутов билета. Пока реализовано только редактирование флага явки.
**URL: \[BASE\_URL\]/transit/updateTickets**
Запрос:
```xml
<TransitUpdateTicketRequest>
<!-- ключ маршрута -->
<RouteKey>
<!-- UID станции отправления рейса -->
<dispatchStationUid>523243243209840293840293849895781093</dispatchStationUid>
<!-- UID конечной станции -->
<arrivalStationUid>90929359890589203498093209904288</arrivalStationUid>
<!-- время отправления со станции отпраления. в часовом поясе станции отправления. -->
<dispatchTime>10:00:00</dispatchTime>
<!-- ИНН перевозчика -->
<carrierCode>141478737450</carrierCode>
</RouteKey>
<Ticket>
<ticketId>5543543</ticketId>
<isGone>true</isGone>
</Ticket>
<Ticket>
<ticketId>545354</ticketId>
<isGone>false</isGone>
</Ticket>
</TransitUpdateTicketRequest>
```
Ответ:
```xml
<TransitUpdateTicketResponse>
</TransitUpdateTicketResponse>
il y a 7 ans
```