Документация

master
Nikolay Ushmodin 7 years ago
parent 871480afe4
commit a5430188ee

@ -1,45 +1,78 @@
# Введение Спецификация на протокол AVS5RS продажи билетов для автотранспорта
==================================================================
**Версия документа: 1.2** **Версия документа: 1.3**
**Дата изменения: 16.09.2016** **Дата изменения: 17.11.2016**
Для возможности продажи с использованием протокола AVS5RS необходимо реализовать сервис с использованием протокола HTTP. Все запросы оправляются методом POST. Введение
Методы включают в себя справочные методы и методы продажи. Продажа состоит из двух этапов резервирование и подтверждение продажи. ========
Протокол должен быть защищен авторизацией через логин и пароль. Так же необходимо чтобы трафик передавался по защищенному каналу связи с использованием SSL или VPN.
## Методы сервиса Данный документ содержит спецификацию протокола AVS5RS, предназначенного
для организации удаленной продажи билетов на автотранспорте.
Спецификация предназначена для унификации процесса обмена данными между
перевозчиками, автовокзалами и агентами по продаже билетов.
Все запросы должны передаваться по протоколу HTTP методом пост. В теле POST запроса и ответа передается XML фиксированного формата. Описание протокола
Каждый метод имеет отдельный URL. Через HTTP заголовок Content-Type передается значение `application/xml; charset=UTF-8`. ==================
Этот заголовок указывает на тип содержимого запроса и его кодировку. Необходимо использовать только кодировку UTF-8.
### Формат ответа Общие сведения
--------------
Корневой тег XML ответа Response. У него есть обязательный атрибут success, который указывает корректно выполнился запрос или нет, значения true - корректно, false - нет. Обмен данными в протоколе AVS5RS производится через протокол HTTP.
Если ответ корректный, то данные ответа содержатся во вложенном теге Body. Если ответ не корректный, тег Body будет проигнорирован, а информация об ошибке должна Передача и прием данных производится в формате XML, с использованием
находиться во вложенном теге Error. Который состоит из кода ошибки и описания. Коды ошибок не регламентируются. Описание это произвольные тест, поясняющий причину ошибки. кодировки UTF-8.
Регистр названий тегов и атрибутов должен совпадать с регистром из примеров.
Все ответы должны приходить с HTTP кодом 200. Все XML ответы должны начинаться с объявления `<?xml version="1.0" encoding="UTF-8"?>` в котором указана кодировка содержимого.
Формат даты `yyyy-MM-dd`, формат даты и времени `yyyy-MM-dd'T'HH:mm:ss`, пример 2016-09-07T13:10:00 (символ T латинский, обязательный) (секунды обязательны).
Время указано в часовом поясе сервера который предоставляет контент.
Все идентификаторы сущностей (id) это строки, произвольного формата, длинной до 36 символов.
Корректный ответ: Все запросы оправляются методом POST. Каждый метод протокола реализуется
через отдельный URL, который строится относительно базового адреса
сервиса, далее обозначаемого как \[BASE\_URL\].
Ответы с сервера должны поступать по протоколу HTTP c кодом 200 и
HTTP-заголовком “Content-Type”, имеющим значение “application/xml; charset=UTF-8”.
Доступ к веб-сервису, реализующему протокол AVS5RS, должен быть закрыт с
применением Basic-аутентификации. Допускается использование протокола
HTTPS, контроля доступа по IP, передача данных через VPN-соединение.
Форматы данных
--------------
Тело XML- ответа должно начинаться с объявления
`<?xml version="1.0" encoding="UTF-8"?>`. Регистр
названий тегов и атрибутов должен совпадать с регистром из примеров.
XML-ответ сервиса, реализующего протокол в обязательном порядке имеет
корневой тег `<Response>` с атрибутом success, который указывает на
результат выполнения запроса: true - корректно, false - нет. Если ответ
корректный, то данные ответа содержатся во вложенном теге &lt;Body&gt;.
Если ответ не корректный, информация об ошибке должна находиться во
вложенном теге &lt;Error&gt;, который состоит из кода ошибки в теге
&lt;code&gt; и описания ошибки в теге &lt;message&gt;. Коды ошибок не
регламентируются. Описание - это произвольные текст на русском языке,
поясняющий причину ошибки.
Формат даты: `yyyy-MM-dd`, формат даты и времени:
`yyyy-MM-dd'T'HH:mm:ss`. Пример:
2016-09-07T13:10:00 (символ T латинский, обязательный) (секунды
обязательны). Время указано в часовом поясе сервера который
предоставляет контент. Все идентификаторы сущностей (id) это строки,
произвольного формата, длинной до 36 символов.
Пример ответа в случае успешной обработки запроса:
```xml ```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <Response success="true">
<Body> <Body>
<message>Test</message> <message>Test</message>
</Body> </Body>
</Response> </Response>
``` ```
Не корректный ответ: Пример ответа в случае обработки запроса с ошибкой:
```xml ```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="false"> <Response success="false">
<Error> <Error>
<code>ERROR</code> <code>ERROR</code>
@ -48,11 +81,17 @@
</Response> </Response>
``` ```
Методы протокола
----------------
### echo ### echo
Метод принимает в параметра произвольную строку и возвращает её в теле ответа. Не выполняет ни какой логики. Необходим для проверки доступен ли сервис. Используется для проверки доступности сервиса.
**URL: /sales/echo** Метод принимает в параметре произвольную строку и возвращает её в теле
ответа.
**URL: \[BASE\_URL\]/sales/echo**
Запрос: Запрос:
@ -78,11 +117,12 @@
### getDispatchStations ### getDispatchStations
Метод получения станций отправления. Метод получения станций отправления. Продажа происходит от станции
Продажа происходит от станции отправления до станции назначения, поэтому метод должен вернуть хотя бы один элемент. отправления до станции назначения, поэтому метод должен вернуть хотя бы
Обычно станциями отправления являются автовокзалы или автоматизированные остановочные пункты с функцией продажи билетов. один элемент. Обычно станциями отправления являются автовокзалы или
автоматизированные остановочные пункты с функцией продажи билетов.
**URL: /sales/getDispatchStations** **URL: \[BASE\_URL\]/sales/getDispatchStations**
Запрос: Запрос:
@ -95,7 +135,7 @@
Ответ: Ответ:
```xml ```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <Response success="true">
<Body> <Body>
<!-- Станция --> <!-- Станция -->
@ -127,11 +167,12 @@
### getArrivalStations ### getArrivalStations
Метод получения станций назначения от станции отправления. В параметра принимает идентификатор станции отправления. Метод получения станций назначения от станции отправления. В параметре
Станциями назначения могут быть любые остановочные пункты до которых есть хотя бы один рейс. принимает идентификатор станции отправления. Станциями назначения могут
Если станций назначения нет вернуть пустой список. быть любые остановочные пункты до которых есть хотя бы один рейс. Если
станций назначения нет, метод должен вернуть пустой список.
**URL: /sales/getArrivalStations** **URL: \[BASE\_URL\]/sales/getArrivalStations**
Запрос: Запрос:
@ -146,7 +187,7 @@
Ответ: Ответ:
```xml ```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <Response success="true">
<Body> <Body>
<Station> <Station>
@ -178,10 +219,11 @@
### searchTrips ### searchTrips
Метод возвращает список рейсов от станции отправления до станции назначения на заданную дату. Метод возвращает список рейсов от станции отправления до станции
В параметрах передается идентификатор станции отправления, идентификатор станции назначения и дата. назначения на заданную дату. В параметрах передается идентификатор
станции отправления, идентификатор станции назначения и дата.
**URL: /sales/searchTrips** **URL: \[BASE\_URL\]/sales/searchTrips**
Запрос: Запрос:
@ -200,7 +242,7 @@
Ответ: Ответ:
```xml ```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <Response success="true">
<Body> <Body>
<!-- Рейс--> <!-- Рейс-->
@ -233,11 +275,10 @@
<busInfo>49 Мест Категория ТС &quot;М3&quot; </busInfo> <busInfo>49 Мест Категория ТС &quot;М3&quot; </busInfo>
<!-- <!--
Флаг обязательности ввода дополнительных персональных данных покупателя. Флаг обязательности ввода дополнительных персональных данных покупателя.
Основые персональные данные: Имя, Фамилия, Тип документа, Номер документа. Основные персональные данные: Имя, Фамилия, Тип и Серия/Номер документа, удостоверяющего личность.
Дополнительные персональные данные: Отчество, Пол, Дата рождения, Гражданство. Дополнительные персональные данные: Отчество, Пол, Дата рождения, Гражданство.
Ввод дополнительных данных требуется во исполнение статьи 11 закона "О транспортной безопасности" Ввод дополнительных данных требуется во исполнение статьи 11 закона "О транспортной безопасности" (с изменениями на 3 февраля 2014 года).
(с изменениями на 3 февраля 2014 года).
<p>
См. http://docs.cntd.ru/document/902027326 См. http://docs.cntd.ru/document/902027326
Обязателен. Если система не поддерживает, возвращать всегда true. Обязателен. Если система не поддерживает, возвращать всегда true.
@ -255,10 +296,12 @@
--> -->
<type>INTERREGIONAL</type> <type>INTERREGIONAL</type>
<!-- <!--
статус рейса. Обязателен. Статус рейса. Обязателен.
ON_SALE - В продаже. На рейса доступны все опрерации., ON_SALE - В продаже. Можно продавать билеты на этот рейс,
SUSPENDED - Приостановка остановка продажи. Рейс не доступен для продажи. SUSPENDED - Приостановка продажи. Продажа запрещена.
CANCELED - Рейс отменен. Рейс не доступен для продажи. CANCELED - Рейс отменен. Продажа запрещена.
DISPATCHED - Рейс отправлен. Продажа запрещена.
UNKNOWN - Неопределенный статус. Рейс не доступен для продажи. UNKNOWN - Неопределенный статус. Рейс не доступен для продажи.
--> -->
<status>ON_SALE</status> <status>ON_SALE</status>
@ -293,10 +336,11 @@
### getFreeSeats ### getFreeSeats
Получение списка свободных мест для рейса. Получение списка свободных мест для рейса. В параметре принимает
В параметра принимает идентификатор рейса, идентификтор станции отправления и идентификатор станции назначения. идентификатор рейса, идентификатор станции отправления и идентификатор
станции назначения.
**URL: /sales/getFreeSeats** **URL: \[BASE\_URL\]/sales/getFreeSeats**
Запрос: Запрос:
@ -315,7 +359,7 @@
Ответ: Ответ:
```xml ```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <Response success="true">
<Body> <Body>
<!-- Место--> <!-- Место-->
@ -343,10 +387,11 @@
### getTicketTypes ### getTicketTypes
Получение списка типов билетов, доступных для продажи. Получение списка типов билетов, доступных для продажи. В параметре
В параметра принимает идентификатор рейса, идентификатор станции отправления и идентификатор станции назначения. принимает идентификатор рейса, идентификатор станции отправления и
идентификатор станции назначения.
**URL: /sales/getTicketTypes** **URL: \[BASE\_URL\]/sales/getTicketTypes**
Запрос: Запрос:
@ -359,13 +404,13 @@
<dispatchStationId>983</dispatchStationId> <dispatchStationId>983</dispatchStationId>
<!-- Идентификатор станции назначения. Обязательный. --> <!-- Идентификатор станции назначения. Обязательный. -->
<arrivalStationId>1080</arrivalStationId> <arrivalStationId>1080</arrivalStationId>
/GetTicketTypesRequest> </GetTicketTypesRequest>
``` ```
Ответ: Ответ:
```xml ```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <Response success="true">
<Body> <Body>
<TicketType> <TicketType>
@ -400,11 +445,18 @@
### getDocumentTypes ### getDocumentTypes
Получение списка типов документов, допустимых при оформлении билетов. Система должна предоставить хотя бы один тип документа. Получение списка типов документов, допустимых для удостоверения личности
Рекомендуется использовать документы из (приказа)[http://base.garant.ru/70229008/] в Таблице 1. при оформлении билетов через интернет. Система должна предоставить хотя
В параметра принимает идентификатор рейса, идентификатор станции отправления и идентификатор станции назначения. бы один тип документа. Допустимые идентификаторы и названия документов
перечислены в таблице 1 Приказа Минтранса РФ от 19 июля 2012 г. N 243
"Об утверждении Порядка формирования и ведения автоматизированных
централизованных баз персональных данных о пассажирах и персонале
(экипаже) транспортных средств, а также предоставления содержащихся в
них данных".
Текст документа в системе ГАРАНТ: <http://base.garant.ru/70229008/>
**URL: /sales/getDocumentTypes** **URL: \[BASE\_URL\]/sales/getDocumentTypes**
Запрос: Запрос:
@ -423,46 +475,74 @@
Ответ: Ответ:
```xml ```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <Response success="true">
<Body> <Body>
<DocumentType> <DocumentType>
<!-- ID типа документа. Обязателен. Может совпадать с названием. --> <!-- ID типа документа. Обязателен. -->
<id>1</id> <id>0</id>
<!-- Название типа документа. Обязателен. --> <!-- Название типа документа. Обязателен. -->
<name>Паспорт РФ</name> <name>Паспорт РФ</name>
</DocumentType> </DocumentType>
<DocumentType> <DocumentType>
<id>52</id> <id>3</id>
<name>Паспорт иностранного гражданина</name> <name>Паспорт иностранного гражданина</name>
</DocumentType> </DocumentType>
<DocumentType> <DocumentType>
<id>40</id>
<name>Удостоверение (Казахстан)</name>
</DocumentType>
<DocumentType>
<id>2</id>
<name>Свидетельство о рождении</name>
</DocumentType>
<DocumentType>
<id>4</id> <id>4</id>
<name>Удостоверение личности военнослужащего</name> <name>Свидетельство о рождении</name>
</DocumentType>
<DocumentType>
<id>55</id>
<name>Временное удостоверение ОВД</name>
</DocumentType> </DocumentType>
</Body> /Body>
</Response> </Response>
``` ```
Таблица 1. Коды документов, удостоверяющих личность, при передаче в АЦБПДП
---------------------------------------------------------------
-------------------------------------------------------------------------
Код Наименование документа
--- -------------------------------------------------------------------
00 Паспорт гражданина Российской Федерации
01 Паспорт моряка
02 Общегражданский заграничный паспорт гражданина Российской Федерации
03 Паспорт иностранного гражданина
04 Свидетельство о рождении
05 Удостоверение личности военнослужащего
06 Удостоверение личности лица без гражданства
07 Временное удостоверение личности, выдаваемое органами внутренних дел
08 Военный билет военнослужащего срочной службы
09 Вид на жительство иностранного гражданина или лица без гражданства
10 Справка об освобождении из мест лишения свободы
11 Паспорт гражданина СССР
12 Паспорт дипломатический
13 Паспорт служебный (кроме паспорта моряка и дипломатического)
14 Свидетельство о возвращении из стран СНГ
15 Справка об утере паспорта
--------------------------------------------------------------------------
### getTripStops ### getTripStops
Метод возвращает список остановочных пунктов для рейса. Метод возвращает список остановочных пунктов для рейса. В параметре
В параметра принимает идентификатор рейса. принимает идентификатор рейса. Информация имеет справочный характер.
Метод информационный.
**URL: /sales/getTripStops** **URL: \[BASE\_URL\]/sales/getTripStops**
Запрос: Запрос:
@ -477,7 +557,7 @@
Ответ: Ответ:
```xml ```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <Response success="true">
<Body> <Body>
<Stop> <Stop>
@ -524,16 +604,20 @@
### bookOrder ### bookOrder
Бронирование заказа. Бронь сохраняется в течение ограниченного времени, от 20 до 60 минут. Если в указанный Бронирование заказа. Бронь сохраняется в течение ограниченного времени,
период времени не поступает подтверждение оплаты через метод confirmOrder(), то бронирование автоматически от 20 до 60 минут. Если в указанный период времени не поступает
отменяется. Метод должен выполнить все возможные проверки корректности переданных данных. В случае ошибки подтверждение оплаты через метод confirmOrder(), то бронирование
заказ не должен быть создан. Допускается бронирование нескольких билетов в рамках одного заказа. автоматически отменяется. Метод должен выполнить все возможные проверки
В параметра принимает идентификатор рейса, идентификатор станции отправления, идентификатор станции назначения, корректности переданных данных. В случае ошибки заказ не должен быть
информацию о бронируемых билетах, информацию об агенте совершивший эту операцию. Информации о бронируемых билетах создан. Допускается бронирование нескольких билетов в рамках одного
включает в себя идентификатор типа билета, идентификатор места и информацию о пассажире. Информация об заказа. В параметрах запроса передаются идентификатор рейса,
идентификатор станции отправления, идентификатор станции назначения,
информацию о бронируемых билетах, информацию об агенте совершивший эту
операцию. Информации о бронируемых билетах включает в себя идентификатор
типа билета, идентификатор места и информацию о пассажире. Информация об
агенте включает в себя наименование и ИНН агента. агенте включает в себя наименование и ИНН агента.
**URL: /sales/bookOrder** **URL: \[BASE\_URL\]/sales/bookOrder**
Запрос: Запрос:
@ -591,7 +675,7 @@
Ответ: Ответ:
```xml ```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <Response success="true">
<Body> <Body>
<!-- Идентификатор заказ. Обязателен. --> <!-- Идентификатор заказ. Обязателен. -->
@ -604,11 +688,13 @@
### getOrder ### getOrder
Получение информации о заказе. В параметрах принимает идентификатор заказа, полученный в результате bookOrder. Получение информации о заказе. В параметрах принимает идентификатор
Метод должен вернуть такое же количество билетов сколько было передано при вызове bookOrder. заказа, полученный в результате bookOrder. Метод должен вернуть такое же
Метод должен работать на любом этапе жизни заказа т.е. после создания, подтверждения, отмены, возврата. количество билетов сколько было передано при вызове bookOrder. Метод
должен работать на любом этапе жизни заказа т.е. после создания,
подтверждения, отмены, возврата.
**URL: /sales/getOrder** **URL: \[BASE\_URL\]/sales/getOrder**
Запрос: Запрос:
@ -623,10 +709,10 @@
Ответ: Ответ:
```xml ```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <?xml version="1.0" encoding="UTF-8"?>
<Response success="true"> <Response success="true">
<Body> <Body>
<!-- Идентификатор заказа. Обязателен. --> <!-- Идентификатор заказа. Обязателен. -->
<orderId>9828350</orderId> <orderId>9828350</orderId>
<!-- Информация о билетах. Отдельный тег для каждого билета --> <!-- Информация о билетах. Отдельный тег для каждого билета -->
<Ticket> <Ticket>
@ -713,13 +799,15 @@ RETURNED Выполнен возврат билета. Данный статус
### confirmOrder ### confirmOrder
Подтверждение оплаты заказа. Данный метод должен вызываться только после того как заказ действительно был Подтверждение оплаты заказа. Данный метод должен вызываться только после
оплачен покупателем. Метод не должен делать проверок корректности заказа. Все проверки должны делать в bookOrder того как заказ действительно был оплачен покупателем. Метод не должен
или updateTicket. Вызов этого метода означает, все данные заполнены правильно и деньги от покупателя получены. делать проверок корректности заказа, все проверки должны выполняться в
В параметрах принимает идентификатор заказа, полученный в результате bookOrder и информацию об агенте который bookOrder или updateTicket. Вызов этого метода означает подтверждение
совершил операцию правильного приема данных и получение денег от покупателя. В параметрах
принимает идентификатор заказа, полученный в результате bookOrder и
информацию об агенте который совершил операцию
**URL: /sales/confirmOrder** **URL: \[BASE\_URL\]/sales/confirmOrder**
Запрос: Запрос:
@ -741,15 +829,16 @@ RETURNED Выполнен возврат билета. Данный статус
Ответ аналогичен ответу на запрос [getOrder](#getorder) Ответ аналогичен ответу на запрос [getOrder](#getorder)
### cancelTicket ### cancelTicket
Отмена билета. Техническая операция, выполняет полный возврат билета без удержаний. Отмена билета. Техническая операция, выполняет полный возврат билета без
Необходима при нештатных ситуациях например в случае сбоев ККМ или ошибки выбора рейса. удержаний. Необходима при нештатных ситуациях: в случае сбоев ККМ или
В параметрах принимает идентификатор билета и информацию об агенте который совершил операцию. обнаружения ошибки выбора рейса, персональных данных. В параметрах
Можно выполнять после создания заказа и в течении 5-30 минут после подтверждения заказа. принимает идентификатор билета и информацию об агенте который совершил
операцию. Можно выполнять после создания заказа и в течении 5-30 минут
после подтверждения заказа.
**URL: /sales/cancelTicket** **URL: \[BASE\_URL\]/sales/cancelTicket**
Запрос: Запрос:
@ -773,10 +862,11 @@ RETURNED Выполнен возврат билета. Данный статус
### returnTicket ### returnTicket
Возврат билета. При возврате возможны удержания. В параметрах принимает идентификатор билета и информацию Возврат билета. При возврате возможны удержания. В параметрах принимает
об агенте который совершил операцию. Билет можно вернуть только после подтверждения confirmOrder. идентификатор билета и информацию об агенте который совершил операцию.
Билет можно вернуть только после подтверждения confirmOrder.
**URL: /sales/returnTicket** **URL: \[BASE\_URL\]/sales/returnTicket**
Запрос: Запрос:
@ -800,11 +890,11 @@ RETURNED Выполнен возврат билета. Данный статус
### updateTicket ### updateTicket
Изменение персональных данных пассажира в забронированном или проданном билете. Изменение персональных данных пассажира в забронированном или проданном
В параметрах принимает идентификатор билета, информацию о пассажире и информацию билете. В параметрах принимает идентификатор билета, информацию о
об агенте который совершил операцию. пассажире и информацию об агенте который совершил операцию.
**URL: /sales/updateTicket** **URL: \[BASE\_URL\]/sales/updateTicket**
Запрос: Запрос:
@ -854,5 +944,3 @@ RETURNED Выполнен возврат билета. Данный статус
<Response success="true"> <Response success="true">
</Response> </Response>
``` ```

Loading…
Cancel
Save