API сервиса поиска вагонов
Описание протокола обмена данными с системой поиска вагонов от Альта-Софт
Обмен данными между сервисом Альта-Софт и сторонними ресурсами осуществляется по протоколу http, транспорт xml. Все запросы в системе – POST.
1) Выполнение запроса на поиск вагона или контейнера.
На адрес http://ww.alta.ru/rail_tracking/api_v1.php нужно послать xml-строку следующего формата:
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<root>
<query>
<login>your_login</login>
<password>your_password</password>
<action>add</action>
<type>1|2</type>
<state>20</state>
<name>My query</name>
<vag num=”some_num_1”/>
<vag num=”some_num_2”/>
….
<vag num=”some_num_n” />
</query>
</root>
Где:
login и password – учетные данные, выданные при регистрации личного кабинета
action – [add|get] – добавление запроса на поиск (add) или получение ответа по добавленному ранее запросу (get)
type – [1|2] 1 - запрос на поиск вагонов, 2 – запрос на поиск контейнеров
state – необязательный параметр, код государства запроса, для России всегда 20
name – необязательный параметр, произвольный идентификатор запроса, он будет отображаться в личном кабинете на alta.ru при просмотре через web-интерфейс
vag – список вагонов для выполнения поиска, где атрибут num – собственно номер вагона или контейнера.
В одном запросе не допускается включать номера перевозочных средств разных типов, т.е. в запросе должны быть либо номера только вагонов, либо номера только контейнеров (в соответствии с заданным type).
В ответ система выдаст xml следующего содержания:
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<root>
<response>
<status code="result_code" descr="Result_descr">ok|error</status>
<hash>your_query_hash</hash>
</response>
</root>
Где:
Status – [ok|error], статус запроса, ok – выполнен успешно, error – возникла ошибка.
При успешном завершении выполнения запроса атрибут code всегда равен нулю, при возникновении ошибки code = [50|60|70|100], в атрибуте descr – текстовое описание ошибки.
Коды ошибок:
50 – Не указан список вагонов/контейнеров
60, 70 – зарезервировано
91 – ошибка соединения с базой
92 – Неверный логин/пароль
93 – Аккаунт не активирован
94 – Неизвестная ошибка
95 – Указанное действие не поддерживается
96 - Дубликат запроса, действие отменено. Выполнить запрос с такими же параметрами можно через 3 минуты
97 - Данному пользователю разрешено размещать запросы только по РФ
100 – Недостаточно денег на балансе для выполнения запросов
Hash - в случае успеха добавляется элемент hash, содержащий уникальный идентификатор запроса, по которому можно будет получить ответ, содержащий информацию по дислокации перевозочных средств.
2) Получение результата запроса.
Не ранее чем через 1 минуту после добавления запроса, по адресу http://www.alta.ru/rail_tracking/api_v1.php можно выполнить xml-запрос на получение результата. Содержание xml-строки:
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<root>
<query>
<login>your_login</login>
<password>your_password</password>
<action>get</action>
<hash>your_query_hash</hash>
</query>
</root>
Где:
login и password – учетные данные, выданные при регистрации личного кабинета
action – [get] получение ответа по добавленному ранее запросу (get)
hash – уникальный идентификатор, полученный при добавлении запроса на выполнение
В ответ система выдаст xml следующего содержания:
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<root>
<response>
<status code="result_code" descr="Result_descr">1|2|3|4|error</status>
<vag num=”some_num_1” [атрибуты, см. далее описание] />
<vag num=”some_num_2” [атрибуты, см. далее описание] />
….
<vag num=”some_num_n” [атрибуты, см. далее описание] />
</response>
</root>
Где:
Status=error – если возникла ошибка или от «1» до «4» – состояние запроса. В атрибуте code всегда ноль при успешной обработке запроса или код ошибки. Descr – текстовое описание ошибки или состояния запроса.
Коды состояния status:
1 – в очереди на обработку
2 – обрабатывается
3 – частично обработан (получены данные не по всем перевозочным средствам)
4 – полностью обработан
Коды ошибок code:
30 – запрос с указанным hash отсутствует (не формировался)
40 – ошибка при запросе к базе
91 – ошибка соединения с базой
92 – Неверный логин/пароль
93 – Аккаунт не активирован
94 – Неизвестная ошибка
95 – Указанное действие не поддерживается
100 – Недостаточно денег на балансе для выполнения запросов
При status=3 или status=4 xml-ответ дополняется элементами vag, содержащими информацию по дислокации перевозочных средств. Ниже даны описания атрибутов:
num – номер запрошенного вагона/контейнера
station – ecp-код станции
op_date – дата операции
station_name – наименование станции
lon и lat – широта и долгота станции (если есть в базе)
state – код государства станции
state_name – наименование государства станции
road_name – дорога станции
operation – операции, совершенная на станции с поездом
okpo – ОКПО собственника перевозочного средства
owner – наименование собственника перевозочного средства (если доступно)
kgro и kgrp – коды грузоотправителя и грузополучателя
train_index – индекс поезда
train_number – номер поезда
freight – код груза ЕТСНГ
freight_name – наименование груза ЕТСНГ
weight – масса груза в центнерах
vag_number – только для контейнеров, номер вагона, на котором размещен контейнер
rasst – расстояние, оставшееся до станции назначения
Пример ответа:
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<root>
<response>
<status descr="Обработан" code="0">4</status>
<vag num="54922810" station="19380" station_name="Перово" lon="37.764368" lat ="55.735818" state="20" state_name="Россия" road_name="Московская" op_date="2013-10-14 21:57:00" operation="РАСФОРМИРОВАНИЕ ПОЕЗДА" okpo="87556235" owner="ООО "ИМПРОМ"" kgro="0" kgrp="9999" train_index="0" train_number="0" freight="42110" freight_name="Платформы железнодорожные, перевозимые на своих осях" weight="0" vag_number="" rasst="76" />
<vag num="54973847" station="98380" station_name="Партизанск" lon="133.143368" lat ="43.06927" state="20" state_name="Россия" road_name="Дальневосточная" op_date="2013-10-16 13:44:00" operation="ПРОСЛ.ПОЕЗ.""НАШЕЙ"" СТ.Б/ОСТ(БЕЗ ПР./СД. НА ДР.ДОР)" okpo="62716542" owner="ООО "Репетек"" kgro="6856" kgrp="0032" train_index="9859004123050" train_number="1297" freight="300" freight_name="" weight="250" vag_number="" rasst="9232" />
<vag num="67770560" station="29300" station_name="Коноша I" lon="40.247064" lat ="60.974297" state="20" state_name="Россия" road_name="Северная" op_date="2013-10-15 23:18:00" operation="БРОСАНИЕ ПОЕЗДА НА СТАНЦИИ" okpo="68398528" owner="ОАО [ВГКk" kgro="5194" kgrp="2865" train_index="100016123700" train_number="2301" freight="23205" freight_name="Габбро" weight="690" vag_number="" rasst="732" />
</response>
</root>
3) Запрос баланса
На адрес http://www.alta.ru/rail_tracking/api_v1.php выполнить xml-запрос на получение баланса. Содержание xml-строки:
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<root>
<query>
<login>your_login</login>
<password>your_password</password>
<action>balans</action>
</query>
</root>
В ответ получите xml, содержащую баланс на момент запроса.
Пример ответа:
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<root>
<response>
<status descr="Обработан" code="0">ok</status>
<balans>[остаток на счете на момент запроса в рублях]</balans>
</response>
</root>
Status=error – если возникла ошибка. В атрибуте code всегда ноль при успешной обработке запроса или код ошибки.
Descr – текстовое описание ошибки или состояния запроса.
Коды ошибок code:
91 – ошибка соединения с базой
92 – Неверный логин/пароль
93 – Аккаунт не активирован
94 – Неизвестная ошибка
95 – Указанное действие не поддерживается
Примеры запросов для языка PHP.
1) Запрос на поиск (add_query_example.php)
<?php
function post_data($url, $params, $timeout = 5)
{
$opts = array('http' => array( 'method' => 'POST', 'header' => 'Content-type: application/x-www-form-urlencoded', 'content' => $params, 'timeout' => $timeout ) );
$context = stream_context_create($opts);
$result = file_get_contents($url, false, $context);
return $result;
}
$login = 'your_login';
$pass = 'your_password';
$xml_str = "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>";
$xml_str .= "<root><query><login>$login</login><password>$pass</password>";
$xml_str .= "<action>add</action>";
$xml_str .= '<vag num="54532312"/>';
$xml_str .= '<vag num="54563036"/>';
$xml_str .= '<vag num="59616896"/>';
$xml_str .= '<state>20</state>';
$xml_str .= '<type>1</type>';
$xml_str .= '<name>Пример запроса</name>';
$xml_str .= "</query></root>";
$result = post_data("http://www.alta.ru/rail_tracking/api_v1.php", $xml_str, 5);
$xml = simplexml_load_string($result);
$status = $xml->response->status;
echo '<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />';
if ($status == 'ok')
{
echo "Результат: ".$status['descr'];
echo "<br/>";
echo "Идентификатор запроса: ".$xml->response->hash;
}
else
{
echo "Результат: ".$status['descr'];
echo "<br/>";
echo "Код ошибки: ".$status['code'];
}
?>
2) Запрос на получение ответа (get_response_example.php)
<?php
function post_data($url, $params, $timeout = 5)
{
$opts = array('http' => array( 'method' => 'POST', 'header' => 'Content-type: application/x-www-form-urlencoded', 'content' => $params, 'timeout' => $timeout ) );
$context = stream_context_create($opts);
$result = file_get_contents($url, false, $context);
return $result;
}
$login = 'your_login';
$pass = 'your_password';
$xml_str = "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>";
$xml_str .= "<root><query><login>$login</login><password>$pass</password>";
$xml_str .= "<action>get</action>";
$xml_str .= '<hash>c4cf2a16090153f078ea263acab1a6d8</hash>';
$xml_str .= "</query></root>";
$result = post_data("http://www.alta.ru/rail_tracking/api_v1.php", $xml_str, 5);
$xml = simplexml_load_string($result);
$status = $xml->response->status;
echo '<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />';
if ($status != 'error')
{
echo "Статус запроса: ".$status['descr'];
echo "<hr/>";
foreach ($xml->xpath('/root/response/vag') as $vag)
{
echo "Станция: ".$vag['station'].' '.$vag['station_name']."<br/>";
echo "Координаты станции: ".$vag['lon'].' '.$vag['lat'].'<br/>';
echo "Дата: ".$vag['op_date']."<br/>";
echo "Операция: ".$vag['operation']."<br/>";
echo "ОКПО собственника: ".$vag['okpo'].' '.$vag['owner'].'<br/>';
echo "<hr/>";
}
}
else
{
echo "Результат: ".$status['descr'];
echo "<br/>";
echo "Код ошибки: ".$status['code'];
}
?>
Все действия, производимые через api видны и в web-интерфейсе системы (на закладках «в обработке» и «отчеты»)
