Слежение (для Груз на СВХ)

О сервисе Слежение

Сервис "Слежение" для "Груз на СВХ" 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	Просмотр статуса всех отслеживаемых контейнеров. Через этот метод можно узнать id контейнеров находящихся на слежении. Можно указать нужные контейнеры: ids=<id контейнеров через запятую “,”> или data=<имена контейнеров через запятую “,”>

обязательные GET параметры в URL

1. логин ― логин сервис аккаунта в открытом виде
2. секрет ― 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  

Ответ

Метод List Описание полей возвращаемых данных

data	[]	Корневой элемент, содержит массив записей слежения *
id	int	Идентификатор записи слежения
created	str	Дата постановки на слежение 3
updated	str	Дата последнего обновления информации сервисом
num	str	Номер контейнера или авианакладной
type	str	Тип слежения: К - контейнер, А - авианакладная
status	str	Статус слежения 1
do1	int	Количество записей ДО1 по контейнеру
cmn13014	int	Количество сообщений 13014 по контейнеру
infoDateMax	str	Дата последних полученных данных по контейнеру

* максимальный размер возвращаемых данных 9900 записей

¹ Статусы слежения:

new	Новый, запись только что добавлена
process	В процессе обработки, проходят проверки
old	В процессе обработки, имеется старая информация, старше чем указано в настройках ЛК в параметре Уведомлять о старой информации 2
busy	Занят, происходит запись информации
arh	Контейнер перенесен в архив (удален), автоматически помещается в архив если статус old более 90 дней

² Уведомлять о старой информации ― Параметр включает уведомления по событиям слежения с даты ранее даты постановки на слежение created ³

Например, если в параметре установлено 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,

  "cmn13014": 0,

  "infoDateMax": null,

},

    ...

   ]

}

Метод Set

POST данные: data=TEST0000001,TEST0000002

Описание полей возвращаемых данных

success	bool	true ― успешный запрос
add	[]	Массив успешно добавленных контейнеров
no	[]	Массив контейнеров, которые не добавлены. Каждый элемент содержит массив, состоящий из номера контейнера и статуса

Пример ответа:

{

"add": ["TEST0000001"],

"success": true,

"no": [

     [    "TEST0000002",  "Новый"   ]

]

}

Метод Del аналогичен методу set

POST данные: data=TEST0000001,TEST0000002

Описание полей возвращаемых данных

success

bool

true ― успешный запрос

Пример ответа:

{

"success": true

}

Метод Info Описание полей возвращаемых данных

success	bol	true ― успешный запрос
data	[]	Массив, содержащий настройки аккаунта
notifyEmail	bool	1 ― включены уведомления на email
notifyOneMail	bool	1 ― отдельное письмо для каждого результата. Если в течении минуты пришло несколько контейнеров, то при значении "0" они будут объединены в одно письмо
notifyTG	bool	1 ― включены уведомления в телеграмм
notifyWebhook	bool	1 ― включены уведомления webhook
webhook	str	URL-адрес webhook
tgId	int	ID привязанного телеграмм аккаунта
sa_balance	float	Баланс сервис аккаунта
service_price	float	Цена за уведомление
freezing	float	Заморожено средств
addArh	bool	Разрешено добавлять архивные
sa_login	str	Логин выбранного сервис аккаунта
notifyAddDoc	bool	1 ― добавляет номер документа-основания (ДО1 или CMN.13014) в текст уведомления
notifyOldDay	int	Кол-во дней. При постановке задачи на слежение учитывается полученная ранее информация. Если параметр = 3 дня, то будет уведомление об информации не старше 3 дней. Влияет только на начало слежения
notifyLoginEmail	bool	Уведомление на email аккаунта
notify13014	bool	Уведомлять о получении сообщений 13014
notifyDO1	bool	Уведомлять о появлении новых ДО1
login	str	Ваш логин
emails	[]	Массив Ваших дополнительных email адресов для уведомлений. Содержит массив значений ―  email адрес (ключевое поле) и состояние - включен (true) или нет (false)

Пример ответа:

{

"data": {

  "notifyEmail": 0,

  "service_price": 1,

  "notifyAddDoc": 1,

  "notifyTG": 0,

  "freezing": 147,

  "notifyWebhook": 0,

  "webhook": null,

  "addArh": 0,

  "sa_login": "сервис аккаунт",

  "notifyDO1": 0,

  "tgId": 11122233344,

  "sa_balance": 500,

  "notifyOldDay": 3,

  "notifyLoginEmail": 0,

  "notify13014": 1,

  "notifyOneMail": 0,

  "login": "ваш логин",

  "emails": {

   "первый@": false,

   "второй@": true

   },

},

"success": true

}

Возможные ошибки

При возникновении ошибок возвращается код ответа сервера отличный от 200, а также описание ошибки в JSON-массиве.

код ответа 400:

{"success":false,"info":"Нет авторизации","code":101}

Webhook

По Webhook на указанный в личном кабинете URL-адрес приходят POST данные в таком формате:

test	int	1 ― указывает что запрос тестовый, отсутствие параметра ― боевой
change	[] json	Массив изменений в json формате
Номер контейнера : тип уведомления		Тип уведомления:  do1 ― появилась ДО1;  13014 ― появилось сообщение CMN.13014

пример POST запроса:

test=1&change={"TEST0000001":"do1","TEST0000002":"13014"}

Работа запросов webhook

Как только url ответил с кодом 200, уведомление считается доставленным, но если код ответа отличный от 200, то происходит еще 5 попыток достучаться до указанного url с интервал между попытками примерно 1-2 минуты.