Слежение (для Груз на СВХ): различия между версиями

Материал из Alta-Soft Wikipedia
Перейти к навигации Перейти к поиску
Строка 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 необходимо получить в личном кабинете https://www.alta.ru/user/, заключив договор на использование онлайн-сервисов. В настройках договора будут указаны технический логин и пароль.
 
 
 
Тарификация производится так же как при постановке на слежение через личный кабинет.
 
 
 
API позволяет ставить, снимать со слежения и просматривать списки контейнеров находящихся на слежении. Уведомления об обнаружении новой информации приходят на указанные почтовые ящики в кабинете слежения https://www.alta.ru/svh-gruz/tracking/
 
  
Формирование URL запроса
+
Логин и пароль для обращения по API необходимо получить в личном кабинете <nowiki>https://www.alta.ru/user/</nowiki>, заключив договор на использование онлайн-сервисов. В настройках договора будут указаны технический логин и пароль. 
  
Запросы направляются на URL  https://www.alta.ru/svh-gruz/tracking/api/v1/<МЕТОД>/
+
Тарификация производится так же как при постановке на слежение через личный кабинет.  
  
Метод Тип запроса Описание
+
API позволяет ставить, снимать со слежения и просматривать списки контейнеров находящихся на слежении. Уведомления об обнаружении новой информации приходят на указанные почтовые ящики в кабинете слежения <nowiki>https://www.alta.ru/svh-gruz/tracking/</nowiki>
help GET вызывает справку - выдает доступные методы API и списки передаваемых параметров
 
test GET проверка работы API и правильности формирования запроса - выдает результат проверки правильности секрета, правильную строку для расчета секрета и логин (если отправлен верный секрет)
 
info GET информация об аккаунте и настройках слежения
 
set POST постановка контейнеров на слежение, POST-параметр data=<номера контейнеров через запятую “,”>
 
del POST снятие контейнеров со слежения, POST-параметр ids=<id контейнеров через запятую “,”> или data=<имена контейнеров через запятую “,”> (id контейнера приходит при постановке на слежение)
 
list GET просмотр статуса всех отслеживаемых контейнеров. Можно указать нужные контейнеры: ids=<id контейнеров через запятую “,”> или data=<имена контейнеров через запятую “,”>
 
  
 +
=== Формирование 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 записей
  
data [] Корневой элемент, содержит массив записей слежения *
+
<sup>1</sup> Статусы слежения:
id int Идентификатор записи слежения
+
{| class="wikitable"
created str дата постановки на слежение 3
+
|new
updated str дата последнего обновления информации сервисом
+
|новый, запись только что добавлена
num str номер контейнера
+
|-
status str статус слежения 1
+
|process
do1 int количество записей ДО1 по контейнеру
+
|в процессе обработки, проходят проверки
cmn13014 int количество сообщений 13014 по контейнеру
+
|-
infoDateMax str дата последних полученных данных по контейнеру
+
|old
 
+
|в процессе обработки, имеется старая информация, старше чем указано в настройках ЛК в параметре Уведомлять о старой информации <sup>2</sup>
* максимальный размер возвращаемых данных 9900 записей
+
|-
 
+
|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
Номер контейнера : тип уведомления Тип уведомления:  do1 ― появилась ДО1;  13014 ― появилось сообщение CMN.13014
+
|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

  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  

Ответ

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

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}