JSON-API сервиса поиска вагонов: различия между версиями

Материал из Alta-Soft Wikipedia
Перейти к навигации Перейти к поиску
 
(не показано 13 промежуточных версий этого же участника)
Строка 1: Строка 1:
 
==О сервисе==
 
==О сервисе==
 
JSON-API сервиса «Поиск вагонов» позволяет интегрировать возможности сервиса в сторонние программы и сайты.
 
JSON-API сервиса «Поиск вагонов» позволяет интегрировать возможности сервиса в сторонние программы и сайты.
Посредством данного API можно выполнять оперативные запросы на поиск вагонов и контейнеров по жд сетям, ставить и снимать вагоны и контейнеры на слежение по СНГ, странам Балтии, Монголии и Китаю, а также запрашивать справки ГВЦ.
+
Посредством данного API можно ставить и снимать вагоны и контейнеры на слежение по СНГ, странам Балтии, Монголии и Китаю.
 
Сам интерфейс предоставляется бесплатно, тарифицируются только запросы, выполненные с его помощью согласно расценкам, опубликованным на сайте "Альта-Софт".
 
Сам интерфейс предоставляется бесплатно, тарифицируются только запросы, выполненные с его помощью согласно расценкам, опубликованным на сайте "Альта-Софт".
  
Строка 11: Строка 11:
 
Технический пароль можно получить в личном кабинете, в разделе управления договором, в пункте 'Технические настройки'<br>
 
Технический пароль можно получить в личном кабинете, в разделе управления договором, в пункте 'Технические настройки'<br>
 
Например, для пользователя с логином alta@alta.ru, сервис-аккаунтом sa000000 и техническим паролем alta_test:<br>
 
Например, для пользователя с логином alta@alta.ru, сервис-аккаунтом sa000000 и техническим паролем alta_test:<br>
Вычисляем секрет: secret = md5("rail_tracking:sa000000:md5('alta_test')") = 5ec1514f1b5a383fc5ad3f04bb9ac0e3 <br>
+
Вычисляем секрет: secret = md5("rail_tracking:sa000000:md5('alta_test')") = bb92dcee8bf2b49287e1038b65a72b79 <br>
  
 
Для выполнения любого запроса необходимо указать название метода (action) и авторизационные данные.<br>
 
Для выполнения любого запроса необходимо указать название метода (action) и авторизационные данные.<br>
 
Например, для проверки корректности генерации секрета необходимо выполнить запрос:
 
Например, для проверки корректности генерации секрета необходимо выполнить запрос:
https://www.alta.ru/rail_tracking/api_v2.php?action=test_secret&login=alta@alta.ru&sa=sa000000&secret=5ec1514f1b5a383fc5ad3f04bb9ac0e3
+
https://www.alta.ru/rail_tracking/api_v2.php?action=test_secret&login=alta@alta.ru&sa=sa000000&secret=bb92dcee8bf2b49287e1038b65a72b79
  
 
В json-ответе будет <code>{"status":"ok"}</code> в случае корректного секрета, в противном случае <code>{"status":"error"}</code>
 
В json-ответе будет <code>{"status":"ok"}</code> в случае корректного секрета, в противном случае <code>{"status":"error"}</code>
Строка 30: Строка 30:
  
 
Hash для получения ответов по вагонам:
 
Hash для получения ответов по вагонам:
- оперативный запрос 7e1019777173ff342ef500e31719572c <br>
 
 
  - слежение ebc356dfa5beee7d3844ccacf535410c <br>
 
  - слежение ebc356dfa5beee7d3844ccacf535410c <br>
 
Cont_hash для получения ответов по контейнерам:
 
Cont_hash для получения ответов по контейнерам:
- оперативный запрос fece39d1523836d03c3c2da73a6f1275 <br>
 
 
  - слежение 931700e35d7ff88a10bd5d680da50f02 <br>
 
  - слежение 931700e35d7ff88a10bd5d680da50f02 <br>
  
 
==Структура ответа и статус запроса==
 
==Структура ответа и статус запроса==
 +
Ответ на запроса для всех методов, за исключением test_secret, представляет из себя json-массив. Первый элемент массива - всегда статус запроса с текстовым описанием состояния или ошибки. В первом эелементе также может содержаться набор дополнительных необязательных полей в зависимости от вызываемого метода.<br>
 +
Последующие элементы - тело ответа, содержащие информацию о дислокации, список вагонов и проч.
  
 +
<source lang="json">
 +
[
 +
  {
 +
    "status": "ok",
 +
    "descr": "Запрос успешно сохранен"
 +
  }
 +
]
 +
</source>
  
==Выполнение оперативного (разового) запроса. Метод "add".==
+
или в случае ошибки ответ будет дополнен кодом ошибки Code (коды ошибок см. ниже)
Оперативный запрос выполняется единожды. Запрос в среднем обрабатывается в течение минуты. Тарифицируются только те запросы, по которым пришел ответ. Например, в запросе указано 6 вагонов, а ответ пришел только на 5. Значит с баланса спишется сумма за 5 вагонов.<br>
 
Ниже приводится полный список входных параметров:
 
 
 
{|  class="wikitable" width="75%"
 
|+
 
!Параметр !!Тип !!Описание
 
 
 
|- highlight
 
|colspan=3 |'''Обязательные'''
 
 
 
|-
 
|action||string||add - добавление оперативного запроса
 
 
 
|-
 
|login||string||Логин в сервисе. Например, alta@alta.ru
 
 
 
|-
 
|sa||string||Сервис-аккаунт (договор). Например, sa000000
 
 
 
|-
 
|secret||string||Сгенерированный секрет. Например 5ec1514f1b5a383fc5ad3f04bb9ac0e3
 
 
 
|-
 
|wagons||string||Список номеров вагонов/контейнеров через запятую. Например, "54676515,AMFU8899067"
 
 
 
|-
 
|state||string||Код страны, по которой осуществляется запрос. На данный момент оперативные запросы поддерживаются только по РФ. Код=20.
 
 
 
|-
 
|track_type||int||Тип слежения. Для оперативного запроса track_type=1
 
 
 
|- highlight
 
|colspan=3 |'''Необязательные'''
 
 
 
|-
 
|comment||string||Комментарий к запросу в urlencode
 
 
 
|-
 
|emails||string||Список email-адресов, куда отправить отчет о дислокации после выполнения, через запятую.
 
 
 
|-
 
|email_report_type||int||Всегда 2
 
 
 
|-
 
|attach_excel||int||Вкладывать ли в письма копию отчета в Excel. 1 - вкладывать, 0 - не вкладывать. По умолчанию 0.
 
 
 
|}
 
 
 
JSON-ответ включает в себя отчет о состоянии запроса (принят/не принят в обработку) и hash, по которому можно получить ответ.<br>
 
Например, на запрос вагона 54676515 и контейнера AMFU8899067 получим json-массив:
 
  
 
<source lang="json">
 
<source lang="json">
 
[
 
[
 
   {
 
   {
     "status": "ok",
+
     "status": "error",
     "descr": "Запрос успешно сохранен",
+
     "descr": "Указан неподдерживаемый метод",
     "hash": "7e1019777173ff342ef500e31719572c",
+
     "code": 15
    "group_id": 322,
 
    "cont_hash": "fece39d1523836d03c3c2da73a6f1275"
 
 
   }
 
   }
 
]
 
]
 
</source>
 
</source>
  
Следует учитывать, что в силу особенностей обработки запросов вагоны и контейнеры обрабатываются отдельно (обычно ответ на вагоны приходит быстрее). Поэтому в ответе может быть 2 хэша.<br>
 
  
 
Выходные параметры json-массива:
 
Выходные параметры json-массива:
Строка 131: Строка 86:
 
|}
 
|}
  
==Пример оперативного запроса==
+
==Постановка вагонов/контейнеров на слежение. Метод "add".==
Запрос дислокации вагона 54676515:<br>
+
Постановка на слежение выполняется с помощью метода "add". <br>
https://www.alta.ru/rail_tracking/api_v2.php?action=add&login=alta@alta.ru&sa=sa000000&secret=5ec1514f1b5a383fc5ad3f04bb9ac0e3&wagons=54676515&state=20&track_type=1&comment=%D0%BA%D0%B0%D0%BA%D0%BE%D0%B9-%D1%82%D0%BE%20%D0%BA%D0%BE%D0%BC%D0%BC%D0%B5%D0%BD%D1%82%D0%B0%D1%80%D0%B8%D0%B9<br>
 
В запросе можно комбинировать номера вагонов и контейнеров. <br>
 
Запрос дислокации вагона 54676515 и контейнера AMFU8899067: <br>
 
https://www.alta.ru/rail_tracking/api_v2.php?action=add&login=alta@alta.ru&sa=sa000000&secret=5ec1514f1b5a383fc5ad3f04bb9ac0e3&wagons=54676515,AMFU8899067&state=20&track_type=1&comment=%D0%BA%D0%B0%D0%BA%D0%BE%D0%B9-%D1%82%D0%BE%20%D0%BA%D0%BE%D0%BC%D0%BC%D0%B5%D0%BD%D1%82%D0%B0%D1%80%D0%B8%D0%B9
 
  
==Получение ответа на оперативный запрос. Метод "show". ==
+
Обращаем внимание, что в связи с особенностями работы системы слежения получение первого отчета с актуальными данными возможно не ранее 3-6 часов с момента постановкии на слежение (иногда до 12).
После размещения запроса он встает в очередь на обработку. Обычно обработка занимает около 1 минуты. В случае повышенной нагрузки на сервер обработка может занимать до 5 минут и более.
+
В противном случае могут прийти устаревшие данные (или не прийти вовсе). Особенно это характерно для контейнеров
Оптимальный период опроса сервера - 1 минута. В случае частых запросов ООО "Альта-Софт" оставляет за собой право заблокировать такие запросы и отказать в обслуживании.
+
Например:
 
+
На слежение был поставлен контейнер в начале рабочего дня в 09:00. Время обновления данных: 09:30, 14:30 и 17:30.
Ниже приводится полный список входных параметров:
+
В 09:30 этого же дня с высокой долей вероятности будут получены неактуальные (устаревшие) данные или данных не будет. В 14:30 и 17:30 будут получены уже актуализированные отчеты.
 +
Все последующие сутки актуальные отчеты будут приходить в любое из указанного в расписании время, т.е. и в 09:30 следующих суток уже придут свежие данные. <br/>
  
 +
Существует несколько регионов слежения: РФ, СНГ и Балтия, СНГ и Балтия + Китай + Монголия. Ниже описаны основные особенности:<br>
 +
- При слежении первый ответ (обновление) может формироваться довольно продолжительное время: от 3 часов по РФ до суток по странам Средней Азии и Китаю. 
 +
- В течение суток можно получить до 3-х обновлений дислокации за одну цену.
 +
- Стоимость слежения по РФ значительно ниже слежения по другим регионам. Однако, в случае пересечения перевозочного средства границы нет никаких гарантий, что свежая информация продолжит поступать.
 +
- Слежение по СНГ и Балтии, Китаю и Монголии позволяет получать дислокацию по всем перечисленным регионам, независимо от того, где находится ПС
 +
- При постановке ПС на слежение задается регламент получения отчетов - в какой день недели и какое время удобно получать свежую информацию, а также способ снятия со слежения (ручной или автоматический)
 +
- Существуют 2 типа слежения: посуточное и рейс. Единственное отличие между ними - в способе тарификации. Посуточное слежение - это такой тип слежения, когда денежные средства списываются со счета клиента при очередном формировании отчета (т.е. первом отчете за сутки согласно расписанию). Рейс тарифицируется сразу за весь маршрут при постановке на слежение и нет необходимости следить за состоянием баланса.
 +
- Для слежения информация по hash будет постоянно обновляться до окончания слежения.
 +
Ниже приводится полный список входных параметров. Жирным шрифтом отмечены те из них, значению которых следует уделить внимание при постановке на слежение:
 +
 
 
{|  class="wikitable" width="75%"
 
{|  class="wikitable" width="75%"
 
|+
 
|+
Строка 152: Строка 114:
  
 
|-
 
|-
|action||string||show - просмотр дислокации по заданному hash
+
|action||string||add - добавление запроса на слежение
  
 
|-
 
|-
Строка 161: Строка 123:
  
 
|-
 
|-
|secret||string||Сгенерированный секрет. Например 5ec1514f1b5a383fc5ad3f04bb9ac0e3
+
|secret||string||Сгенерированный секрет. Например bb92dcee8bf2b49287e1038b65a72b79
 +
 
 +
|-
 +
|wagons||string||Список номеров вагонов/контейнеров через запятую. Например, "54676515,AMFU8899067"
 +
 
 +
|-
 +
|<b>state</b>||string||Код страны, по которой осуществляется запрос. Для РФ, СНГ, Балтии, Монголии, Китая - 20.
 +
 
 +
|-
 +
|<b>track_state</b>||string||Регион слежения. ru - Россия, СНГ, Балтии, Монголия, Китай.
 +
 
 +
|-
 +
|<b>track_type</b>||int||Тип слежения. Для посуточного слежения запроса track_type=2, для рейса - track_type=3
 +
 
 +
|-
 +
|<b>stop_station</b>||string||Снимать ли со слежения по прибытию на станцию назначения. "yes" - снимать, "no" - не снимать. Если указать <код ЕСР> - снимать по прибытию на станцию с кодом <код ЕСР>. Код ЕСР - 5-и значный код станции согласно Единой Сетевой Разметке (ЕСР). 
 +
 
 +
|-
 +
|<b>times</b>||string||Время обновлений информации в сутки в рамках одной стоимости вагоно(контейнеро)/суток. Можно указать до 3-х раз. Формат: "H:i", через запятую. Например: "09:00,13:00,18:00". Время московское.
 +
 
 +
|-
 +
|<b>times_per_day</b>||string||Количество обновлений информации в сутки в рамках одной стоимости вагоно(контейнеро)/суток. Можно указать до 3-х раз. Если указано, что times меньше times_per_day, то times имеет больший приоритет. Например, times_per_day="2", a times="09:00,13:00,18:00", то отчет будет сформирован только в первое время и второе время, т.е. в 09:00 и в 13:00.
 +
 
 +
|-
 +
|<b>days</b>||string||Дни недели, по которым необходимо получать отчет, через запятую. Номера начинаются с нуля (Воскресенье) до 6 (Суббота). Например, если отчеты необходимы по будням, то days="1,2,3,4,5".
 +
 
 +
|- highlight
 +
|colspan=3 |'''Необязательные'''
 +
 
 +
|-
 +
|comment||string||Комментарий к запросу в urlencode
 +
 
 +
|-
 +
|emails||string||Список email-адресов, куда отправить отчет о дислокации после выполнения, через запятую.
  
 
|-
 
|-
|hash||string||Хэш запроса. Например, 7e1019777173ff342ef500e31719572c
+
|email_report_type||int||Всегда 2
 +
 
 +
|-
 +
|attach_excel||int||Вкладывать ли в письма копию отчета в Excel. 1 - вкладывать, 0 - не вкладывать. По умолчанию 0.
  
 
|}
 
|}
 +
 +
==Пример постановки на слежение==
 +
Контейнер AMFU8899067, получение инфорамции по будням дням (days=1,2,3,4,5) в 09:00 и 13:00 по московскому времени (times=09:00,13:00 и times_per_day=2), регион - только РФ (track_state=ru, state=20) без снятия со слежения по прибытии на станцию назначения (stop_station=no, т.е. ручное снятие), адреса для рассылки отчетов alta@alta.ru,mymail@mymail.com (emails=alta@alta.ru,mymail@mymail.com):<br>
 +
https://www.alta.ru/rail_tracking/api_v2.php?action=add&login=alta@alta.ru&sa=sa000000&secret=bb92dcee8bf2b49287e1038b65a72b79&wagons=AMFU8899067&state=20&track_type=2&comment=%D0%BF%D0%B5%D1%80%D0%B2%D0%BE%D0%B5+%D1%81%D0%BB%D0%B5%D0%B6%D0%B5%D0%BD%D0%B8%D0%B5+%28%D0%BA%D0%BE%D0%BD%D1%82%29&days=1,2,3,4,5&times_per_day=2&times=09:00,13:00&track_state=ru&stop_station=no&emails=alta@alta.ru,mymail@mymail.com
 +
<br>
 +
JSON-ответ включает в себя отчет о состоянии запроса на слежение (поставлен/не поставлен на слежение) и hash, по которому можно получить ответ.<br>
 +
 +
<source lang="json">
 +
[
 +
  {
 +
    "status": "ok",
 +
    "descr": "Запрос успешно сохранен",
 +
    "cont_hash": "931700e35d7ff88a10bd5d680da50f02"
 +
  }
 +
]
 +
</source>
 +
 +
При постановке вагона на слежение получим json-массив:
 +
 +
<source lang="json">
 +
[
 +
  {
 +
    "status": "ok",
 +
    "descr": "Запрос успешно сохранен",
 +
    "hash": "ebc356dfa5beee7d3844ccacf535410c"
 +
  }
 +
]
 +
</source>
 +
 +
Поля hash и cont_hash можно использовать для получения <b>текущей</b> дислокации (согласно расписанию).
 +
 +
==Получение ответа на ПС, стоящих на слежении. Метод "show". ==
 +
После размещения запроса он встает в очередь на обработку. В обозначенный момент времени (по расписанию) запрос выполняется. Обычно обработка запроса на слежение занимает около 1 минуты. В случае повышенной нагрузки на сервер обработка может занимать до 5 минут и более. <br>
 +
Оптимальный период опроса сервера - 1 минута. В случае частых запросов ООО "Альта-Софт" оставляет за собой право заблокировать такие запросы и отказать в обслуживании. <br>
 +
Для получение последней дислокации необходимо вызвать метод "show". <br><br>
 +
Например, для получения дислокации контейнера AMFU8899067: <br>
 +
https://www.alta.ru/rail_tracking/api_v2.php?action=show&login=alta@alta.ru&sa=sa000000&secret=bb92dcee8bf2b49287e1038b65a72b79&hash=931700e35d7ff88a10bd5d680da50f02
  
 
JSON-ответ включает в себя отчет о состоянии запроса (в очереди/обрабатывается/обработан) в первом элементе массива, в последующих элементах - отчет о дислокации перевозочных средств.
 
JSON-ответ включает в себя отчет о состоянии запроса (в очереди/обрабатывается/обработан) в первом элементе массива, в последующих элементах - отчет о дислокации перевозочных средств.
Строка 194: Строка 229:
 
     "departure_date": "2017-12-03 14:06:00",
 
     "departure_date": "2017-12-03 14:06:00",
 
     "route_start_date": "",
 
     "route_start_date": "",
 +
    "delivery_date": "2017-12-15 00:00:00",
 +
    "etd_date": "2017-12-20:00:00",
 
     "operation": "ПРИБЫТИЕ С ПОЕЗДОМ НА СТАНЦИЮ",
 
     "operation": "ПРИБЫТИЕ С ПОЕЗДОМ НА СТАНЦИЮ",
 
     "nakl_nom": "",
 
     "nakl_nom": "",
Строка 293: Строка 330:
 
|-
 
|-
 
|route_start_date||string||Дата начала рейса. Формат Y-m-d H:i:s". Время московское.
 
|route_start_date||string||Дата начала рейса. Формат Y-m-d H:i:s". Время московское.
 +
 +
|-
 +
|delivery_date||string||Ожидаемая дата прибытия на ст. назначения. Формат Y-m-d H:i:s". Время московское.
 +
 +
|-
 +
|etd_date||string||Ожидаемая дата доставки контейнера грузополучателю после раскредитовки. Формат Y-m-d H:i:s". Время московское.
  
 
|-
 
|-
Строка 342: Строка 385:
 
|is_loaded||int||1 - груженый, 0 - порожний
 
|is_loaded||int||1 - груженый, 0 - порожний
 
|-
 
|-
 +
 +
|sender_name||string||Наименование грузоотправителя
 +
|-
 +
 +
|rcpt_name||string||Наименование грузополучателя
 +
|-
 +
 +
|}
 +
 +
 +
==Снятие со слежения. Метод cancel_track.==
 +
 +
Ниже приводится полный список входных параметров:
 +
 +
{|  class="wikitable" width="75%"
 +
|+
 +
!Параметр !!Тип !!Описание
 +
 +
|- highlight
 +
|colspan=3 |'''Обязательные'''
 +
 +
|-
 +
|action||string||cancel_track - снятие со слежения запроса
 +
 +
|-
 +
|login||string||Логин в сервисе. Например, alta@alta.ru
 +
 +
|-
 +
|sa||string||Сервис-аккаунт (договор). Например, sa000000
 +
 +
|-
 +
|secret||string||Сгенерированный секрет. Например bb92dcee8bf2b49287e1038b65a72b79
 +
 +
|-
 +
|hash||string||Хэш запроса. Например, ebc356dfa5beee7d3844ccacf535410c
 +
 +
|- highlight
 +
|colspan=3 |'''Необязательные'''
 +
 +
|-
 +
|wagons||string||Список номеров вагонов/контейнеров через запятую. В случае указания списка со слежения будут сняты только те ПС, которые в нем указаны, а не весь запрос. Например, "54676515"
  
 
|}
 
|}
  
==Пример получения отчета на оперативный запрос.==
+
== Пример снятия со слежения==
 +
Снять со слежения вагон 54676515 из запроса с hash ebc356dfa5beee7d3844ccacf535410c<br>
 +
https://www.alta.ru/rail_tracking/api_v2.php?action=cancel_track&login=alta@alta.ru&sa=sa000000&secret=bb92dcee8bf2b49287e1038b65a72b79&hash=ebc356dfa5beee7d3844ccacf535410c&wagons=54676515
  
Получить отчет по вагону 54676515 по hash=7e1019777173ff342ef500e31719572c:<br>
+
Снять со слежения '''весь''' (т.е. все перевозочные средства из запроса) запрос с hash 931700e35d7ff88a10bd5d680da50f02<br>
https://www.alta.ru/rail_tracking/api_v2.php?action=show&login=alta@alta.ru&sa=sa000000&secret=5ec1514f1b5a383fc5ad3f04bb9ac0e3&hash=7e1019777173ff342ef500e31719572c
+
https://www.alta.ru/rail_tracking/api_v2.php?action=cancel_track&login=alta@alta.ru&sa=sa000000&secret=bb92dcee8bf2b49287e1038b65a72b79&hash=931700e35d7ff88a10bd5d680da50f02
 +
 
 +
Обратите внимание, что для тестовых данных ответ на запрос снятия со слежения будет "успешно", однако фактически запросы останутся на слежении.
 +
 
 +
== Получение списка запросов на слежении. Метод "track_list". ==
 +
Ниже приводится полный список входных параметров:
  
==Постановка вагонов/контейнеров на слежение. Метод "add" с доп. параметрами.==
 
Постановка на слежение аналогично оперативному запросу, т.е. выполняется с помощью метода "add". Существенное различие в дополнительных параметрах, их значениях и поведении системы при слежении.<br>
 
Существует несколько регионов слежения: РФ, СНГ и Балтия, СНГ и Балтия + Китай + Монголия. Ниже описаны основные отличия и особенности:<br>
 
- Основное отличие от оперативного запроса - во времени отклика системы. Если выполнив оперативный запрос ответ будет получен в течение минуты (в среднем), то при слежении ответ может формироваться довольно продолжительное время: от 10 минут по РФ до нескольких часов по странам Средней Азии и Китаю. 
 
- В течение суток можно получить до 3-х обновлений дислокации за одну цену, в то время как <b>каждый</b> оперативный запрос тарифицируется.
 
- Стоимость слежения по РФ значительно ниже слежения по другим регионам. Однако, в случае пересечения перевозочного средства границы нет никаких гарантий, что свежая информация продолжит поступать.
 
- Слежение по СНГ и Балтии, Китаю и Монголии позволяет получать дислокацию по всем перечисленным регионам, независимо от того, где находится ПС
 
- При постановке ПС на слежение задается регламент получения отчетов - в какой день недели и какое время удобно получать свежую информацию, а также способ снятия со слежения (ручной или автоматический)
 
- Существуют 2 типа слежения: посуточное и рейс. Единственное отличие между ними - в способе тарификации. Посуточное слежение - это такой тип слежения, когда денежные средства списываются со счета клиента при очередном формировании отчета (т.е. первом отчете за сутки согласно расписанию). Рейс тарифицируется сразу за весь маршрут при постановке на слежение и нет необходимости следить за состоянием баланса.
 
- По hash оперативного запроса не идет обновление информации, т.е. информация о дислокации актуальна только на момент получения ответа. Для слежения информация по hash будет постоянно обновляться до окончания слежения.
 
Ниже приводится полный список входных параметров. Жирным шрифтом отмечены те из них, которых или нет в оперативном запросе, или их значению следует уделить внимание при постановке на слежение:
 
 
 
 
{|  class="wikitable" width="75%"
 
{|  class="wikitable" width="75%"
 
|+
 
|+
Строка 370: Строка 449:
  
 
|-
 
|-
|action||string||add - добавление оперативного запроса
+
|action||string||track_list - список запросов, стоящих на слежении
  
 
|-
 
|-
Строка 379: Строка 458:
  
 
|-
 
|-
|secret||string||Сгенерированный секрет. Например 5ec1514f1b5a383fc5ad3f04bb9ac0e3
+
|secret||string||Сгенерированный секрет. Например bb92dcee8bf2b49287e1038b65a72b79
 +
 
 +
|}
 +
Например: <br>
 +
https://www.alta.ru/rail_tracking/api_v2.php?action=track_list&login=alta@alta.ru&sa=sa000000&secret=bb92dcee8bf2b49287e1038b65a72b79
 +
 
 +
Json-ответ:
 +
 
 +
<source lang="json">
 +
[
 +
  {
 +
    "status": "ok"
 +
  },
 +
  {
 +
    "name": "первое слежение",
 +
    "comment": null,
 +
    "vagon_count": "1",
 +
    "email": "",
 +
    "phone": "",
 +
    "hash": "ebc356dfa5beee7d3844ccacf535410c",
 +
    "modify_date": "29.07.2021 21:52",
 +
    "on_track": "1",
 +
    "track_type": "1",
 +
    "state": "20",
 +
    "track_state": "ru",
 +
    "status": 4,
 +
    "type": "group"
 +
  },
 +
  {
 +
    "name": "первое слежение (конт)",
 +
    "comment": null,
 +
    "vagon_count": "1",
 +
    "email": "",
 +
    "phone": "",
 +
    "hash": "931700e35d7ff88a10bd5d680da50f02",
 +
    "modify_date": "03.08.2021 13:10",
 +
    "on_track": "1",
 +
    "track_type": "1",
 +
    "state": "20",
 +
    "track_state": "ru",
 +
    "status": 4,
 +
    "type": "group"
 +
  }
 +
]
 +
</source>
 +
 
 +
Выходные поля json-массива:
 +
 
 +
{|  class="wikitable" width="75%"
 +
|+
 +
!Поле !!Тип !!Описание
 +
 
 +
|- highlight
 +
|colspan=3 |'''Обязательные'''
 +
 
 +
|- highlight
 +
|colspan=3 |'''1-й элемент'''
 +
 
 +
|-
 +
|status||string||ok - при успешном получении данных, error или fail - при ошибке. Список кодов ошибок см. ниже.
 +
 
 +
 
 +
|- highlight
 +
|colspan=3 |'''Последующие эелементы'''
 +
 
 +
|-
 +
|comment||string||Комментарий к запросу
  
 
|-
 
|-
|wagons||string||Список номеров вагонов/контейнеров через запятую. Например, "54676515,AMFU8899067"
+
|vagon_count||string||Количество ПС в запросе
 +
 
 +
|-
 +
|email||string||Адреса электронной почты для рассылки отчетов о дислокации, через запятую.
  
 
|-
 
|-
|<b>state</b>||string||Код страны, по которой осуществляется запрос. Для РФ - 20. По странам СНГ и Балтии, Монголии, Китаю - 22.
+
|hash||string||Hash запроса.
  
 
|-
 
|-
|<b>track_state</b>||string||Регион слежения. ru - только Россия, sng - страны СНГ, Балтии, Монголия, Китай.
+
|modify_date||string||Дата последнего изменения/выполнения запроса.
  
 
|-
 
|-
|<b>track_type</b>||int||Тип слежения. Для посуточного слежения запроса track_type=2, для рейса - track_type=3
+
|on_track||string||Стоит ли запрос на слежении. 1 - стоит, 0 - снят.
  
 
|-
 
|-
|<b>stop_station</b>||string||Снимать ли со слежения по прибытию на станцию назначения. "yes" - снимать, "no" - не снимать. Если указать <код ЕСР> - снимать по прибытию на станцию с кодом <код ЕСР>. Код ЕСР - 5-и значный код станции согласно Единой Сетевой Разметке (ЕСР). 
+
|track_type||string||Тип слежения. 1 - постоянное, 2 - рейс. Обратите внимание, нумерация в данном случае отличае от таковой при постановке на слежение./
  
 
|-
 
|-
|<b>times</b>||string||Время обновлений информации в сутки в рамках одной стоимости вагоно(контейнеро)/суток. Можно указать до 3-х раз. Формат: "H:i", через запятую. Например: "09:00,13:00,18:00". Время московское.  
+
|track_state||string||Регион слежения. ru - только РФ, sng - страны СНГ, Балтии, Монголия, Китай.
  
 
|-
 
|-
|<b>times_per_day</b>||string||Количество обновлений информации в сутки в рамках одной стоимости вагоно(контейнеро)/суток. Можно указать до 3-х раз. Если указано, что times меньше times_per_day, то times имеет больший приоритет. Например, times_per_day="2", a times="09:00,13:00,18:00", то отчет будет сформирован только в первое время и второе время, т.е. в 09:00 и в 13:00.
+
|state||string||Государство слежения. 20 - РФ, 22 - страны СНГ, Балтии, Монголия, Китай.
  
 
|-
 
|-
|<b>days</b>||string||Дни недели, по которым необходимо получать отчет, через запятую. Номера начинаются с нуля (Воскресенье) до 6 (Суббота). Например, если отчеты необходимы по будням, то days="1,2,3,4,5".  
+
|status||int||Статус обработки запроса. 1 - в очереди на обработку, 2 - обрабатывается, 3,4 - обработан
 +
 
 +
|}
 +
 
 +
== Получение списка ПС в запросе. Метод "carr_list". ==
 +
Ниже приводится полный список входных параметров:
 +
 
 +
{|  class="wikitable" width="75%"
 +
|+
 +
!Параметр !!Тип !!Описание
  
 
|- highlight
 
|- highlight
|colspan=3 |'''Необязательные'''
+
|colspan=3 |'''Обязательные'''
 +
 
 +
|-
 +
|action||string||carr_list - список номеров перевозочных средств в запросе
  
 
|-
 
|-
|comment||string||Комментарий к запросу в urlencode
+
|login||string||Логин в сервисе. Например, alta@alta.ru
  
 
|-
 
|-
|emails||string||Список email-адресов, куда отправить отчет о дислокации после выполнения, через запятую.
+
|sa||string||Сервис-аккаунт (договор). Например, sa000000
  
 
|-
 
|-
|email_report_type||int||Всегда 2
+
|secret||string||Сгенерированный секрет. Например bb92dcee8bf2b49287e1038b65a72b79
  
 
|-
 
|-
|attach_excel||int||Вкладывать ли в письма копию отчета в Excel. 1 - вкладывать, 0 - не вкладывать. По умолчанию 0.
+
|hash||string||Хэш запроса. Например 931700e35d7ff88a10bd5d680da50f02
 +
 
  
 
|}
 
|}
 +
Например: <br>
 +
https://www.alta.ru/rail_tracking/api_v2.php?action=carr_list&login=alta@alta.ru&sa=sa000000&secret=bb92dcee8bf2b49287e1038b65a72b79&hash=931700e35d7ff88a10bd5d680da50f02
  
==Пример постановки на слежение==
+
Json-ответ:
Контейнер AMFU8899067, получение инфорамции по будням дням (days=1,2,3,4,5) в 09:00 и 13:00 по московскому времени (times=09:00,13:00 и times_per_day=2), регион - только РФ (track_state=ru, state=20) без снятия со слежения по прибытии на станцию назначения (stop_station=no, т.е. ручное снятие), адреса для рассылки отчетов alta@alta.ru,mymail@mymail.com (emails=alta@alta.ru,mymail@mymail.com):<br>
 
https://www.alta.ru/rail_tracking/api_v2.php?action=add&login=alta@alta.ru&sa=sa000000&secret=5ec1514f1b5a383fc5ad3f04bb9ac0e3&wagons=AMFU8899067&state=20&track_type=2&comment=первое слежение (конт)&days=1,2,3,4,5&times_per_day=2&times=09:00,13:00&track_state=ru&stop_station=no&emails=alta@alta.ru,mymail@mymail.com
 
<br>
 
JSON-ответ включает в себя отчет о состоянии запроса на слежение (поставлен/не поставлен на слежение) и hash, по которому можно получить ответ.<br>
 
  
 
<source lang="json">
 
<source lang="json">
 
[
 
[
 
   {
 
   {
     "status": "ok",
+
     "status": "ok"
     "descr": "Запрос успешно сохранен",
+
  },
     "cont_hash": "931700e35d7ff88a10bd5d680da50f02"
+
  {
 +
     "group_id": 1519743,
 +
     "carrs": [
 +
      "AMFU8899067"
 +
    ]
 
   }
 
   }
 
]
 
]
 
</source>
 
</source>
  
При постановке вагона на слежение получим json-массив:
+
Выходные поля json-массива:
 +
 
 +
{|  class="wikitable" width="75%"
 +
|+
 +
!Поле !!Тип !!Описание
 +
 
 +
|- highlight
 +
|colspan=3 |'''Обязательные'''
 +
 
 +
|- highlight
 +
|colspan=3 |'''1-й элемент'''
 +
 
 +
|-
 +
|status||string||ok - при успешном получении данных, error или fail - при ошибке. Список кодов ошибок см. ниже.
 +
 
 +
 
 +
|- highlight
 +
|colspan=3 |'''Последующие эелементы'''
 +
 
 +
|-
 +
|carrs||string||Массив номеров перевозочных средств в запросе
 +
 
 +
|}
 +
 
 +
== Получение баланса. Метод "balance"==
 +
Ниже приводится полный список входных параметров:
 +
 
 +
{|  class="wikitable" width="75%"
 +
|+
 +
!Параметр !!Тип !!Описание
 +
 
 +
|- highlight
 +
|colspan=3 |'''Обязательные'''
 +
 
 +
|-
 +
|action||string||balance - остаток денежных средств или бонусов на счету
 +
 
 +
|-
 +
|login||string||Логин в сервисе. Например, alta@alta.ru
 +
 
 +
|-
 +
|sa||string||Сервис-аккаунт (договор). Например, sa000000
 +
 
 +
|-
 +
|secret||string||Сгенерированный секрет. Например bb92dcee8bf2b49287e1038b65a72b79
 +
 
 +
|}
 +
Например: <br>
 +
https://www.alta.ru/rail_tracking/api_v2.php?action=balance&login=alta@alta.ru&sa=sa000000&secret=bb92dcee8bf2b49287e1038b65a72b79
  
 +
Json-ответ
 
<source lang="json">
 
<source lang="json">
 
[
 
[
 
   {
 
   {
 
     "status": "ok",
 
     "status": "ok",
     "descr": "Запрос успешно сохранен",
+
     "descr": "Ваш баланс: 0.00 руб. / Бонусы 0",
     "hash": "ebc356dfa5beee7d3844ccacf535410c"
+
    "balans": "0.00",
 +
    "bonus": 0,
 +
     "sa": "sa000000"
 
   }
 
   }
 
]
 
]
 
</source>
 
</source>
  
Поля hash и cont_hash аналогичны таковым для оперативного запроса. Однако, их можно использовать для получения <b>текущей</b> дислокации (согласно расписанию).
+
Выходные поля json-массива:
 +
 
 +
{|  class="wikitable" width="75%"
 +
|+
 +
!Поле !!Тип !!Описание
  
==Получение ответа на ПС, стоящих на слежении. Метод "show". ==
+
|- highlight
После размещения запроса он встает в очередь на обработку. В обозначенный момент времени (по расписанию) запрос выполняется. Обычно обработка запроса на слежение занимает около 1 минуты. В случае повышенной нагрузки на сервер обработка может занимать до 5 минут и более. <br>
+
|colspan=3 |'''Обязательные'''
Оптимальный период опроса сервера - 1 минута. В случае частых запросов ООО "Альта-Софт" оставляет за собой право заблокировать такие запросы и отказать в обслуживании. <br>
+
 
Для получение последней дислокации необходимо вызвать метод "show", полностью аналогичный таковому для оперативного запроса. <br>
+
|- highlight
Например, для получения дислокации контейнера AMFU8899067: <br>
+
|colspan=3 |'''1-й элемент'''
https://www.alta.ru/rail_tracking/api_v2.php?action=show&login=alta@alta.ru&sa=sa000000&secret=5ec1514f1b5a383fc5ad3f04bb9ac0e3&hash=931700e35d7ff88a10bd5d680da50f02
+
 
 +
|-
 +
|status||string||ok - при успешном получении данных, error или fail - при ошибке. Список кодов ошибок см. ниже.
 +
 
 +
|-
 +
|descr||string||Остаток денежных средств/бонусов в текстовом виде
 +
 
 +
|-
 +
|balans||string||Остаток денежных средств в рублях
 +
 
 +
|-
 +
|bonus||string||Остаток бонусов
 +
 
 +
|-
 +
|sa||string||Номер договора (сервис-аккаунта)
  
==Снятие со слежения. ==
+
|}

Текущая версия на 11:37, 11 апреля 2023

О сервисе

JSON-API сервиса «Поиск вагонов» позволяет интегрировать возможности сервиса в сторонние программы и сайты. Посредством данного API можно ставить и снимать вагоны и контейнеры на слежение по СНГ, странам Балтии, Монголии и Китаю. Сам интерфейс предоставляется бесплатно, тарифицируются только запросы, выполненные с его помощью согласно расценкам, опубликованным на сайте "Альта-Софт".

API. Авторизация. Метод "test_secret".

Доступ к API предоставляется по URL https://www.alta.ru/rail_tracking/api_v2.php. Входные параметры передаются с помощью запроса HTTP GET или POST. Для использования сервиса необходима авторизация с помощью сервисного логина и пароля.

Для авторизации необходимо в любой запрос добавить логин в открытом виде, сервис-аккаунт (номер договора для тарификации) и MD5-хеш от сгенерированной строки символьное обозначения сервиса + сервис-аккаунт + технический пароль, разделенный знаком двоеточия «:».
Символьное обозначение сервиса для поиска вагонов - всегда rail_tracking.
Технический пароль можно получить в личном кабинете, в разделе управления договором, в пункте 'Технические настройки'
Например, для пользователя с логином alta@alta.ru, сервис-аккаунтом sa000000 и техническим паролем alta_test:
Вычисляем секрет: secret = md5("rail_tracking:sa000000:md5('alta_test')") = bb92dcee8bf2b49287e1038b65a72b79

Для выполнения любого запроса необходимо указать название метода (action) и авторизационные данные.
Например, для проверки корректности генерации секрета необходимо выполнить запрос: https://www.alta.ru/rail_tracking/api_v2.php?action=test_secret&login=alta@alta.ru&sa=sa000000&secret=bb92dcee8bf2b49287e1038b65a72b79

В json-ответе будет {"status":"ok"} в случае корректного секрета, в противном случае {"status":"error"}

Тестирование JSON-API

Для тестирования сервиса используйте следующие авторизационные данные:
Логин: alta@alta.ru
Технический пароль: alta_test
Сервис-аккаунт (договор): sa000000

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

Hash для получения ответов по вагонам:

- слежение ebc356dfa5beee7d3844ccacf535410c 

Cont_hash для получения ответов по контейнерам:

- слежение 931700e35d7ff88a10bd5d680da50f02 

Структура ответа и статус запроса

Ответ на запроса для всех методов, за исключением test_secret, представляет из себя json-массив. Первый элемент массива - всегда статус запроса с текстовым описанием состояния или ошибки. В первом эелементе также может содержаться набор дополнительных необязательных полей в зависимости от вызываемого метода.
Последующие элементы - тело ответа, содержащие информацию о дислокации, список вагонов и проч.

[
  {
    "status": "ok",
    "descr": "Запрос успешно сохранен"
  }
]

или в случае ошибки ответ будет дополнен кодом ошибки Code (коды ошибок см. ниже)

[
  {
    "status": "error",
    "descr": "Указан неподдерживаемый метод",
    "code": 15
  }
]


Выходные параметры json-массива:

Параметр Тип Описание
Обязательные
status string ok - при успешном размещении запроса, error или fail - при ошибке. Список кодов ошибок см. ниже.
descr string Текстовое описание состояния или ошибки
Необязательные
hash string Хэш запроса по вагонам (если они были в запросе)
cont_hash string Хэш запроса по контейнерам (если они были в запросе)

Постановка вагонов/контейнеров на слежение. Метод "add".

Постановка на слежение выполняется с помощью метода "add".

Обращаем внимание, что в связи с особенностями работы системы слежения получение первого отчета с актуальными данными возможно не ранее 3-6 часов с момента постановкии на слежение (иногда до 12). В противном случае могут прийти устаревшие данные (или не прийти вовсе). Особенно это характерно для контейнеров Например: На слежение был поставлен контейнер в начале рабочего дня в 09:00. Время обновления данных: 09:30, 14:30 и 17:30. В 09:30 этого же дня с высокой долей вероятности будут получены неактуальные (устаревшие) данные или данных не будет. В 14:30 и 17:30 будут получены уже актуализированные отчеты. Все последующие сутки актуальные отчеты будут приходить в любое из указанного в расписании время, т.е. и в 09:30 следующих суток уже придут свежие данные.

Существует несколько регионов слежения: РФ, СНГ и Балтия, СНГ и Балтия + Китай + Монголия. Ниже описаны основные особенности:

- При слежении первый ответ (обновление) может формироваться довольно продолжительное время: от 3 часов по РФ до суток по странам Средней Азии и Китаю.  
- В течение суток можно получить до 3-х обновлений дислокации за одну цену.
- Стоимость слежения по РФ значительно ниже слежения по другим регионам. Однако, в случае пересечения перевозочного средства границы нет никаких гарантий, что свежая информация продолжит поступать.
- Слежение по СНГ и Балтии, Китаю и Монголии позволяет получать дислокацию по всем перечисленным регионам, независимо от того, где находится ПС
- При постановке ПС на слежение задается регламент получения отчетов - в какой день недели и какое время удобно получать свежую информацию, а также способ снятия со слежения (ручной или автоматический)
- Существуют 2 типа слежения: посуточное и рейс. Единственное отличие между ними - в способе тарификации. Посуточное слежение - это такой тип слежения, когда денежные средства списываются со счета клиента при очередном формировании отчета (т.е. первом отчете за сутки согласно расписанию). Рейс тарифицируется сразу за весь маршрут при постановке на слежение и нет необходимости следить за состоянием баланса.
- Для слежения информация по hash будет постоянно обновляться до окончания слежения. 

Ниже приводится полный список входных параметров. Жирным шрифтом отмечены те из них, значению которых следует уделить внимание при постановке на слежение:

Параметр Тип Описание
Обязательные
action string add - добавление запроса на слежение
login string Логин в сервисе. Например, alta@alta.ru
sa string Сервис-аккаунт (договор). Например, sa000000
secret string Сгенерированный секрет. Например bb92dcee8bf2b49287e1038b65a72b79
wagons string Список номеров вагонов/контейнеров через запятую. Например, "54676515,AMFU8899067"
state string Код страны, по которой осуществляется запрос. Для РФ, СНГ, Балтии, Монголии, Китая - 20.
track_state string Регион слежения. ru - Россия, СНГ, Балтии, Монголия, Китай.
track_type int Тип слежения. Для посуточного слежения запроса track_type=2, для рейса - track_type=3
stop_station string Снимать ли со слежения по прибытию на станцию назначения. "yes" - снимать, "no" - не снимать. Если указать <код ЕСР> - снимать по прибытию на станцию с кодом <код ЕСР>. Код ЕСР - 5-и значный код станции согласно Единой Сетевой Разметке (ЕСР).
times string Время обновлений информации в сутки в рамках одной стоимости вагоно(контейнеро)/суток. Можно указать до 3-х раз. Формат: "H:i", через запятую. Например: "09:00,13:00,18:00". Время московское.
times_per_day string Количество обновлений информации в сутки в рамках одной стоимости вагоно(контейнеро)/суток. Можно указать до 3-х раз. Если указано, что times меньше times_per_day, то times имеет больший приоритет. Например, times_per_day="2", a times="09:00,13:00,18:00", то отчет будет сформирован только в первое время и второе время, т.е. в 09:00 и в 13:00.
days string Дни недели, по которым необходимо получать отчет, через запятую. Номера начинаются с нуля (Воскресенье) до 6 (Суббота). Например, если отчеты необходимы по будням, то days="1,2,3,4,5".
Необязательные
comment string Комментарий к запросу в urlencode
emails string Список email-адресов, куда отправить отчет о дислокации после выполнения, через запятую.
email_report_type int Всегда 2
attach_excel int Вкладывать ли в письма копию отчета в Excel. 1 - вкладывать, 0 - не вкладывать. По умолчанию 0.

Пример постановки на слежение

Контейнер AMFU8899067, получение инфорамции по будням дням (days=1,2,3,4,5) в 09:00 и 13:00 по московскому времени (times=09:00,13:00 и times_per_day=2), регион - только РФ (track_state=ru, state=20) без снятия со слежения по прибытии на станцию назначения (stop_station=no, т.е. ручное снятие), адреса для рассылки отчетов alta@alta.ru,mymail@mymail.com (emails=alta@alta.ru,mymail@mymail.com):
https://www.alta.ru/rail_tracking/api_v2.php?action=add&login=alta@alta.ru&sa=sa000000&secret=bb92dcee8bf2b49287e1038b65a72b79&wagons=AMFU8899067&state=20&track_type=2&comment=%D0%BF%D0%B5%D1%80%D0%B2%D0%BE%D0%B5+%D1%81%D0%BB%D0%B5%D0%B6%D0%B5%D0%BD%D0%B8%D0%B5+%28%D0%BA%D0%BE%D0%BD%D1%82%29&days=1,2,3,4,5&times_per_day=2&times=09:00,13:00&track_state=ru&stop_station=no&emails=alta@alta.ru,mymail@mymail.com
JSON-ответ включает в себя отчет о состоянии запроса на слежение (поставлен/не поставлен на слежение) и hash, по которому можно получить ответ.

[
  {
    "status": "ok",
    "descr": "Запрос успешно сохранен",
    "cont_hash": "931700e35d7ff88a10bd5d680da50f02"
  }
]

При постановке вагона на слежение получим json-массив:

[
  {
    "status": "ok",
    "descr": "Запрос успешно сохранен",
    "hash": "ebc356dfa5beee7d3844ccacf535410c"
  }
]

Поля hash и cont_hash можно использовать для получения текущей дислокации (согласно расписанию).

Получение ответа на ПС, стоящих на слежении. Метод "show".

После размещения запроса он встает в очередь на обработку. В обозначенный момент времени (по расписанию) запрос выполняется. Обычно обработка запроса на слежение занимает около 1 минуты. В случае повышенной нагрузки на сервер обработка может занимать до 5 минут и более.
Оптимальный период опроса сервера - 1 минута. В случае частых запросов ООО "Альта-Софт" оставляет за собой право заблокировать такие запросы и отказать в обслуживании.
Для получение последней дислокации необходимо вызвать метод "show".

Например, для получения дислокации контейнера AMFU8899067:
https://www.alta.ru/rail_tracking/api_v2.php?action=show&login=alta@alta.ru&sa=sa000000&secret=bb92dcee8bf2b49287e1038b65a72b79&hash=931700e35d7ff88a10bd5d680da50f02

JSON-ответ включает в себя отчет о состоянии запроса (в очереди/обрабатывается/обработан) в первом элементе массива, в последующих элементах - отчет о дислокации перевозочных средств. Например, на запрос AMFU8899067 получим json-массив:

[
  {
    "status": "ok",
    "descr": "Обработан",
    "query_status": "4",
    "hash": "fece39d1523836d03c3c2da73a6f1275",
    "type": "2",
    "count": 1
  },
  {
    "num": "AMFU8899067",
    "on_track": 0,
    "station": "24160",
    "station_name": "Вековка",
    "state": "20",
    "state_name": "Россия",
    "lon": "40.764762",
    "lat": "55.498762",
    "road_name": "Горьковская",
    "op_date": "2017-12-05 20:03:00",
    "departure_date": "2017-12-03 14:06:00",
    "route_start_date": "",
    "delivery_date": "2017-12-15 00:00:00",
    "etd_date": "2017-12-20:00:00",
    "operation": "ПРИБЫТИЕ С ПОЕЗДОМ НА СТАНЦИЮ",
    "nakl_nom": "",
    "okpo": "94421386",
    "owner": null,
    "kgro": "1386",
    "kgrp": "7575",
    "train_index": "18290-853-98130",
    "train_number": "1282",
    "fraight": "51403",
    "fraight_name": "Изделия кондитерские сахаристые, н.п.",
    "weight": "13000",
    "wagon_number": "94785045",
    "station_from": "18290",
    "is_loaded": 1,
    "hash": "ea7a000c4649388f68af14051f0827a04f11a2ee",
    "station_to": "98130",
    "station_from_name": "Тучково",
    "station_to_name": "Первая Речка",
    "route": "8928"
  }
]

Выходные поля json-массива:

Поле Тип Описание
Обязательные
1-й элемент
status string ok - при успешном получении данных, error или fail - при ошибке. Список кодов ошибок см. ниже.
descr string Текстовое описание состояния или ошибки
type string Тип запроса. 1- вагоны, 2 - контейнеры
query_status string Состояние запроса. 1 - в очереди, 2 - обрабатывается, 3 или 4 - обработан
count int Количество перевозочных средств в отчете
hash string Хэш запроса.
Последующие эелементы (при query_status больше 2)
num string Номер перевозочного средства
station string Код станции, где была зафиксирована последняя операция с перевозочным средством. 5 символов(или 6 символов, 6-й - контрольный знак). В случае отсутствия данных по дислокации ПС значение будет "no_data".
station_name string Название станции, где была зафиксирована последняя операция с перевозочным средством.
op_date string Дата фиксирования последней операции. В формате "Y-m-d H:i:s". Время московское.
operation string Наименование последней операции
route string Оставшееся до станции назначения расстояние, км
on_track int Стоит ли перевозочное средство на слежении. 1 - стоит, 0 - снят или оперативный запрос
Необязательные
state string Код государства станции, где была зафиксирована последняя операция
state_name string Название государства станции, где была зафиксирована последняя операция
lon string Долгота станции, где была зафиксирована последняя операция
lat string Широта станции, где была зафиксирована последняя операция
road_name string Дорога, где была зафиксирована последняя операция
departure_date string Дата отправки. Формат Y-m-d H:i:s". Время московское.
route_start_date string Дата начала рейса. Формат Y-m-d H:i:s". Время московское.
delivery_date string Ожидаемая дата прибытия на ст. назначения. Формат Y-m-d H:i:s". Время московское.
etd_date string Ожидаемая дата доставки контейнера грузополучателю после раскредитовки. Формат Y-m-d H:i:s". Время московское.
nakl_nom string Номер накладной
okpo string ОКПО отправителя
owner string Собственник перевозочного средства
kgro string Номер грузоотправителя
kgrp string Номер грузополучателя
train_index string Индекс поезда
train_number string Номер поезда
fraight string Код груза по номенклатуре ЕТСНГ
fraight_name string Наименование груза
weight string Вес груза (чаще всего в килограммах, но может быть в центнерах или тоннах)
wagon_number string Номер вагона (платформы), на котором закреплен контейнер (только для контейнерных запросов)
station_from string Код станции отправления
station_from_name string Название станции отправления
station_to string Код станции назначения
station_to_name string Название станции назначения
is_loaded int 1 - груженый, 0 - порожний
sender_name string Наименование грузоотправителя
rcpt_name string Наименование грузополучателя


Снятие со слежения. Метод cancel_track.

Ниже приводится полный список входных параметров:

Параметр Тип Описание
Обязательные
action string cancel_track - снятие со слежения запроса
login string Логин в сервисе. Например, alta@alta.ru
sa string Сервис-аккаунт (договор). Например, sa000000
secret string Сгенерированный секрет. Например bb92dcee8bf2b49287e1038b65a72b79
hash string Хэш запроса. Например, ebc356dfa5beee7d3844ccacf535410c
Необязательные
wagons string Список номеров вагонов/контейнеров через запятую. В случае указания списка со слежения будут сняты только те ПС, которые в нем указаны, а не весь запрос. Например, "54676515"

Пример снятия со слежения

Снять со слежения вагон 54676515 из запроса с hash ebc356dfa5beee7d3844ccacf535410c
https://www.alta.ru/rail_tracking/api_v2.php?action=cancel_track&login=alta@alta.ru&sa=sa000000&secret=bb92dcee8bf2b49287e1038b65a72b79&hash=ebc356dfa5beee7d3844ccacf535410c&wagons=54676515

Снять со слежения весь (т.е. все перевозочные средства из запроса) запрос с hash 931700e35d7ff88a10bd5d680da50f02
https://www.alta.ru/rail_tracking/api_v2.php?action=cancel_track&login=alta@alta.ru&sa=sa000000&secret=bb92dcee8bf2b49287e1038b65a72b79&hash=931700e35d7ff88a10bd5d680da50f02

Обратите внимание, что для тестовых данных ответ на запрос снятия со слежения будет "успешно", однако фактически запросы останутся на слежении.

Получение списка запросов на слежении. Метод "track_list".

Ниже приводится полный список входных параметров:

Параметр Тип Описание
Обязательные
action string track_list - список запросов, стоящих на слежении
login string Логин в сервисе. Например, alta@alta.ru
sa string Сервис-аккаунт (договор). Например, sa000000
secret string Сгенерированный секрет. Например bb92dcee8bf2b49287e1038b65a72b79

Например:
https://www.alta.ru/rail_tracking/api_v2.php?action=track_list&login=alta@alta.ru&sa=sa000000&secret=bb92dcee8bf2b49287e1038b65a72b79

Json-ответ:

[
  {
    "status": "ok"
  },
  {
    "name": "первое слежение",
    "comment": null,
    "vagon_count": "1",
    "email": "",
    "phone": "",
    "hash": "ebc356dfa5beee7d3844ccacf535410c",
    "modify_date": "29.07.2021 21:52",
    "on_track": "1",
    "track_type": "1",
    "state": "20",
    "track_state": "ru",
    "status": 4,
    "type": "group"
  },
  {
    "name": "первое слежение (конт)",
    "comment": null,
    "vagon_count": "1",
    "email": "",
    "phone": "",
    "hash": "931700e35d7ff88a10bd5d680da50f02",
    "modify_date": "03.08.2021 13:10",
    "on_track": "1",
    "track_type": "1",
    "state": "20",
    "track_state": "ru",
    "status": 4,
    "type": "group"
  }
]

Выходные поля json-массива:

Поле Тип Описание
Обязательные
1-й элемент
status string ok - при успешном получении данных, error или fail - при ошибке. Список кодов ошибок см. ниже.


Последующие эелементы
comment string Комментарий к запросу
vagon_count string Количество ПС в запросе
email string Адреса электронной почты для рассылки отчетов о дислокации, через запятую.
hash string Hash запроса.
modify_date string Дата последнего изменения/выполнения запроса.
on_track string Стоит ли запрос на слежении. 1 - стоит, 0 - снят.
track_type string Тип слежения. 1 - постоянное, 2 - рейс. Обратите внимание, нумерация в данном случае отличае от таковой при постановке на слежение./
track_state string Регион слежения. ru - только РФ, sng - страны СНГ, Балтии, Монголия, Китай.
state string Государство слежения. 20 - РФ, 22 - страны СНГ, Балтии, Монголия, Китай.
status int Статус обработки запроса. 1 - в очереди на обработку, 2 - обрабатывается, 3,4 - обработан

Получение списка ПС в запросе. Метод "carr_list".

Ниже приводится полный список входных параметров:

Параметр Тип Описание
Обязательные
action string carr_list - список номеров перевозочных средств в запросе
login string Логин в сервисе. Например, alta@alta.ru
sa string Сервис-аккаунт (договор). Например, sa000000
secret string Сгенерированный секрет. Например bb92dcee8bf2b49287e1038b65a72b79
hash string Хэш запроса. Например 931700e35d7ff88a10bd5d680da50f02


Например:
https://www.alta.ru/rail_tracking/api_v2.php?action=carr_list&login=alta@alta.ru&sa=sa000000&secret=bb92dcee8bf2b49287e1038b65a72b79&hash=931700e35d7ff88a10bd5d680da50f02

Json-ответ:

[
  {
    "status": "ok"
  },
  {
    "group_id": 1519743,
    "carrs": [
      "AMFU8899067"
    ]
  }
]

Выходные поля json-массива:

Поле Тип Описание
Обязательные
1-й элемент
status string ok - при успешном получении данных, error или fail - при ошибке. Список кодов ошибок см. ниже.


Последующие эелементы
carrs string Массив номеров перевозочных средств в запросе

Получение баланса. Метод "balance"

Ниже приводится полный список входных параметров:

Параметр Тип Описание
Обязательные
action string balance - остаток денежных средств или бонусов на счету
login string Логин в сервисе. Например, alta@alta.ru
sa string Сервис-аккаунт (договор). Например, sa000000
secret string Сгенерированный секрет. Например bb92dcee8bf2b49287e1038b65a72b79

Например:
https://www.alta.ru/rail_tracking/api_v2.php?action=balance&login=alta@alta.ru&sa=sa000000&secret=bb92dcee8bf2b49287e1038b65a72b79

Json-ответ

[
  {
    "status": "ok",
    "descr": "Ваш баланс: 0.00 руб. / Бонусы 0",
    "balans": "0.00",
    "bonus": 0,
    "sa": "sa000000"
  }
]

Выходные поля json-массива:

Поле Тип Описание
Обязательные
1-й элемент
status string ok - при успешном получении данных, error или fail - при ошибке. Список кодов ошибок см. ниже.
descr string Остаток денежных средств/бонусов в текстовом виде
balans string Остаток денежных средств в рублях
bonus string Остаток бонусов
sa string Номер договора (сервис-аккаунта)