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

Материал из Alta-Soft Wikipedia
Перейти к навигации Перейти к поиску
(Новая страница: «О сервисе Слежение»)
 
 
(не показаны 3 промежуточные версии этого же участника)
Строка 1: Строка 1:
−
О сервисе Слежение
+
== О сервисе Слежение ==
 +
Сервис "Слежение" для "Груз на СВХ" <nowiki>https://www.alta.ru/svh-gruz/tracking/</nowiki> позволяет ставить контейнеры на слежение с получением результатов размещения на складе и таможенного оформления грузов в контейнере через личный кабинет.
 +
 
 +
Отправляет уведомления на почту и URL-адрес по webhook о появлении новой информации по указанным контейнерам. Ставить и снимать контейнеры со слежения можно как через личный кабинет так и по API. Почта, URL-адрес для уведомлений и события для уведомления настраиваются только через личный кабинет.
 +
 
 +
== API ==
 +
Доступ к API предоставляется по URL <nowiki>https://www.alta.ru/svh-gruz/tracking/api/v1/</nowiki>. Для использования сервиса необходима авторизация с помощью логина и пароля.
 +
 
 +
Логин и пароль для обращения по 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
 +
 
 +
# логин ― логин сервис аккаунта в открытом виде
 +
# секрет ― 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-запрос: <nowiki>https://www.alta.ru/svh-gruz/tracking/api/v1/list/?login=testlogin&secret=18a3a18768475d5fbaf244f291212e86</nowiki>  
 +
 
 +
=== Ответ ===
 +
 
 +
 
 +
<big>Метод</big> '''<big>List</big>'''
 +
Описание полей возвращаемых данных
 +
{| 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
 +
|Занят, происходит запись информации
 +
|-
 +
|arh
 +
|Контейнер перенесен в архив (удален), автоматически помещается в архив если статус old более 90 дней
 +
|}
 +
 
 +
 
 +
 
 +
<sup>2</sup> Уведомлять о старой информации ― Параметр включает уведомления по событиям слежения с даты ранее даты постановки на слежение created <sup>3</sup>
 +
 
 +
Например, если в параметре установлено 3 дня, то при постановке контейнера на слежение он уведомит Вас об информации, которая появилась не старше чем 3 дня назад.
 +
 
 +
 
 +
<big>Пример ответа:</big>
 +
 
 +
Код ответа 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, - максимальная дата полученная из сообщений
 +
 
 +
},
 +
 
 +
     ………..
 +
 
 +
   ]
 +
 
 +
}
 +
 
 +
<big>Метод</big> '''<big>Set</big>'''
 +
Описание полей возвращаемых данных
 +
{| class="wikitable"
 +
|success
 +
|bool
 +
|true ― успешный запрос
 +
|-
 +
|add
 +
|[]
 +
|Массив успешно добавленных контейнеров
 +
|-
 +
|no
 +
|[]
 +
|Массив контейнеров, которые не добавлены. Каждый элемент содержит массив, состоящий из номера контейнера и статуса
 +
|}
 +
 
 +
 
 +
<big>Пример ответа:</big>
 +
 
 +
 
 +
{
 +
 
 +
"add": ["TEST0000001"],
 +
 
 +
"success": true,
 +
 
 +
"no": [
 +
 
 +
     [    "TEST0000002",  "Новый"   ]
 +
 
 +
]
 +
 
 +
}
 +
 
 +
 
 +
<big>Метод</big> '''<big>Del</big>'''
 +
Описание полей возвращаемых данных
 +
{| class="wikitable"
 +
|success
 +
|bool
 +
|true ― успешный запрос
 +
|}
 +
 
 +
 
 +
<big>Пример ответа:</big>
 +
 
 +
 
 +
{
 +
 
 +
"success": true
 +
 
 +
}
 +
 
 +
 
 +
<big>Метод</big> '''<big>Info</big>'''
 +
Описание полей возвращаемых данных
 +
 
 +
{| class="wikitable"
 +
|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)
 +
|}
 +
 
 +
 
 +
<big>Пример ответа:</big>
 +
 
 +
 
 +
{
 +
 
 +
"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
 +
 
 +
}
 +
 
 +
'''<big>Webhook</big>'''
 +
 
 +
По Webhook на указанный в личном кабинете URL-адрес приходят POST данные в таком формате:
 +
{| class="wikitable"
 +
|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}

Текущая версия на 17:26, 1 августа 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  

Ответ

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

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, - максимальная дата полученная из сообщений

},

     ………..

   ]

}

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

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


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


{

"add": ["TEST0000001"],

"success": true,

"no": [

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

]

}


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

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

}

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}

Источник — https://wiki.alta.ru/index.php?title=Слежение_(для_Груз_на_СВХ)&oldid=1350