Version 2.0

4 years ago · c93e95cde3
--- a/README.md
+++ b/README.md
@@ -1,9 +1,9 @@
 Спецификация на протокол AVS5RS продажи билетов для автотранспорта
 ==================================================================

 **Версия документа: 1.4**
 **Версия документа: 2.0**

 **Дата изменения: 26.12.2016**
 **Дата изменения: 22.02.2017**

 Введение
 ========
@@ -20,65 +20,142 @@
 --------------

 Обмен данными в протоколе AVS5RS производится через протокол HTTP.
 Передача и прием данных производится в формате XML, с использованием
 Передача и прием данных производится в формате XML или JSON, с использованием
 кодировки UTF-8.

 Все запросы оправляются методом POST. Каждый метод протокола реализуется
 через отдельный URL, который строится относительно базового адреса
 сервиса, далее обозначаемого как \[BASE\_URL\].

 Ответы с сервера должны поступать по протоколу HTTP c кодом 200 и
 HTTP-заголовком “Content-Type”, имеющим значение “application/xml; charset=UTF-8”.

 Доступ к веб-сервису, реализующему протокол AVS5RS, должен быть закрыт с
 применением Basic-аутентификации. Допускается использование протокола
 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 version="1.0" encoding="UTF-8"?>`. Регистр
 названий тегов и атрибутов должен совпадать с регистром из примеров.

 XML-ответ сервиса, реализующего протокол в обязательном порядке имеет
 корневой тег `<Response>` с атрибутом success, который указывает на
 результат выполнения запроса: true - корректно, false - нет. Если ответ
 корректный, то данные ответа содержатся во вложенном теге &lt;Body&gt;.
 XML-ответ в обязательном порядке имеет корневой тег, название которого 
 должно соответствовать формату "&lt;НазваниеМетодаResponse&gt;" (например EchoResponse, SearchTripsResponse)
 Если ответ корректный, то данные ответа содержатся во вложенном теге &lt;Body&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 латинский, обязательный) (секунды
 обязательны). Время указано в часовом поясе сервера который
 предоставляет контент. Все идентификаторы сущностей (id) это строки,
 произвольного формата, длинной до 36 символов.
 Пустой ответ:

 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <UpdateTicketResponse>
 </UpdateTicketResponse>
 ```

 Пример ответа в случае успешной обработки запроса:

 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <Response success="true">
 <EchoResponse>
    <Body>
        <message>Test</message>
    </Body>
 </Response>
 </EchoResponse>
 ```

 Пример ответа в случае обработки запроса с ошибкой:

 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <Response success="false">
 <BookResponse>
    <Error>
        <code>ERROR</code>
        <message>Место 5 занято</message>
    </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>
 ```

 ```json
 {
  "message": "Test"
 }
 ```

 Ответ:

 ```xml
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <Response success="true">
 <EchoResponse>
    <Body>
        <!-- Сообщение переданное в запросе -->
        <message>Test</message>
    </Body>
 </Response>
 </EchoResponse>
 ```

 ```json
 {
  "body": {
    "message": "Test"
  }
 }
 ```


 ### getDispatchStations

 Метод получения станций отправления. Продажа происходит от станции
@@ -132,11 +224,15 @@ XML-ответ сервиса, реализующего протокол в об
 </GetDispatchStationsRequest>
 ```

 ```json
 {}
 ```

 Ответ:

 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <Response success="true">
 <GetDispatchStationsResponse>
    <Body>
        <!-- Станция -->
        <Station>
@@ -162,15 +258,43 @@ XML-ответ сервиса, реализующего протокол в об
            <okato>45000000000</okato>
        </Station>
    </Body>
 </Response>
 </GetDispatchStationsResponse>
 ```

 ```json
 {
  "body": [
    {
      "id": "983",
      "name": "ВДНХ АС",
      "region": "Москва",
      "okato": "45000000000"
    },
    {
      "id": "853",
      "name": "Варшавская АС",
      "region": "Москва",
      "okato": "45000000000"
    },
    {
      "id": "6",
      "name": "Красногвардейская АС",
      "region": "Москва",
      "okato": "45000000000"
    }
  ]
 }
 ```


 ### getArrivalStations

 Метод получения станций назначения от станции отправления. В параметре
 принимает идентификатор станции отправления. Станциями назначения могут
 быть любые остановочные пункты до которых есть хотя бы один рейс. Если
 станций назначения нет, метод должен вернуть пустой список.
 станций назначения нет, метод должен вернуть пустой список. 
 В случае отсутствия станций назначения для указанной станции отправления
 возвращать пустой ответ.

 **URL: \[BASE\_URL\]/sales/getArrivalStations**

@@ -184,44 +308,52 @@ XML-ответ сервиса, реализующего протокол в об
 </GetArrivalStationsRequest>
 ```

 ```json
 {
  "dispatchStationId": "983"
 }
 ```

 Ответ:

 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <Response success="true">
    <Body>
        <Station>
            <id>1069</id>
            <name>Рыбинск</name>
            <region>Ярославская область</region>
            <okato>78415000000</okato>
        </Station>
        <Station>
            <id>1018</id>
            <name>Сергиев Посад</name>
            <region>Московская область</region>
            <okato>46215501000</okato>
        </Station>
        <Station>
            <id>1084</id>
            <name>Углич</name>
            <region>Ярославская область</region>
            <okato>78420000000</okato>
        </Station>
        <Station>
            <id>1078</id>
            <name>Утена</name>
            <region>Литва</region>
        </Station>
    </Body>
 </Response>
 {
  "body": [
    {
      "id": "1069",
      "name": "Рыбинск",
      "region": "Ярославская область",
      "okato": "78415000000"
    },
    {
      "id": "1018",
      "name": "Сергиев Посад",
      "region": "Московская область",
      "okato": "46215501000"
    },
    {
      "id": "1084",
      "name": "Углич",
      "region": "Ярославская область",
      "okato": "78420000000"
    },
    {
      "id": "1078",
      "name": "Утена",
      "region": "Литва"
    }
  ]
 }
 ```

 ### searchTrips

 Метод возвращает список рейсов от станции отправления до станции
 назначения на заданную дату. В параметрах передается идентификатор
 станции отправления, идентификатор станции назначения и дата.
 станции отправления, идентификатор станции назначения и дата. 
 В случае отсутствия рейсов для указанных параметров возвращать пустой ответ.
 Рейсы должны быть отсортированы по дате отправления.

 **URL: \[BASE\_URL\]/sales/searchTrips**

@@ -243,7 +375,7 @@ XML-ответ сервиса, реализующего протокол в об

 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <Response success="true">
 <SearchTripsResponse>
    <Body>
         <!-- Рейс-->
        <Trip>
@@ -326,7 +458,7 @@ XML-ответ сервиса, реализующего протокол в об
            <freeSeatCount>49</freeSeatCount>
        </Trip>
    </Body>
 </Response>
 </SearchTripsResponse>
 ```

 ### getFreeSeats
@@ -355,7 +487,7 @@ XML-ответ сервиса, реализующего протокол в об

 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <Response success="true">
 <GetFreeSeatsResponse>
    <Body>
        <!-- Место-->
        <Seat>
@@ -377,7 +509,7 @@ XML-ответ сервиса, реализующего протокол в об
            <type>Сидячее</type>
        </Seat>
    </Body>
 </Response>
 </GetFreeSeatsResponse>
 ```

 ### getTicketTypes
@@ -406,7 +538,7 @@ XML-ответ сервиса, реализующего протокол в об

 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <Response success="true">
 <GetTicketTypesResponse>
    <Body>
        <TicketType>
            <!-- Идентификатор типа билета. Обязателен. Может совпадать с названием. -->
@@ -435,7 +567,7 @@ XML-ответ сервиса, реализующего протокол в об
            <ticketClass>BAGGAGE</ticketClass>
        </TicketType>
    </Body>
 </Response>
 </GetTicketTypesResponse>
 ```

 ### getDocumentTypes
@@ -471,7 +603,7 @@ XML-ответ сервиса, реализующего протокол в об

 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <Response success="true">
 <GetDocumentTypesResponse>
 <Body>
    <DocumentType>
        <!-- ID типа документа. Обязателен. -->
@@ -488,7 +620,7 @@ XML-ответ сервиса, реализующего протокол в об
        <name>Свидетельство о рождении</name>
    </DocumentType>
 /Body>
 </Response>
 </GetDocumentTypesResponse>
 ```

 Таблица 1. Коды документов, удостоверяющих личность, при передаче в АЦБПДП
@@ -553,7 +685,7 @@ XML-ответ сервиса, реализующего протокол в об

 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <Response success="true">
 <GetTripStopsResponse>
    <Body>
        <Stop>
            <!-- ID остановки. Совпадает с ID станции. Обязателен. -->
@@ -594,7 +726,7 @@ XML-ответ сервиса, реализующего протокол в об
            <price>1177</price>
        </Stop>
    </Body>
 </Response>
 </GetTripStopsResponse>
 ```

 ### bookOrder
@@ -655,6 +787,8 @@ XML-ответ сервиса, реализующего протокол в об
            FEMALE - Женский
            -->
            <gender>MALE</gender>
            <!-- Телефон пассажира. Не обязателен. -->
            <phone>999-888-77-66</phone>
            <!--
            Дополнительная произвольная информация. Не обязательно.
            -->
@@ -675,14 +809,14 @@ XML-ответ сервиса, реализующего протокол в об

 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <Response success="true">
 <BookOrderResponse>
    <Body>
        <!-- Идентификатор заказ. Обязателен. -->
        <orderId>9828350</orderId>
        <!-- Время жизни заказа. В минутах. Не обязателен. По умолчанию значение 30 -->
        <lifetime>30</lifetime>
    </Body>
 </Response>
 </BookOrderResponse>
 ```

 ### getOrder
@@ -709,7 +843,7 @@ XML-ответ сервиса, реализующего протокол в об

 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <Response success="true">
 <GetOrderResponse>
    <Body>
    <!-- Идентификатор заказа. Обязателен. -->
        <orderId>9828350</orderId>
@@ -776,25 +910,20 @@ RETURNED Выполнен возврат билета. Данный статус
                <birthday>1985-01-01</birthday>
                <citizenshipISO2>RU</citizenshipISO2>
                <gender>MALE</gender>
                <phone>999-888-77-66</phone>
                <info>FewwLks Mq</info>
            </Passenger>
            <!-- Тариф (руб). Обязателен после подтверждения. -->
            <fare>0</fare>
            <!-- Cборы (руб). Обязателен после подтверждения. Если нет то 0. -->
            <fees>0</fees>
            <!-- Удержано Тариф (руб). Обязателен в случает возврата или отмены. -->
            <chargeFare>0</chargeFare>
            <!-- Удержано Остальные сборы (руб). Обязателен в случает возврата или отмены. -->
            <chargeOthers>0</chargeOthers>
            <!-- Возврат Тариф (руб). Обязателен в случает возврата или отмены. -->
            <repaymentFare>0</repaymentFare>
            <!-- Возврат Остальные сборы (руб). Обязателен в случает возврата или отмены. -->
            <repaymentOthers>0</repaymentOthers>
            <!-- Удержано Остальные сборы (руб). Обязателен в случает возврата. -->
            <repayment>0</repaymentFare>
            <!-- Информация о страховании. Обязательно. Необходим при печати билета. -->
            <insuranceInfo>СТРАХОВЩИК: ПАО &quot;Росстрах&quot;; 119991; г. Москва; ул. Большая Ордынка; д. 40; стр.</insuranceInfo>
        </Ticket>
    </Body>
 </Response>
 </GetOrderResponse>
 ```

 ### confirmOrder
@@ -814,6 +943,7 @@ bookOrder или updateTicket. Вызов этого метода означае
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <ConfirmOrderRequest>
    <!-- ID заказа. Обязателен. -->
    <orderId>9828585</orderId>
    <!-- Агент выполнивший операцию. Не Обязателен. -->
    <Agent>
@@ -827,16 +957,19 @@ bookOrder или updateTicket. Вызов этого метода означае

 Ответ:

 Ответ аналогичен ответу на запрос [getOrder](#getorder)
 Ответ аналогичен ответу на запрос [getOrder](#getorder) c именем корневого тега ConfirmOrderResponse 

 ### cancelTicket

 Отмена билета. Техническая операция, выполняет полный возврат билета без
 Отмена одного или нескольких билетов. Техническая операция, выполняет полный возврат билета без
 удержаний. Необходима при нештатных ситуациях: в случае сбоев ККМ или
 обнаружения ошибки выбора рейса, персональных данных. В параметрах
 принимает идентификатор билета и информацию об агенте который совершил
 операцию. Можно выполнять после создания заказа и в течении 5-30 минут
 после подтверждения заказа.
 принимает идентификаторы билета и информацию об агенте который совершил
 операцию. Все билеты должны быть обработы в рамках одной транзакции. 
 т.е. если было передано 2 билета, первый был обработан а при обработке второго возникла ошибка
 то обработка первого должна быть отменена. 
 Можно выполнять после создания заказа и в течении 5-30 минут
 после подтверждения заказа. 

 **URL: \[BASE\_URL\]/sales/cancelTicket**

@@ -845,7 +978,9 @@ bookOrder или updateTicket. Вызов этого метода означае
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <CancelTicketRequest>
    <ticketId>12435434</ticketId>
    <!-- ID билетов для возврата. произвольное количество тегов. -->
    <ticketId>34</ticketId>
    <ticketId>36</ticketId>
    <!-- Агент выполнивший операцию. Не Обязателен. -->
    <Agent>
        <!-- Имя агента. Не обязателен.-->
@@ -858,12 +993,15 @@ bookOrder или updateTicket. Вызов этого метода означае

 Ответ:

 Ответ аналогичен ответу на запрос [getOrder](#getorder)
 Ответ аналогичен ответу на запрос [getOrder](#getorder) c именем корневого тега CancelTicketResponse

 ### returnTicket

 Возврат билета. При возврате возможны удержания. В параметрах принимает
 идентификатор билета и информацию об агенте который совершил операцию.
 Возврат одного или нескольких билетов. При возврате возможны удержания. В параметрах принимает
 идентификатор билета и информацию об агенте который совершил операцию. 
 Все билеты должны быть обработы в рамках одной транзакции. 
 т.е. если было передано 2 билета, первый был обработан а при обработке второго возникла ошибка
 то обработка первого должна быть отменена. 
 Билет можно вернуть только после подтверждения confirmOrder.

 **URL: \[BASE\_URL\]/sales/returnTicket**
@@ -873,7 +1011,9 @@ bookOrder или updateTicket. Вызов этого метода означае
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <ReturnTicketRequest>
    <ticketId>12435435</ticketId>
    <!-- ID билетов для возврата. произвольное количество тегов. -->
    <ticketId>35</ticketId>
    <ticketId>36</ticketId>
    <!-- Агент выполнивший операцию. Не Обязателен. -->
    <Agent>
        <!-- Имя агента. Не обязателен.-->
@@ -886,7 +1026,7 @@ bookOrder или updateTicket. Вызов этого метода означае

 Ответ:

 Ответ аналогичен ответу на запрос [getOrder](#getorder)
 Ответ аналогичен ответу на запрос [getOrder](#getorder) c именем корневого тега ReturnTicketResponse

 ### updateTicket

@@ -945,6 +1085,7 @@ bookOrder или updateTicket. Вызов этого метода означае

 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <Response success="true">
 </Response>
 <UpdateTicketResponse>
 </UpdateTicketResponse>
 ```