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) Получение результата запроса.

Не ранее чем через 15 минут после добавления запроса, по адресу 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="ООО &quot;ИМПРОМ&quot;" 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="ПРОСЛ.ПОЕЗ.&quot;&quot;НАШЕЙ&quot;&quot; СТ.Б/ОСТ(БЕЗ ПР./СД. НА ДР.ДОР)" okpo="62716542" owner="ООО &quot;Репетек&quot;" 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-интерфейсе системы (на закладках «в обработке» и «отчеты»)