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