Слежение (для Груз на СВХ)
Содержание
О сервисе Слежение
Сервис "Слежение" для "Груз на СВХ" 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
- логин ― логин сервис аккаунта в открытом виде
- секрет ― 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 записей
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,
"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 минуты.
