Слежение (для Груз на СВХ)
О сервисе Слежение
Сервис "Слежение" для "Груз на СВХ" https://www.alta.ru/svh-gruz/tracking/ позволяет ставить контейнеры на слежение с получением результатов размещения на складе и таможенного оформления грузов в контейнере через личный кабинет.
Отправляет уведомления на почту и URL-адрес по webhook о появлении новой информации по указанным контейнерам. Ставить и снимать контейнеры со слежения можно как через личный кабинет так и по API. Почта, URL-адрес для уведомлений и события для уведомления настраиваются только через личный кабинет.
API
Доступ к API предоставляется по URL https://www.alta.ru/svh-gruz/tracking/api/v1/. Для использования сервиса необходима авторизация с помощью логина и пароля.
Логин и пароль для обращения по API необходимо получить в личном кабинете https://www.alta.ru/user/, заключив договор на использование онлайн-сервисов. В настройках договора будут указаны технический логин и пароль.
Тарификация производится так же как при постановке на слежение через личный кабинет.
API позволяет ставить, снимать со слежения и просматривать списки контейнеров находящихся на слежении. Уведомления об обнаружении новой информации приходят на указанные почтовые ящики в кабинете слежения https://www.alta.ru/svh-gruz/tracking/
Формирование URL запроса
Запросы направляются на URL https://www.alta.ru/svh-gruz/tracking/api/v1/<МЕТОД>/
Метод Тип запроса Описание help GET вызывает справку - выдает доступные методы API и списки передаваемых параметров test GET проверка работы API и правильности формирования запроса - выдает результат проверки правильности секрета, правильную строку для расчета секрета и логин (если отправлен верный секрет) info GET информация об аккаунте и настройках слежения set POST постановка контейнеров на слежение, POST-параметр data=<номера контейнеров через запятую “,”> del POST снятие контейнеров со слежения, POST-параметр ids=<id контейнеров через запятую “,”> или data=<имена контейнеров через запятую “,”> (id контейнера приходит при постановке на слежение) list GET просмотр статуса всех отслеживаемых контейнеров. Можно указать нужные контейнеры: ids=<id контейнеров через запятую “,”> или data=<имена контейнеров через запятую “,”>
обязательные GET параметры в URL
логин ― логин сервис аккаунта в открытом виде секрет ― MD5-хеш от сгенерированной строки (все параметры разделены знаком “:” (двоеточие)): параметры_GET + параметры_POST + метод + логин + md5(пароль)
Формирование секрета
secret = md5("{параметры_GET}:{параметры_POST}:{метод}:{логин}:{md5(пароль)}")
параметры_GET ― это значения прочих get параметров помимо логина, секрета и метода, разделенные “:”
параметры_POST ― это значения post параметров для методов set и del, разделенные “:”
Пример расчёта секрета для метода del, логина testlogin и пароля testpassword:
Если дополнительный GET параметр foo = bar , то для расчета секрета надо использовать параметры_GET = “bar”
Для метода del надо указывать id номера контейнеров в POST параметре ids через запятую. Если ids=11,55,33 , то для расчета секрета параметры_POST = “11,55,33”
Итоговая строка секрета = md5("bar:11,55,33:del:testlogin:md5(testpassword)")
Пример запроса списка контейнеров:
Метод list, пользователь с логином testlogin и пароль testpassword
Прочие параметры_GET - отсутствуют, параметры_POST отсутствуют, так как это GET метод
Вычисляем секрет: secret = md5("пусто:пусто:list:testlogin:md5(testpassword)") = md5("::list:testlogin:md5(testpassword)") = 18a3a18768475d5fbaf244f291212e86
Таким образом, итоговый URL, на который совершается GET-запрос: https://www.alta.ru/svh-gruz/tracking/api/v1/list/?login=testlogin&secret=18a3a18768475d5fbaf244f291212e86
Ответ
Описание полей возвращаемых данных
data [] Корневой элемент, содержит массив записей слежения * id int Идентификатор записи слежения created str дата постановки на слежение 3 updated str дата последнего обновления информации сервисом num str номер контейнера status str статус слежения 1 do1 int количество записей ДО1 по контейнеру cmn13014 int количество сообщений 13014 по контейнеру infoDateMax str дата последних полученных данных по контейнеру
- максимальный размер возвращаемых данных 9900 записей
1 Статусы слежения:
new новый, запись только что добавлена process в процессе обработки, проходят проверки old в процессе обработки, имеется старая информация, старше чем указано в настройках ЛК в параметре Уведомлять о старой информации 2 busy занят, происходит запись информации arh контейнер перенесен в архив (удален), автоматически помещается в архив если статус old более 90 дней
2 Уведомлять о старой информации ― Параметр включает уведомления по событиям слежения с даты ранее даты постановки на слежение created 3
Например, если в параметре установлено 3 дня, то при постановке контейнера на слежение он уведомит Вас об информации, которая появилась не старше чем 3 дня назад.
Пример ответа:
Код ответа 200:
{
"data": [
{
"id": 12,
"created": "2023-01-19 12:03:45",
"updated": "2023-04-11 18:11:06",
"num": "XXXX1018593",
"status": "process", - статус слежения
"do1": 0, - сколько записей ДО1 по контейнеру
"cmn13014": 0, - сколько сообщений 13014 по контейнеру
"infoDateMax": null, - максимальная дата полученная из сообщений
},
………..
]
}
Webhook
По Webhook на указанный в личном кабинете URL-адрес приходят POST данные в таком формате:
test int 1 ― указывает что запрос тестовый, отсутствие параметра ― боевой change [] json Массив изменений в json формате Номер контейнера : тип уведомления Тип уведомления: do1 ― появилась ДО1; 13014 ― появилось сообщение CMN.13014
пример POST запроса:
test=1&change={"TEST0000001":"do1","TEST0000002":"13014"}
Возможные ошибки
При возникновении ошибок возвращается код ответа сервера отличный от 200, а также описание ошибки в JSON-массиве.
код ответа 400:
{"success":false,"info":"Нет авторизации","code":101}
