JSON-API сервиса поиска вагонов

О сервисе

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

API

Доступ к 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')") = 5ec1514f1b5a383fc5ad3f04bb9ac0e3

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

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

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

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

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

Выполнение оперативного (разового) запроса

Оперативный запрос выполняется единожды. Запрос в среднем обрабатывается в течение минуты. Тарифицируются только те запросы, по которым пришел ответ. Например, в запросе указано 6 вагонов, а ответ пришел только на 5. Значит с баланса спишется сумма за 5 вагонов.
Ниже приводится полный список входных параметров:

Параметр	Тип	Описание
Обязательные
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
Необязательные
comment	string	Комментарий к запросу в urlencode
emails	string	Список email-адресов, куда отправить отчет о дислокации после выполнения, через запятую.
email_report_type	int	Всегда 2
attach_excel	int	Вкладывать ли в письма копию отчета в Excel. 1 - вкладывать, 0 - не вкладывать. По умолчанию 0.

JSON-ответ включает в себя отчет о состоянии запроса (принят/не принят в обработку) и hash, по которому можно получить ответ.
Например, на запрос вагона 54676515 и контейнера AMFU8899067 получим json-массив:

[
  {
    "status": "ok",
    "descr": "Запрос успешно сохранен",
    "hash": "7e1019777173ff342ef500e31719572c",
    "group_id": 322,
    "cont_hash": "fece39d1523836d03c3c2da73a6f1275"
  }
]

Следует учитывать, что в силу особенностей обработки запросов вагоны и контейнеры обрабатываются отдельно (обычно ответ на вагоны приходит быстрее). Поэтому в ответе может быть 2 хэша.

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

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

Пример оперативного запроса

Запрос дислокации вагона 54676515:
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
В запросе можно комбинировать номера вагонов и контейнеров.
Запрос дислокации вагона 54676515 и контейнера AMFU8899067:
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

Получение ответа на оперативный запрос

После размещения запроса он встает в очередь на обработку. Обычно обработка занимает около 1 минуты. В случае повышенной нагрузки на сервер обработка может занимать до 5 минут и более.

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

Параметр	Тип	Описание
Обязательные
action	string	show - просмотр дислокации по заданному hash
login	string	Логин в сервисе. Например, alta@alta.ru
sa	string	Сервис-аккаунт (договор). Например, sa000000
secret	string	Сгенерированный секрет. Например 5ec1514f1b5a383fc5ad3f04bb9ac0e3
hash	string	Хэш запроса. Например, 7e1019777173ff342ef500e31719572c

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": "",
    "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	Хэш запроса.
Последующие эелементы
num	string	Номер перевозочного средства
station	string	Код станции, где была зафиксирована последняя операция с перевозочным средством. 5 символов(или 6 символов, 6-й - контрольный знак)
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"
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 - порожний

Пример получения отчета на оперативный запрос

Получить отчет по вагону из предыдущего примера (54676515) по hash=7e1019777173ff342ef500e31719572c:
https://www.alta.ru/rail_tracking/api_v2.php?action=show&login=alta@alta.ru&sa=sa000000&secret=5ec1514f1b5a383fc5ad3f04bb9ac0e3&hash=7e1019777173ff342ef500e31719572c