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

Материал из Alta-Soft Wikipedia
Перейти к навигации Перейти к поиску
Строка 344: Строка 344:
 
Существует несколько регионов слежения: РФ, СНГ и Балтия, СНГ и Балтия + Китай + Монголия. Ниже описаны основные отличия и особенности:<br>
 
Существует несколько регионов слежения: РФ, СНГ и Балтия, СНГ и Балтия + Китай + Монголия. Ниже описаны основные отличия и особенности:<br>
 
  - Основное отличие от оперативного запроса - во времени отклика системы. Если выполнив оперативный запрос ответ будет получен в течение минуты (в среднем), то при слежении ответ может формироваться довольно продолжительное время: от 10 минут по РФ до нескольких часов по странам Средней Азии и Китаю.   
 
  - Основное отличие от оперативного запроса - во времени отклика системы. Если выполнив оперативный запрос ответ будет получен в течение минуты (в среднем), то при слежении ответ может формироваться довольно продолжительное время: от 10 минут по РФ до нескольких часов по странам Средней Азии и Китаю.   
  - В течение суток можно получить до 3-х обновлений дислокации за одну цену, в то время как <b>каждый</b> оперативный запрос тарифицируется
+
  - В течение суток можно получить до 3-х обновлений дислокации за одну цену, в то время как <b>каждый</b> оперативный запрос тарифицируется.
  - Стоимость слежения по РФ значительно ниже слежения по другим регионам. Однако, в случае пересечения перевозочного средства границы нет никаких гарантий, что свежая информация продолжит поступать.<br>
+
  - Стоимость слежения по РФ значительно ниже слежения по другим регионам. Однако, в случае пересечения перевозочного средства границы нет никаких гарантий, что свежая информация продолжит поступать.
 
  - Слежение по СНГ и Балтии, Китаю и Монголии позволяет получать дислокацию по всем перечисленным регионам, независимо от того, где находится ПС
 
  - Слежение по СНГ и Балтии, Китаю и Монголии позволяет получать дислокацию по всем перечисленным регионам, независимо от того, где находится ПС
 
  - При постановке ПС на слежение задается регламент получения отчетов - в какой день недели и какое время удобно получать свежую информацию, а также способ снятия со слежения (ручной или автоматический)
 
  - При постановке ПС на слежение задается регламент получения отчетов - в какой день недели и какое время удобно получать свежую информацию, а также способ снятия со слежения (ручной или автоматический)
Строка 374: Строка 374:
  
 
|-
 
|-
|state||string||Код страны, по которой осуществляется запрос. На данный момент оперативные запросы поддерживаются только по РФ. Код=20.
+
|state||string||Код страны, по которой осуществляется запрос. Для РФ - 20. По странам СНГ и Балтии, Монголии, Китаю - 22.
  
 
|-
 
|-
|track_type||int||Тип слежения. Для оперативного запроса track_type=1
+
|track_state||string||Региоон слежения. ru - только Россия, sng - страны СНГ, Балтии, Монголия, Китай.
 +
 
 +
|-
 +
|track_type||int||Тип слежения. Для посуточного слежения запроса track_type=2, для рейса - track_type=3
  
 
|- highlight
 
|- highlight

Версия 19:51, 29 июля 2021

О сервисе

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

Выполнение оперативного (разового) запроса. Метод "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 минут и более.

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

Параметр Тип Описание
Обязательные
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

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

Постановка на слежение аналогично оперативному запросу, т.е. выполняется с помощью метода "add". Существенное различие в дополнительных параметрах, их значениях и поведении системы при слежении.
Существует несколько регионов слежения: РФ, СНГ и Балтия, СНГ и Балтия + Китай + Монголия. Ниже описаны основные отличия и особенности:

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

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

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