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="ООО &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-интерфейсе системы (на закладках «в обработке» и «отчеты»)

Тестирования сервиса

Для отладки взаимодействия сервиса поиска вагонов и учетной системы клиента существует возможность отправлять запросы и получать ответы, используя тестовые данные.
Никаких платежей за использование тестовых данных не предусмотрено.

Для тестирования сервиса используйте следующие данные:
login: test
password: test
Вы можете отправить запрос только на следующие номера перевозочных средств:
Вагоны: 54676515
Контейнеры: AMFU8899067