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

Материал из Alta-Soft Wikipedia
Перейти к навигации Перейти к поиску
Строка 22: Строка 22:
 
|help
 
|help
 
|GET  
 
|GET  
−
|вызывает справку - выдает доступные методы API и списки передаваемых параметров
+
|Вызывает справку - выдает доступные методы API и списки передаваемых параметров
 
|-
 
|-
 
|test
 
|test
 
|GET  
 
|GET  
−
|проверка работы API и правильности формирования запроса - выдает результат проверки правильности секрета, правильную строку для расчета секрета и логин (если отправлен верный секрет)
+
|Проверка работы API и правильности формирования запроса - выдает результат проверки правильности секрета, правильную строку для расчета секрета и логин (если отправлен верный секрет)
 
|-
 
|-
 
|info  
 
|info  
 
|GET  
 
|GET  
−
|информация об аккаунте и настройках слежения
+
|Информация об аккаунте и настройках слежения
 
|-
 
|-
 
|set  
 
|set  
 
|POST  
 
|POST  
−
|постановка контейнеров на слежение, POST-параметр data=<номера контейнеров через запятую “,”>
+
|Постановка контейнеров на слежение, POST-параметр data=<номера контейнеров через запятую “,”>
 
|-
 
|-
 
|del  
 
|del  
 
|POST  
 
|POST  
−
|снятие контейнеров со слежения, POST-параметр ids=<id  контейнеров через запятую “,”> или data=<имена контейнеров  через запятую “,”> (id контейнера приходит при постановке на слежение)
+
|Снятие контейнеров со слежения, POST-параметр ids=<id  контейнеров через запятую “,”> или data=<имена контейнеров  через запятую “,”> (id контейнера приходит при постановке на слежение)
 
|-
 
|-
 
|list  
 
|list  
 
|GET  
 
|GET  
−
|просмотр статуса всех отслеживаемых контейнеров. Можно указать нужные контейнеры: ids=<id контейнеров через запятую “,”> или data=<имена контейнеров через запятую “,”>
+
|Просмотр статуса всех отслеживаемых контейнеров. Можно указать нужные контейнеры: ids=<id контейнеров через запятую “,”> или data=<имена контейнеров через запятую “,”>
 
|}
 
|}
 
обязательные GET параметры в URL
 
обязательные GET параметры в URL
Строка 80: Строка 80:
  
 
=== Ответ ===
 
=== Ответ ===
 +
 +
 +
<big>Метод</big> '''<big>List</big>'''
  
 
Описание полей возвращаемых данных
 
Описание полей возвращаемых данных
Строка 93: Строка 96:
 
|created
 
|created
 
|str
 
|str
−
|дата постановки на слежение <sup>3</sup>
+
|Дата постановки на слежение <sup>3</sup>
 
|-
 
|-
 
|updated
 
|updated
 
|str
 
|str
−
|дата последнего обновления информации сервисом
+
|Дата последнего обновления информации сервисом
 
|-
 
|-
 
|num
 
|num
 
|str
 
|str
−
|номер контейнера
+
|Номер контейнера
 
|-
 
|-
 
|status
 
|status
 
|str
 
|str
−
|статус слежения <sup>1</sup>
+
|Статус слежения <sup>1</sup>
 
|-
 
|-
 
|do1
 
|do1
 
|int
 
|int
−
|количество записей ДО1 по контейнеру
+
|Количество записей ДО1 по контейнеру
 
|-
 
|-
 
|cmn13014
 
|cmn13014
 
|int
 
|int
−
|количество сообщений 13014 по контейнеру
+
|Количество сообщений 13014 по контейнеру
 
|-
 
|-
 
|infoDateMax
 
|infoDateMax
 
|str
 
|str
−
|дата последних полученных данных по контейнеру
+
|Дата последних полученных данных по контейнеру
 
|}
 
|}
 
<nowiki>*</nowiki> максимальный размер возвращаемых данных 9900 записей
 
<nowiki>*</nowiki> максимальный размер возвращаемых данных 9900 записей
Строка 124: Строка 127:
 
{| class="wikitable"
 
{| class="wikitable"
 
|new
 
|new
−
|новый, запись только что добавлена
+
|Новый, запись только что добавлена
 
|-
 
|-
 
|process
 
|process
−
|в процессе обработки, проходят проверки
+
|В процессе обработки, проходят проверки
 
|-
 
|-
 
|old
 
|old
−
|в процессе обработки, имеется старая информация, старше чем указано в настройках ЛК в параметре Уведомлять о старой информации <sup>2</sup>
+
|В процессе обработки, имеется старая информация, старше чем указано в настройках ЛК в параметре Уведомлять о старой информации <sup>2</sup>
 
|-
 
|-
 
|busy
 
|busy
−
|занят, происходит запись информации
+
|Занят, происходит запись информации
 
|-
 
|-
 
|arh
 
|arh
−
|контейнер перенесен в архив (удален), автоматически помещается в архив если статус old более 90 дней
+
|Контейнер перенесен в архив (удален), автоматически помещается в архив если статус old более 90 дней
 
|}
 
|}
  
Строка 145: Строка 148:
 
Например, если в параметре установлено 3 дня, то при постановке контейнера на слежение он уведомит Вас об информации, которая появилась не старше чем 3 дня назад.
 
Например, если в параметре установлено 3 дня, то при постановке контейнера на слежение он уведомит Вас об информации, которая появилась не старше чем 3 дня назад.
  
−
=== Пример ответа: ===
+
 
 +
<big>Пример ответа:</big>
 +
 
 
Код ответа 200:
 
Код ответа 200:
  
Строка 178: Строка 183:
 
}
 
}
  
 +
<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>'''
 
'''<big>Webhook</big>'''

Версия 17:25, 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=1349