Version 2.0

master
Nikolay Ushmodin 7 years ago
parent cdf958dc42
commit c93e95cde3

@ -1,9 +1,9 @@
Спецификация на протокол AVS5RS продажи билетов для автотранспорта Спецификация на протокол AVS5RS продажи билетов для автотранспорта
================================================================== ==================================================================
**Версия документа: 1.4** **Версия документа: 2.0**
**Дата изменения: 26.12.2016** **Дата изменения: 22.02.2017**
Введение Введение
======== ========
@ -20,65 +20,142 @@
-------------- --------------
Обмен данными в протоколе AVS5RS производится через протокол HTTP. Обмен данными в протоколе AVS5RS производится через протокол HTTP.
Передача и прием данных производится в формате XML, с использованием Передача и прием данных производится в формате XML или JSON, с использованием
кодировки UTF-8. кодировки UTF-8.
Все запросы оправляются методом POST. Каждый метод протокола реализуется Все запросы оправляются методом POST. Каждый метод протокола реализуется
через отдельный URL, который строится относительно базового адреса через отдельный URL, который строится относительно базового адреса
сервиса, далее обозначаемого как \[BASE\_URL\]. сервиса, далее обозначаемого как \[BASE\_URL\].
Ответы с сервера должны поступать по протоколу HTTP c кодом 200 и
HTTP-заголовком “Content-Type”, имеющим значение “application/xml; charset=UTF-8”.
Доступ к веб-сервису, реализующему протокол AVS5RS, должен быть закрыт с Доступ к веб-сервису, реализующему протокол AVS5RS, должен быть закрыт с
применением Basic-аутентификации. Допускается использование протокола применением Basic-аутентификации. Допускается использование протокола
HTTPS, контроля доступа по IP, передача данных через VPN-соединение. HTTPS, контроля доступа по IP, передача данных через VPN-соединение.
Форматы данных Отличия от версии 1
-------------- -------------------
* Удален атрибут success. Анализ ошибки проиводится по наличию тега Error
* Изменено именования корневых тегов ответа.
* Отмена или ворзрат нескольких билетов одновременно.
* Поддержка формата JSON
* Введены коды ошибок
* Поля
* Passenger
* Добавлено info
* Добавлено phone
* Ticket
* Дабавлено repayment
* Удалено chargeFare
* Удалено chargeOthers
* Удалено repaymentFare
* Удалено repaymentOthers
* Мелкие уточнения
Общие форматы данных:
---------------------
Формат даты: `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- ответа должно начинаться с объявления
`<?xml version="1.0" encoding="UTF-8"?>`. Регистр `<?xml version="1.0" encoding="UTF-8"?>`. Регистр
названий тегов и атрибутов должен совпадать с регистром из примеров. названий тегов и атрибутов должен совпадать с регистром из примеров.
XML-ответ сервиса, реализующего протокол в обязательном порядке имеет XML-ответ в обязательном порядке имеет корневой тег, название которого
корневой тег `<Response>` с атрибутом success, который указывает на должно соответствовать формату "&lt;НазваниеМетодаResponse&gt;" (например EchoResponse, SearchTripsResponse)
результат выполнения запроса: true - корректно, false - нет. Если ответ Если ответ корректный, то данные ответа содержатся во вложенном теге &lt;Body&gt;.
корректный, то данные ответа содержатся во вложенном теге &lt;Body&gt;.
Если ответ не корректный, информация об ошибке должна находиться во Если ответ не корректный, информация об ошибке должна находиться во
вложенном теге &lt;Error&gt;, который состоит из кода ошибки в теге вложенном теге &lt;Error&gt;, который состоит из кода ошибки в теге
&lt;code&gt; и описания ошибки в теге &lt;message&gt;. Коды ошибок не &lt;code&gt; и описания ошибки в теге &lt;message&gt;. Код ошибок в приложении.
регламентируются. Описание - это произвольные текст на русском языке, Описание - это произвольные текст на русском языке,
поясняющий причину ошибки. поясняющий причину ошибки. Некоторые методы допускают пустой ответ.
Пустой ответ содержит только корневой тег.
Формат даты: `yyyy-MM-dd`, формат даты и времени: Пустой ответ:
`yyyy-MM-dd'T'HH:mm:ss`. Пример:
2016-09-07T13:10:00 (символ T латинский, обязательный) (секунды ```xml
обязательны). Время указано в часовом поясе сервера который <?xml version="1.0" encoding="UTF-8"?>
предоставляет контент. Все идентификаторы сущностей (id) это строки, <UpdateTicketResponse>
произвольного формата, длинной до 36 символов. </UpdateTicketResponse>
```
Пример ответа в случае успешной обработки запроса: Пример ответа в случае успешной обработки запроса:
```xml ```xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <EchoResponse>
<Body> <Body>
<message>Test</message> <message>Test</message>
</Body> </Body>
</Response> </EchoResponse>
``` ```
Пример ответа в случае обработки запроса с ошибкой: Пример ответа в случае обработки запроса с ошибкой:
```xml ```xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="false"> <BookResponse>
<Error> <Error>
<code>ERROR</code> <code>ERROR</code>
<message>Место 5 занято</message> <message>Место 5 занято</message>
</Error> </Error>
</Response> </BookResponse>
```
Форматы данных JSON
-------------------
Ответы с сервера должны поступать по протоколу HTTP c кодом 200 и
HTTP-заголовком “Content-Type”, имеющим значение “application/json; charset=UTF-8”.
JSON ответ может быть только JSON-объектом. В теле которого допустимо наличие только одного
элемента. В случае успешной обработки запроса ответ должен находиться в елементе __body__.
Если ответ пустой корневой объект должен присутствовать.
В случае если в ответ присутвует элемент __error__ то считается что во время обработки возникла ошибка.
Елемент __error__ состоит из строковых полей __code__ и __message__. Назначени полей аналогично формату XML
Пустой ответ:
```json
{}
```
Пример ответа в случае успешной обработки запроса:
```json
{
"body": {
"message": "Test"
}
}
```
Пример ответа в случае обработки запроса с ошибкой:
```json
{
"error": {
"code": "ERROR",
"message": "Место 5 занято"
}
}
``` ```
Методы протокола Методы протокола
@ -103,18 +180,33 @@ XML-ответ сервиса, реализующего протокол в об
</EchoRequest> </EchoRequest>
``` ```
```json
{
"message": "Test"
}
```
Ответ: Ответ:
```xml ```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response success="true"> <EchoResponse>
<Body> <Body>
<!-- Сообщение переданное в запросе --> <!-- Сообщение переданное в запросе -->
<message>Test</message> <message>Test</message>
</Body> </Body>
</Response> </EchoResponse>
``` ```
```json
{
"body": {
"message": "Test"
}
}
```
### getDispatchStations ### getDispatchStations
Метод получения станций отправления. Продажа происходит от станции Метод получения станций отправления. Продажа происходит от станции
@ -132,11 +224,15 @@ XML-ответ сервиса, реализующего протокол в об
</GetDispatchStationsRequest> </GetDispatchStationsRequest>
``` ```
```json
{}
```
Ответ: Ответ:
```xml ```xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <GetDispatchStationsResponse>
<Body> <Body>
<!-- Станция --> <!-- Станция -->
<Station> <Station>
@ -162,15 +258,43 @@ XML-ответ сервиса, реализующего протокол в об
<okato>45000000000</okato> <okato>45000000000</okato>
</Station> </Station>
</Body> </Body>
</Response> </GetDispatchStationsResponse>
```
```json
{
"body": [
{
"id": "983",
"name": "ВДНХ АС",
"region": "Москва",
"okato": "45000000000"
},
{
"id": "853",
"name": "Варшавская АС",
"region": "Москва",
"okato": "45000000000"
},
{
"id": "6",
"name": "Красногвардейская АС",
"region": "Москва",
"okato": "45000000000"
}
]
}
``` ```
### getArrivalStations ### getArrivalStations
Метод получения станций назначения от станции отправления. В параметре Метод получения станций назначения от станции отправления. В параметре
принимает идентификатор станции отправления. Станциями назначения могут принимает идентификатор станции отправления. Станциями назначения могут
быть любые остановочные пункты до которых есть хотя бы один рейс. Если быть любые остановочные пункты до которых есть хотя бы один рейс. Если
станций назначения нет, метод должен вернуть пустой список. станций назначения нет, метод должен вернуть пустой список.
В случае отсутствия станций назначения для указанной станции отправления
возвращать пустой ответ.
**URL: \[BASE\_URL\]/sales/getArrivalStations** **URL: \[BASE\_URL\]/sales/getArrivalStations**
@ -184,44 +308,52 @@ XML-ответ сервиса, реализующего протокол в об
</GetArrivalStationsRequest> </GetArrivalStationsRequest>
``` ```
```json
{
"dispatchStationId": "983"
}
```
Ответ: Ответ:
```xml ```xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> {
<Body> "body": [
<Station> {
<id>1069</id> "id": "1069",
<name>Рыбинск</name> "name": "Рыбинск",
<region>Ярославская область</region> "region": "Ярославская область",
<okato>78415000000</okato> "okato": "78415000000"
</Station> },
<Station> {
<id>1018</id> "id": "1018",
<name>Сергиев Посад</name> "name": "Сергиев Посад",
<region>Московская область</region> "region": "Московская область",
<okato>46215501000</okato> "okato": "46215501000"
</Station> },
<Station> {
<id>1084</id> "id": "1084",
<name>Углич</name> "name": "Углич",
<region>Ярославская область</region> "region": "Ярославская область",
<okato>78420000000</okato> "okato": "78420000000"
</Station> },
<Station> {
<id>1078</id> "id": "1078",
<name>Утена</name> "name": "Утена",
<region>Литва</region> "region": "Литва"
</Station> }
</Body> ]
</Response> }
``` ```
### searchTrips ### searchTrips
Метод возвращает список рейсов от станции отправления до станции Метод возвращает список рейсов от станции отправления до станции
назначения на заданную дату. В параметрах передается идентификатор назначения на заданную дату. В параметрах передается идентификатор
станции отправления, идентификатор станции назначения и дата. станции отправления, идентификатор станции назначения и дата.
В случае отсутствия рейсов для указанных параметров возвращать пустой ответ.
Рейсы должны быть отсортированы по дате отправления.
**URL: \[BASE\_URL\]/sales/searchTrips** **URL: \[BASE\_URL\]/sales/searchTrips**
@ -243,7 +375,7 @@ XML-ответ сервиса, реализующего протокол в об
```xml ```xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <SearchTripsResponse>
<Body> <Body>
<!-- Рейс--> <!-- Рейс-->
<Trip> <Trip>
@ -326,7 +458,7 @@ XML-ответ сервиса, реализующего протокол в об
<freeSeatCount>49</freeSeatCount> <freeSeatCount>49</freeSeatCount>
</Trip> </Trip>
</Body> </Body>
</Response> </SearchTripsResponse>
``` ```
### getFreeSeats ### getFreeSeats
@ -355,7 +487,7 @@ XML-ответ сервиса, реализующего протокол в об
```xml ```xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <GetFreeSeatsResponse>
<Body> <Body>
<!-- Место--> <!-- Место-->
<Seat> <Seat>
@ -377,7 +509,7 @@ XML-ответ сервиса, реализующего протокол в об
<type>Сидячее</type> <type>Сидячее</type>
</Seat> </Seat>
</Body> </Body>
</Response> </GetFreeSeatsResponse>
``` ```
### getTicketTypes ### getTicketTypes
@ -406,7 +538,7 @@ XML-ответ сервиса, реализующего протокол в об
```xml ```xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <GetTicketTypesResponse>
<Body> <Body>
<TicketType> <TicketType>
<!-- Идентификатор типа билета. Обязателен. Может совпадать с названием. --> <!-- Идентификатор типа билета. Обязателен. Может совпадать с названием. -->
@ -435,7 +567,7 @@ XML-ответ сервиса, реализующего протокол в об
<ticketClass>BAGGAGE</ticketClass> <ticketClass>BAGGAGE</ticketClass>
</TicketType> </TicketType>
</Body> </Body>
</Response> </GetTicketTypesResponse>
``` ```
### getDocumentTypes ### getDocumentTypes
@ -471,7 +603,7 @@ XML-ответ сервиса, реализующего протокол в об
```xml ```xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <GetDocumentTypesResponse>
<Body> <Body>
<DocumentType> <DocumentType>
<!-- ID типа документа. Обязателен. --> <!-- ID типа документа. Обязателен. -->
@ -488,7 +620,7 @@ XML-ответ сервиса, реализующего протокол в об
<name>Свидетельство о рождении</name> <name>Свидетельство о рождении</name>
</DocumentType> </DocumentType>
/Body> /Body>
</Response> </GetDocumentTypesResponse>
``` ```
Таблица 1. Коды документов, удостоверяющих личность, при передаче в АЦБПДП Таблица 1. Коды документов, удостоверяющих личность, при передаче в АЦБПДП
@ -553,7 +685,7 @@ XML-ответ сервиса, реализующего протокол в об
```xml ```xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <GetTripStopsResponse>
<Body> <Body>
<Stop> <Stop>
<!-- ID остановки. Совпадает с ID станции. Обязателен. --> <!-- ID остановки. Совпадает с ID станции. Обязателен. -->
@ -594,7 +726,7 @@ XML-ответ сервиса, реализующего протокол в об
<price>1177</price> <price>1177</price>
</Stop> </Stop>
</Body> </Body>
</Response> </GetTripStopsResponse>
``` ```
### bookOrder ### bookOrder
@ -655,6 +787,8 @@ XML-ответ сервиса, реализующего протокол в об
FEMALE - Женский FEMALE - Женский
--> -->
<gender>MALE</gender> <gender>MALE</gender>
<!-- Телефон пассажира. Не обязателен. -->
<phone>999-888-77-66</phone>
<!-- <!--
Дополнительная произвольная информация. Не обязательно. Дополнительная произвольная информация. Не обязательно.
--> -->
@ -675,14 +809,14 @@ XML-ответ сервиса, реализующего протокол в об
```xml ```xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <BookOrderResponse>
<Body> <Body>
<!-- Идентификатор заказ. Обязателен. --> <!-- Идентификатор заказ. Обязателен. -->
<orderId>9828350</orderId> <orderId>9828350</orderId>
<!-- Время жизни заказа. В минутах. Не обязателен. По умолчанию значение 30 --> <!-- Время жизни заказа. В минутах. Не обязателен. По умолчанию значение 30 -->
<lifetime>30</lifetime> <lifetime>30</lifetime>
</Body> </Body>
</Response> </BookOrderResponse>
``` ```
### getOrder ### getOrder
@ -709,7 +843,7 @@ XML-ответ сервиса, реализующего протокол в об
```xml ```xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <GetOrderResponse>
<Body> <Body>
<!-- Идентификатор заказа. Обязателен. --> <!-- Идентификатор заказа. Обязателен. -->
<orderId>9828350</orderId> <orderId>9828350</orderId>
@ -776,25 +910,20 @@ RETURNED Выполнен возврат билета. Данный статус
<birthday>1985-01-01</birthday> <birthday>1985-01-01</birthday>
<citizenshipISO2>RU</citizenshipISO2> <citizenshipISO2>RU</citizenshipISO2>
<gender>MALE</gender> <gender>MALE</gender>
<phone>999-888-77-66</phone>
<info>FewwLks Mq</info> <info>FewwLks Mq</info>
</Passenger> </Passenger>
<!-- Тариф (руб). Обязателен после подтверждения. --> <!-- Тариф (руб). Обязателен после подтверждения. -->
<fare>0</fare> <fare>0</fare>
<!-- Cборы (руб). Обязателен после подтверждения. Если нет то 0. --> <!-- Cборы (руб). Обязателен после подтверждения. Если нет то 0. -->
<fees>0</fees> <fees>0</fees>
<!-- Удержано Тариф (руб). Обязателен в случает возврата или отмены. --> <!-- Удержано Остальные сборы (руб). Обязателен в случает возврата. -->
<chargeFare>0</chargeFare> <repayment>0</repaymentFare>
<!-- Удержано Остальные сборы (руб). Обязателен в случает возврата или отмены. -->
<chargeOthers>0</chargeOthers>
<!-- Возврат Тариф (руб). Обязателен в случает возврата или отмены. -->
<repaymentFare>0</repaymentFare>
<!-- Возврат Остальные сборы (руб). Обязателен в случает возврата или отмены. -->
<repaymentOthers>0</repaymentOthers>
<!-- Информация о страховании. Обязательно. Необходим при печати билета. --> <!-- Информация о страховании. Обязательно. Необходим при печати билета. -->
<insuranceInfo>СТРАХОВЩИК: ПАО &quot;Росстрах&quot;; 119991; г. Москва; ул. Большая Ордынка; д. 40; стр.</insuranceInfo> <insuranceInfo>СТРАХОВЩИК: ПАО &quot;Росстрах&quot;; 119991; г. Москва; ул. Большая Ордынка; д. 40; стр.</insuranceInfo>
</Ticket> </Ticket>
</Body> </Body>
</Response> </GetOrderResponse>
``` ```
### confirmOrder ### confirmOrder
@ -814,6 +943,7 @@ bookOrder или updateTicket. Вызов этого метода означае
```xml ```xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<ConfirmOrderRequest> <ConfirmOrderRequest>
<!-- ID заказа. Обязателен. -->
<orderId>9828585</orderId> <orderId>9828585</orderId>
<!-- Агент выполнивший операцию. Не Обязателен. --> <!-- Агент выполнивший операцию. Не Обязателен. -->
<Agent> <Agent>
@ -827,16 +957,19 @@ bookOrder или updateTicket. Вызов этого метода означае
Ответ: Ответ:
Ответ аналогичен ответу на запрос [getOrder](#getorder) Ответ аналогичен ответу на запрос [getOrder](#getorder) c именем корневого тега ConfirmOrderResponse
### cancelTicket ### cancelTicket
Отмена билета. Техническая операция, выполняет полный возврат билета без Отмена одного или нескольких билетов. Техническая операция, выполняет полный возврат билета без
удержаний. Необходима при нештатных ситуациях: в случае сбоев ККМ или удержаний. Необходима при нештатных ситуациях: в случае сбоев ККМ или
обнаружения ошибки выбора рейса, персональных данных. В параметрах обнаружения ошибки выбора рейса, персональных данных. В параметрах
принимает идентификатор билета и информацию об агенте который совершил принимает идентификаторы билета и информацию об агенте который совершил
операцию. Можно выполнять после создания заказа и в течении 5-30 минут операцию. Все билеты должны быть обработы в рамках одной транзакции.
после подтверждения заказа. т.е. если было передано 2 билета, первый был обработан а при обработке второго возникла ошибка
то обработка первого должна быть отменена.
Можно выполнять после создания заказа и в течении 5-30 минут
после подтверждения заказа.
**URL: \[BASE\_URL\]/sales/cancelTicket** **URL: \[BASE\_URL\]/sales/cancelTicket**
@ -845,7 +978,9 @@ bookOrder или updateTicket. Вызов этого метода означае
```xml ```xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<CancelTicketRequest> <CancelTicketRequest>
<ticketId>12435434</ticketId> <!-- ID билетов для возврата. произвольное количество тегов. -->
<ticketId>34</ticketId>
<ticketId>36</ticketId>
<!-- Агент выполнивший операцию. Не Обязателен. --> <!-- Агент выполнивший операцию. Не Обязателен. -->
<Agent> <Agent>
<!-- Имя агента. Не обязателен.--> <!-- Имя агента. Не обязателен.-->
@ -858,12 +993,15 @@ bookOrder или updateTicket. Вызов этого метода означае
Ответ: Ответ:
Ответ аналогичен ответу на запрос [getOrder](#getorder) Ответ аналогичен ответу на запрос [getOrder](#getorder) c именем корневого тега CancelTicketResponse
### returnTicket ### returnTicket
Возврат билета. При возврате возможны удержания. В параметрах принимает Возврат одного или нескольких билетов. При возврате возможны удержания. В параметрах принимает
идентификатор билета и информацию об агенте который совершил операцию. идентификатор билета и информацию об агенте который совершил операцию.
Все билеты должны быть обработы в рамках одной транзакции.
т.е. если было передано 2 билета, первый был обработан а при обработке второго возникла ошибка
то обработка первого должна быть отменена.
Билет можно вернуть только после подтверждения confirmOrder. Билет можно вернуть только после подтверждения confirmOrder.
**URL: \[BASE\_URL\]/sales/returnTicket** **URL: \[BASE\_URL\]/sales/returnTicket**
@ -873,7 +1011,9 @@ bookOrder или updateTicket. Вызов этого метода означае
```xml ```xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<ReturnTicketRequest> <ReturnTicketRequest>
<ticketId>12435435</ticketId> <!-- ID билетов для возврата. произвольное количество тегов. -->
<ticketId>35</ticketId>
<ticketId>36</ticketId>
<!-- Агент выполнивший операцию. Не Обязателен. --> <!-- Агент выполнивший операцию. Не Обязателен. -->
<Agent> <Agent>
<!-- Имя агента. Не обязателен.--> <!-- Имя агента. Не обязателен.-->
@ -886,7 +1026,7 @@ bookOrder или updateTicket. Вызов этого метода означае
Ответ: Ответ:
Ответ аналогичен ответу на запрос [getOrder](#getorder) Ответ аналогичен ответу на запрос [getOrder](#getorder) c именем корневого тега ReturnTicketResponse
### updateTicket ### updateTicket
@ -945,6 +1085,7 @@ bookOrder или updateTicket. Вызов этого метода означае
```xml ```xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <UpdateTicketResponse>
</Response> </UpdateTicketResponse>
``` ```

Loading…
Cancel
Save