Browse Source

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

master
Nikolay Ushmodin 4 years ago
parent
commit
a5430188ee
  1. 330
      README.md

330
README.md

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