Определения Транспортная информация – информация

Определения
Транспортная информация – информация касающаяся расписания, графика движения
транспортных средств по маршрутам, классности транспортных средств, наличия свободных
мест, стоимости проезда, прочее...
Маршрут-квитанция – Документ дающий право пользователю бесплатно получить
проездной документ.
Код Маршрут-квитанции — номер состоящий из букв и цифр позволяющий получить
проездной документ в кассе Автостанции или ЖД вокзала.
Сайт интернет-агента – веб-сайт обеспечивающий доступ к транспортной информации
по принципам изложенным в данном документе.
Интернет-агент – организация обладающая сайтом транспортной направленности.
Centralized Distribution Transport System (CDTS) – система агрегирующая
транспортную информацию от разных поставщиков и предоставляющая своим клиентам доступ
к ней в унифицированном виде.
Задача данного документа
Пользователю необходимо предоставить возможность купить билет на транспорт через
интернет с использованием представленных на рынке платёжных систем. Наиболее
эффективным путём продвижения данной услуги (покупки поездки через интернет), является
размещения на ресурсах уже существующих интернет-проектов (сайтах интернет агентов)
элементов пользовательского интерфейса позволяющих посетителю данного ресурса получить
доступ к транспортной информации и приобрести билет при необходимости. Способ
встраивания данных элементов в указанные интернет-ресурсы и является целью данного
документа.
Принципы интеграции
Сценарий поведения пользователя при покупке билета имеет вид:
1. Указание начальных параметров поездки, а именно:
1. Вид транспорта
2. Точка отправления
3. Точка прибытия
4. Дата отправления
5. Дополнительные опции
2. Просмотр вариантов проезда (цены, время движения, классность).
3. Выбор интересующего варианта проезда
4. Уточнение дополнительных опций (номер вагона, места, прочее).
5. Резервирование мест в транспортном средстве
6. Выполнение оплаты с использованием платёжной системы
7. Получение Кода Маршрут-квитанции
При переходе от этапа к этапу пользователь взаимодействует с сайтом интернет-агента. Сайт
интернет-агента, на основании данных полученных от пользователя, производит обращение к
CDTS что позволяет ему отображать запрашиваемую пользователем информацию. Существует
два способ взаимодействия.
1. CDTS представляет web сервис (протокол взаимодействия) специфицированный с
использование WSDL. С его помощью сайт интернет-агента выполняет указанные
обращения отправляя XML запросы и получая XML ответы. Данный способ
предоставляет наибольшую гибкость при интеграции, однако требует значительных
трудозатрат по разработке и внедрению. Работа с CDTS через web service описана в
документе «Centralized Distribution Transport System Interconnection» и не является
предметом рассмотрения в данном случае.
2. Сайт интернет-агента встраивает непосредственно в код своих страниц ряд html
элементов (java-скрипты, css, html-код), и непосредственно из своего кода выполняет
запросы к CDTS. Результатом обработки этих запросов являются html-данные
представляющие подготовленную к выводу транспортную информацию, что позволяет
вывести её непосредственно среди прочего содержимого страницы cайта агента. Htmlданные содержащие транспортную информацию могут быть стилизованы
администратором сайта интернет-агента с использованием собственных сss определений.
Встраивание транспортной информации
Встраивание происходит следующим образом — пользователь передаёт данные на
страницу интернет агента, с которой производится обращение к СDTS, результатом этого
обращения являются данные одной из экранных форм.
В данном документе приводятся примеры кода на PHP которые показывают сам принцип
выполнения обращений к CDTS. В случае если сайт интернет-агента разработан с
использованием других языков (технологий) разработку следует вести по аналогии.
Существует несколько типовых экранных форм которые предлагается использовать на
сайте интернет агента:
1. Экранная форма ввода параметров поездки (от,до,дата) from-to.php;
2. Экранная форма вариантов проезда trips.php;
3. Экранная форма информации об рейсе trip-info.php;
4. Экранная форма информации о карте вагона (список мест) car-map.php;
Пример работы сайта с использованием данных типовых форм приведён по адресу
http://example.t2t.in.ua
Базовые требования
Для того чтобы пользователь мог взаимодействовать с данными формами разработана
библиотека java-скриптов основанная на общеизвестной библиотеке jquery. Таким образом для
взаимодействия с транспортной информацией в соответствующие страницы сайта интернетагента должны быть добавлены следующие скрипты:
<!-- Строки на разных языках для JS -->
<script type="text/javascript" src="<?echo $cdts_url?>/js/messages.js"></script>
<!-- Основной код связанный с обработкой действий пользователя в
большинстве форм -->
<script type="text/javascript" src="http://gui.t2t.in.ua/js/common.js"></script>
<!-- Код связанный с действиями пользователя в форме указания
параметров поездки (от-до-дата) -->
<script type="text/javascript" src="http://gui.t2t.in.ua/js/common-from-to.js"></script>
<!-- Скрипты необходимые для функционирования jquery -->
<script type="text/javascript" src="http://gui.t2t.in.ua/js/jquery-1.4.4.min.js"></script>
<script type="text/javascript" src="http://gui.t2t.in.ua/js/jquery.tipbox.js"></script>
<script type="text/javascript" src="http://gui.t2t.in.ua/js/jquery.ui.datepicker-ru.js"></script>
<script type="text/javascript" src="http://gui.t2t.in.ua/js/jquery-ui-1.8.11.custom.min.js"></script>
Как было сказано ранее CDTS возвращает обычный html код который должен быть
стилизован с учетом дизайнерских решений принятых на данном интернет-ресурсе. Существуют
типовые стили которые могут быть использованы администратором сайта интернет-агента для
начала, а именно:
<link type="text/css" rel="stylesheet" href="http://gui.t2t.in.ua/css/jquery-ui-1.8.11.custom.css" />
<!-- Основные стили (форма списка вариантов проезда) -->
<link type="text/css" rel="stylesheet" href="http://gui.t2t.in.ua/template/common/css/style.css" />
<!-- Стили форм связанных с параметрами ЖД рейса -->
<link type="text/css" rel="stylesheet" href="http://gui.t2t.in.ua/template/common/css/rw.css" />
<!-- Стили форм связанных с параметрами Авто рейса -->
<link type="text/css" rel="stylesheet" href="http://gui.t2t.in.ua/template/common/css/bus.css" />
<!-- Стили формы указания параметров маршрута -->
<link type="text/css" rel="stylesheet" href="http://gui.t2t.in.ua/template/common/css/from-to.css" />
Для получения данных следует выполнять HTTP запросы по определённым URL CDTS.
Важным моментом является то что запросы к CDTS должны быть сессионными. CDTS, при
работе через экранные формы будет сохранять контекст сессий на своей стороне, потому
ответственностью сайта интернет-агента является создание идентификаторов сессий. В качестве
идентификатора сессии следует использовать строку длинной 32 символа включающей буквы
английского алфавита и цифры (что является способом идентификации сессий в PHP).
Идентификатор сессии следует передавать CDTS через cookie с именем PHPSESSID при
выполнении каждого запроса. Таким образом для вызова CDTS можно воспользоваться
следующим примером кода:
<?php
// Внимание!!! Для работы данного кода должна сессия уже должна быть открыта.
Т.е. ф-ция session_start() уже должна быть вызвана.
function cdts_check_session_id() // Генерация идентификатора сессии CDTS в рамках текущей
сессии пользователя
{
if(!isset($_SESSION)) session_start(); // Если сессия сайта интернет-агента еще не начата
начать сессию
if(!isset($_SESSION['CDTS_SESSID'])) // Если идентификатор сессии CDTS еще не создан (Сессия
не открыта) создать его
{
$len = 32;
$characters = '0123456789abcdefghijklmnopqrstuvwxyz';
$string ="";
$cn=strlen($characters);
for ($i = 0; $i < $len; $i++) {
$string .= $characters[mt_rand(0, $cn-1)];
}
$_SESSION['CDTS_SESSID']=$string;
}
return $_SESSION['CDTS_SESSID'];
}
function cdts_query($url) // получить данные у cdts по указанному URL
{
$cdts_ss_id=cdts_check_session_id(); // Получить идентификатор CDTS-сессии
$r = new HttpRequest($url);
try {
$r->addCookies(array("PHPSESSID"=>$cdts_ss_id)); // Добавить идентификатор в обьект
запроса.
$r->send(); // Выполнить запрос
if ($r->getResponseCode() == 200) {
return $r->getResponseBody(); // Если успешно вернуть ответ
}
else
{
return $r->getResponseCode(); // Или код ошибки
}
} catch (HttpException $ex) {
return "При обращении к серверу расписаний возникла ошибка.
Попробуйте позже";
}
}
?>
Экранная форма ввода параметров поездки
Для правильного отображения данных в текстовых полях с автозаполнением (через
которые вводятся названия станции) на странице должна присутствовать переменная:
<script type="text/javascript">
window.global_lang_id = <?php echo $language;?> // Для выбора языка форм
</script>
В данный момент существует поддержка языков:
1. Ангийский — код 1
2. Русский — код 2
3. Украинский — код 3
Добавив на страничку java-скрипты и типовые стили можно добавлять начальную
(типовую) форму ввода параметров рейса:
<body>
<?
echo cdts_query("http://gui.t2t.in.ua/from-to.php?apn=agent1&trips_redirect_page=/show.php&user_data=...&out_encoding=utf8&set_language=2");
?>
</body>
Экранная форма from-to.php представляет собой базовую типовую форму с
использованием которой пользователь может ввести параметры поездки.
Параметры формы from-to.php:
1. apn — имя интернет-агента, присваивается при заключении договора.
2. trips_redirect_page — относительный адрес страницы сайта интернет-агента которая
обработает запрос пользователя о списке рейсов. Как было сказано ранее, веб браузер
пользователя передаёт все введённые данные на страницу сайта интернет-агента
которая обязана выполнить запрос к cdts (куда передать полученные от пользователя
данные) и показать пользователю полученную информацию. Таким образом
trips_redirect_page это страница на которую пользователь попадёт после нажатия на
кнопку найти.
3. user_data — информация о пользователе который в данный момент выполняет запрос (см.
раздел «Передача на сторону CDTS информации о пользователе»)
4. out_encoding — кодировка в которой cdts будет возвращать экранные формы, по
умолчанию cdts возвращает данные в кодировке utf-8
5. set_language — Информация о том в каком языке должен быть вывод
Предложенный вариант добавления данной формы представляет собой использование
типового подхода. Поскольку в этом режиме данная форма статична (нет динамического
содержимого), администратор сайта интернет-агента может реализовать свой вид размещения
элементов формы (с условием наличия всех полей и соблюдения значений атрибутов class. Id и
name). Т. е. вместо обращение к CDTS разработать полностью своё оформления данной формы.
Экранная форма from-to.php использует поля с автозаполнением для ввода станций
отправления и прибытия. Автозаполнение реализовано с использованием возможностей jquery и
ajax запросов. Т.е. каждый раз когда пользователь вводит что-либо в полях формы from-to.php
выполняется ajax-запрос «о списке станций» к серверу интернет-агента. Ajax запросы «о списке
станций» должны обрабатываться страничкой сайта интернет-агента которая, как и в
предыдущем случае, должна выполнять запрос к CDTS отдавая полученное содержимое
браузеру пользователя без изменения. В данном случае содержимое представляет собой xml
данные со списком станций отфильтрованные на основании того какую информацию
пользователь ввёл в форме.
Важно! Для экранной формы from-to.php должен быть указан url страницы которая
обрабатывает ajax-запросы по получению списка станций.
Данный адрес передаётся через javascript-переменную window.search_station_root. Таким образом
следует добавить в страницу сайта содержащую форму from-to следующий код:
<script type="text/javascript">
window.search_station_root="/ss.php";
</script>
Где ss.php страничка отвечающая за обработку запроса на получение списка станций. Страничка
ss.php в нашем случае ДОЛЖНА иметь вид в точности идентичный данному:
<?
header("content-type: text/xml; charset=windows-1251;");
$url="http://gui.t2t.in.ua";
include "cdts/query.php";
echo
cdts_query($url."/awg/xml?class_name=IStations&method_name=search_station&var_0=".$_REQUEST['var_0']."&var_1=".$_REQUEST['va
r_1']."&var_2=".$_REQUEST['var_2']."&var_3=".$_REQUEST['var_3']."&var_4=".urlencode($_REQUEST['var_4']));
?>
Поскольку от пользователей будет приходить довольно большое количество запросов подобного
вида, данная часть процесса может быть оптимизирована. Для чего потребуется настройка вебсервера на «проксирование» запросов о списке станций непосредственно к CDTS. Способ
реализации данной возможности зависит от используемого интернет-агентом веб-сервера.
Например для nginx конфигурация будет иметь вид:
location /awg
{
proxy_pass
proxy_redirect
proxy_set_header
proxy_set_header
proxy_set_header
"http://gui.t2t.in.ua/awg";
off;
Host
$host;
X-Real-IP
$remote_addr;
X-Forwarded-For
$proxy_add_x_forwarded_for;
}
На данном этапе, на страничке сайта интернет-агента, размещена форма которая
позволяет выбрать начальные параметры поездки (с использованием автозаполнения) и
выполнить переход на другую страничку (или туже самую) сайта интернет-агента где должна
быть выведена транспортная информация.
Экранная форма вариантов проезда
Данная экранная форма (как понятно из её названия) служит для вывода информации о
списке поездов (рейсов) удовлетворяющих критериям пользователя введённым на предыдущем
этапе. Как и в предыдущем случае, экранная форма вариантов проезда добавляется на страницу
путём вызова определённого URL CDTS с передачей параметров полученных от экранной
формы ввода параметров поездки.
Параметры экранной формы вариантов проезда:
1. apn — имя интернет-агента присваивается при заключении договора.
2. trips_redirect_page – относительный адрес страницы сайта интернет-агента которая
обработает запрос пользователя о списке рейсов. Как правило значение данного
параметра полностью совпадает с названием текущей страницы.
3. transport_type – вид транспорта
4. src – код пункта отправления
5. dst – код пункта прибытия
6. dt – дата отправления
7. ps – платёжная система
8. hide_from_to – по умолчанию экранная форма вариантов проезда размещает в верхней
своей части экранную форму ввода параметров поездки. Это поведение можно отключить
если в данном параметре передать значение «yes».
9. user_data — информация о пользователе который в данный момент выполняет запрос (см.
раздел «Передача CDTS информации о пользователе»)
10. apn_back_ref — адрес на который пользователь должен вернуться после выполнения
оплаты билета (см. раздел «Оплата билета»).
11. out_encoding — кодировка в которой cdts будет возвращать экранные формы, по
умолчанию cdts возвращает данные в кодировке utf-8
12. set_language — Информация о том в каком языке должен быть вывод
Все эти параметры подготавливаются в экранной форме ввода параметров поездки, что
позволяет выполнить вызов CDTS таким образом:
<?
$trips_form_url="$cdts_url/trips.php".
"?apn=".$example_apn.
"&user_data=".$user_data.
"&trips_redirect_page=/show.php".
"&transport_type=".$_REQUEST['transport_type'].
"&src=".$_REQUEST['src'].
"&dst=".$_REQUEST['dst'].
"&dt=".$_REQUEST['dt'].
(isset($_REQUEST['ps'])?"&ps=".$_REQUEST['ps']:"").
(isset($back_ref)?('&apn_back_ref='.urlencode($back_ref)):'').
"&out_encoding=".$charset.
"&set_language=".$language;
echo cdts_query($trips_form_url);
?>
Данная экранная форма так-же использует ajax запросы для вывода информации о рейсе и карте
вагона.
Важно! Для экранной формы trips.php должен быть указаны url страницы которая
обрабатывает ajax-запросы по получению информации о рейсе и url страницы
обрабатывающей ajax-запросы по получению карты вагона.
Эти параметры передаются через переменные window.trip_info_root и window.car_map_root,
таким образом для настройки этой экранной формы следует добавить на страницу следующий
код:
<script type="text/javascript">
window.trip_info_root="/trip-info.php";
window.car_map_root = "/car_map.php";
</script>
В случае добавления данного javascript-кода на страницу интернет-агента мы укажем что
запросы по получению информации о рейсе перенаправлять на страничку /trip-info.php, а
запросы о карте вагона перенаправлять на страничку /car-map.php. Обе эти странички как и в
случае ss.php должны вызывать соответствующие URL CDTS передавая в них все параметры
пришедшие от браузера пользователя. Данное название страничек является рекомендованным.
Если администратор сайта интернет-агента назвал данные страницы именно так как
рекомендуется, то программный код обоих этих страниц будет иметь такой вид:
<?
header("content-type: text/html; charset=utf-8;");
$url="http://gui.t2t.in.ua";
include "cdts/query.php";
echo cdts_query($url.$_SERVER['REQUEST_URI']."&out_encoding=".$charset);
?>
При обращении к данным страницам все переданные параметры будут переадресовываться на
соответствующий url CDTS – http://gui.t2t.in.ua/trip-info.php и http://gui.t2t.in.ua/car_map.php.
На данном этапе, реализация описанных функциональных точек позволяет встроить в
сайт интернет-агента пользовательский интерфейс предоставляющий возможность
пользователю получать информацию о возможностях проезда между двумя станциями на
определённую дату а так-же просматривать дополнительную информацию о каждом конкретном
рейсе, поезде.
Покупка билета
Если на сайте интернет-агента полностью реализовано получение расписания, то кликнув
на любом рейсе пользователь может указать его параметры и перейти непосредственно к
покупке. Покупка осуществляется следующим образом:
1. При работе со списком рейсов пользователь указывает необходимые параметры поездки.
2. В результате выбора параметров заполняются поля html-формы заказа билета.
3. Пользователь нажимает заказать
4. Данные о рейсе, собранные на предыдущем этапе, пересылаются страницу
invoice.t2t.in.ua где пользователю выводится Маршрут-квитанция. До получения оплаты
Код Маршрут-Квитанции не выводится. На выполнение оплаты пользователю отводится
ограниченное время, по истечении которого не оплаченная Маршрут-Квитанция
5.
6.
7.
8.
9.
аннулируется.
На странице invoice.t2t.in.ua пользователь выбирает способ оплаты (платёжную систему)
Пользователь переходит на страницу платёжной системы где выполняет действия
необходимые для оплаты счёта.
По результату выполнения оплаты пользователь возвращается на страницу
invoice.t2t.in.ua.
Если оплата была выполнена успешно на маршрут квитанции появляется Код МаршрутКвитанции который должен быть использован для получения проездного документа.
Пользователь может нажать кнопку «назад» и вернуться на страницу интернет-агента с
которой он выполнил заказ билета.
Передача CDTS информации о пользователе
Для покупки билета с использованием механизма рассмотренного в данном документе
пользователь должен иметь учётную запись на сервере CDTS и должен быть авторизован. Для
того чтобы не заставлять пользователя выполнять дополнительную работу по регистрации и
авторизации на сервере CDTS, сайт интернет-агента может добавить в запросы к CDTS (а
особенно в запрос к экранной форме from-to.php) поле user_data в котором передать
информацию о пользователе.
Значение поля user_data состоит из таких полей:
1. название агента (apn)
2. e-mail пользователя
3. телефона пользователя (может быть пустым).
Все 3 эти поля форматируются в виде HTTP GET строки. К примеру если у нас есть
интернет-агент example.t2t.in.ua, пользователь example@i.ua, c телефоном 012345678, то строка
user_data будет сформирована как apn=example.t2t.in.ua&email=example@i.ua&phone=012345678.
Полученная строка должна быть подвергнута url-кодированию.
Поскольку эти данные будут передаваться в открытом, виде полученная строка должна
быть зашифрована с использованием алгоритма DES и ключа известного только агенту и CDTS.
Полный пример функции формирования строки user_data
function cdts_user_wrap($apn,$email,$phone,$key)
{
$str="apn=".urlencode($apn)."&email=".urlencode($email)."&phone=".urlencode($phone);
$ret=mcrypt_encrypt(MCRYPT_DES,$key,$str,MCRYPT_MODE_ECB);
$ret=base64_encode($ret);
return urlencode($ret);
}
Переданная информация будет использована для автоматического создания учётной
записи пользователя (о чем пользователь получит email уведомление) и автоматического входа
пользователя под этой учётной записью. Шифрование необходимо для того чтобы
злоумышленник не мог автоматически создавать учётные записи в системе CDTS и чтобы
данные пользователя не передавались по сети в открытом виде.
Если на сайте интернет-агента не используется авторизация пользователей, т. е. нет
возможности передать CDTS аккаунт пользователя, сайт CDTS предложит пользователю указать
свой куда будет выслана ссылка на его билет. По факту перехода по данной ссылке
пользовательская учётная запись будет создана, пользователь авторизован в CDTS, пользователь
получит возможность выполнить оплату билета.
Начало работы
1.
2.
3.
4.
5.
Для начала работы интернет-агент должен:
Быть зарегистрированным в CDTS
Получить APN
Получить ключ (пароль) которым шифровать user_data
Согласовать объём наценки и свою долю в ней.
Предоставить емейл ответсвенного за сверку. Данному пользователю будет предоставлен
доступ к системе отчётности.