JSON-API сервиса поиска вагонов
Содержание
- 1 О сервисе
- 2 API. Авторизация. Метод "test_secret".
- 3 Тестирование JSON-API
- 4 Структура ответа и статус запроса
- 5 Выполнение оперативного (разового) запроса. Метод "add".
- 6 Пример оперативного запроса
- 7 Получение ответа на оперативный запрос. Метод "show".
- 8 Пример получения отчета на оперативный запрос.
- 9 Постановка вагонов/контейнеров на слежение. Метод "add" с доп. параметрами.
- 10 Пример постановки на слежение
- 11 Получение ответа на ПС, стоящих на слежении. Метод "show".
- 12 Снятие со слежения.
О сервисе
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')") = 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
Hash для получения ответов по вагонам:
- оперативный запрос 7e1019777173ff342ef500e31719572c
- слежение ebc356dfa5beee7d3844ccacf535410c
Cont_hash для получения ответов по контейнерам:
- оперативный запрос fece39d1523836d03c3c2da73a6f1275
- слежение 931700e35d7ff88a10bd5d680da50f02
Структура ответа и статус запроса
Выполнение оперативного (разового) запроса. Метод "add".
Оперативный запрос выполняется единожды. Запрос в среднем обрабатывается в течение минуты. Тарифицируются только те запросы, по которым пришел ответ. Например, в запросе указано 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
Получение ответа на оперативный запрос. Метод "show".
После размещения запроса он встает в очередь на обработку. Обычно обработка занимает около 1 минуты. В случае повышенной нагрузки на сервер обработка может занимать до 5 минут и более. Оптимальный период опроса сервера - 1 минута. В случае частых запросов ООО "Альта-Софт" оставляет за собой право заблокировать такие запросы и отказать в обслуживании.
Ниже приводится полный список входных параметров:
Параметр | Тип | Описание |
---|---|---|
Обязательные | ||
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 | Хэш запроса. |
Последующие эелементы (при 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". Время московское. |
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
Постановка вагонов/контейнеров на слежение. Метод "add" с доп. параметрами.
Постановка на слежение аналогично оперативному запросу, т.е. выполняется с помощью метода "add". Существенное различие в дополнительных параметрах, их значениях и поведении системы при слежении.
Существует несколько регионов слежения: РФ, СНГ и Балтия, СНГ и Балтия + Китай + Монголия. Ниже описаны основные отличия и особенности:
- Основное отличие от оперативного запроса - во времени отклика системы. Если выполнив оперативный запрос ответ будет получен в течение минуты (в среднем), то при слежении ответ может формироваться довольно продолжительное время: от 10 минут по РФ до нескольких часов по странам Средней Азии и Китаю. - В течение суток можно получить до 3-х обновлений дислокации за одну цену, в то время как каждый оперативный запрос тарифицируется. - Стоимость слежения по РФ значительно ниже слежения по другим регионам. Однако, в случае пересечения перевозочного средства границы нет никаких гарантий, что свежая информация продолжит поступать. - Слежение по СНГ и Балтии, Китаю и Монголии позволяет получать дислокацию по всем перечисленным регионам, независимо от того, где находится ПС - При постановке ПС на слежение задается регламент получения отчетов - в какой день недели и какое время удобно получать свежую информацию, а также способ снятия со слежения (ручной или автоматический) - Существуют 2 типа слежения: посуточное и рейс. Единственное отличие между ними - в способе тарификации. Посуточное слежение - это такой тип слежения, когда денежные средства списываются со счета клиента при очередном формировании отчета (т.е. первом отчете за сутки согласно расписанию). Рейс тарифицируется сразу за весь маршрут при постановке на слежение и нет необходимости следить за состоянием баланса. - По hash оперативного запроса не идет обновление информации, т.е. информация о дислокации актуальна только на момент получения ответа. Для слежения информация по hash будет постоянно обновляться до окончания слежения.
Ниже приводится полный список входных параметров. Жирным шрифтом отмечены те из них, которых или нет в оперативном запросе, или их значению следует уделить внимание при постановке на слежение:
Параметр | Тип | Описание |
---|---|---|
Обязательные | ||
action | string | add - добавление оперативного запроса |
login | string | Логин в сервисе. Например, alta@alta.ru |
sa | string | Сервис-аккаунт (договор). Например, sa000000 |
secret | string | Сгенерированный секрет. Например 5ec1514f1b5a383fc5ad3f04bb9ac0e3 |
wagons | string | Список номеров вагонов/контейнеров через запятую. Например, "54676515,AMFU8899067" |
state | string | Код страны, по которой осуществляется запрос. Для РФ - 20. По странам СНГ и Балтии, Монголии, Китаю - 22. |
track_state | string | Регион слежения. ru - только Россия, sng - страны СНГ, Балтии, Монголия, Китай. |
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=5ec1514f1b5a383fc5ad3f04bb9ac0e3&wagons=AMFU8899067&state=20&track_type=2&comment=первое слежение (конт)&days=1,2,3,4,5×_per_day=2×=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=5ec1514f1b5a383fc5ad3f04bb9ac0e3&hash=931700e35d7ff88a10bd5d680da50f02