JSON-API сервиса поиска вагонов: различия между версиями
(Метка: визуальный редактор отключён) |
(Метка: визуальный редактор отключён) |
||
Строка 154: | Строка 154: | ||
|- | |- | ||
|hash||string||Хэш запроса. Например, 7e1019777173ff342ef500e31719572c | |hash||string||Хэш запроса. Например, 7e1019777173ff342ef500e31719572c | ||
+ | |||
+ | |} | ||
+ | |||
+ | JSON-ответ включает в себя отчет о состоянии запроса (в очереди/обрабатывается/обработан) в первом элементе массива, в последующих элементах - отчет о дислокации перевозочных средств. | ||
+ | Например, на запрос AMFU8899067 получим json-массив: | ||
+ | |||
+ | <source lang="json"> | ||
+ | [ | ||
+ | { | ||
+ | "status": "ok", | ||
+ | "descr": "Обработан", | ||
+ | "query_status": "4", | ||
+ | "pwd": "", | ||
+ | "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" | ||
+ | } | ||
+ | ] | ||
+ | </source> | ||
+ | |||
+ | Выходные параметры json-массива: | ||
+ | |||
+ | {| class="wikitable" width="75%" | ||
+ | |+ | ||
+ | !Параметр !!Тип !!Описание | ||
+ | |||
+ | |- highlight | ||
+ | |colspan=3 |'''Обязательные''' | ||
+ | |||
+ | |- highlight | ||
+ | |colspan=3 |'''1-й элемент''' | ||
+ | |||
+ | |- | ||
+ | |status||string||ok - при успешном получении данных, error или fail - при ошибке. Список кодов ошибок см. ниже. | ||
+ | |||
+ | |- | ||
+ | |descr||string||Текстовое описание состояния или ошибки | ||
+ | |||
+ | |- | ||
+ | |type||int||Тип запроса. 1- вагоны, 2 - контейнеры | ||
+ | |||
+ | |- | ||
+ | |query_status||int||Состояние запроса. 1 - в очереди, 2 - обрабатывается, 3 или 4 - обработан | ||
+ | |||
+ | |- | ||
+ | |count||int||Количество перевозочных средств в отчете | ||
+ | |||
+ | |||
+ | |- | ||
+ | |hash||string||Хэш запроса. | ||
+ | |||
+ | |- highlight | ||
+ | |colspan=3 |'''Необязательные''' | ||
+ | |||
+ | |- | ||
+ | |hash||string||Хэш запроса по вагонам (если они были в запросе) | ||
+ | |||
+ | |- | ||
+ | |cont_hash||string||Хэш запроса по контейнерам (если они были в запросе) | ||
|} | |} | ||
Получить отчет по вагону из предыдущего примера (54676515) по hash=7e1019777173ff342ef500e31719572c: | Получить отчет по вагону из предыдущего примера (54676515) по hash=7e1019777173ff342ef500e31719572c: |
Версия 16:44, 29 июля 2021
Содержание
О сервисе
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=sa0000000&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",
"pwd": "",
"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 | int | Тип запроса. 1- вагоны, 2 - контейнеры |
query_status | int | Состояние запроса. 1 - в очереди, 2 - обрабатывается, 3 или 4 - обработан |
count | int | Количество перевозочных средств в отчете
|
hash | string | Хэш запроса. |
Необязательные | ||
hash | string | Хэш запроса по вагонам (если они были в запросе) |
cont_hash | string | Хэш запроса по контейнерам (если они были в запросе) |
Получить отчет по вагону из предыдущего примера (54676515) по hash=7e1019777173ff342ef500e31719572c: