API для сервиса report.alta.ru

Материал из Alta-Soft Wikipedia
Перейти к навигации Перейти к поиску

Сервис мониторинг таможенного оформления (REPORT.ALTA.RU)

Сервис предоставляет разработчикам возможность получения информации из внешних программ и сайтов в JSON-формате. С помощью данного сервиса можно выгружать следующую информацию:

  1. Список логинов, к пользователю может быть прикреплено много логинов
  2. Декларанты, таможенные посты
  3. Получение ДТ, ТД, Пассажирских ТД, Заявлений о выпуске до подачи
  4. Получение привязанных документов (если включено дублирование всех сообщений)
  5. Получение ЭД сообщений

Описание параметров

Доступ к API предоставляется по URL https://report.alta.ru/api/ Входные параметры передаются с помощью запроса HTTPS GET. Для использования сервиса необходимо получить apikey и secret в личном кабинете

Пример адреса запроса с параметрами: https://report.alta.ru/api/function/параметр0/?параметр1…2...параметрN&apikey=XXXX&hash=YYYYY

любой запрос должен содержать обязательные параметры, они выделены жирным

Параметр Тип Описание Пример
Обязательные, должны быть в любом запросе
v1 string Версия апи, текущая версия 1 v1 v2 … v1.1
function string вызываемая функция апи docs, messages, decl, logins, tam
apikey string Ключ авторизации, получить в личном кабинете 5b145adecf42b8eecd4e6f3dc7134f45
hash string ХЭШ запроса, рассчитывается для каждого запроса по слову secret 34563456

К необязательным параметрам относится, например, параметр0 Параметр0 идет сразу после функции, его можно опустить, и не писать, тогда ставим слеш после функции и дописываем обязательные параметры ключ и хэш, пример:

/api/v1/docs/?apikey=XXX&hash=YYY

Параметр0 указываем для получения конкретного документа, пример:

/api/v1/docs/xxxxx/?apikey=XXX&hash=YYY

секрет нужен для генерации хэша (подписи) запроса, ХЭШ генерируется так:


hash = md5(версия + функция + параметр0(если есть) + ВСЕ_ПАРАМЕТРЫ + md5(apikey) + md5(secret)) ВСЕ_ПАРАМЕТРЫ — это конкатенация всех GET параметров в той последовательности, в которой они идут в параметрах запроса слева направо, параметры: апи ключ, хеш и секрет не участвуют пример, запрос:

https://report.alta.ru/api/v1/docs/?x=1&y=2&z=3&apikey=5555&hash=5b145adecf42b8eecd4e6f3dc7134f45

в данном случае ВСЕ_ПАРАМЕТРЫ это x y z нам известно, что наш аккаунт имеет следующие данные: apikey = 5555, secret = 7777 тогда вычислим хэш:


hash = md5 ( 1 + docs + (параметр0 не указан, его не берем) + 1 + 2 + 3 + md5(5555) + md5(7777)) = md5 (1docs1236074c6aa3488f3c2dddff2a7ca821aabd79c8788088c2193f0244d8f1f36d2db ) = получилось, что hash = 5b145adecf42b8eecd4e6f3dc7134f45

Список всех функций API

Для наглядности опустим тут обязательную часть запроса, оставим только конкретику

https://report.alta.ru/api/v1/FUNC/param0/?apikey=XXX&hash=YYY

Получение логинов

/logins/

Ответом получаем массив с логинами

Получение декларантов

/decl/

получаем массив с ИНН и названиями организаций

Получение таможенных постов

/tam/

Получаем массив таможенных постов

Получение списка поддерживаемых видов документов

/docs/types/

Параметр Описание Пример
title Краткое наименование документа ДТ
toolTip Полное наименование документа Декларация на товары
maxDatePeriod Максимальное кол-во месяцев в периоде, за который можно запрашивать документы 3
filters Список возможных фильтров для запроса списка документов

Получение документов

/docs/

фильтры, передаются как ПАРАМЕТРЫ запроса, пример:

https://report.alta.ru/api/v1/docs/?doctype=gtd&regdate[from]=2019-03-01&apikey=xxx&hash=xxx&

Параметр Тип Описание Пример
doctype string Вид документа (gtd, td1, arg, passd) doctype=gtd (по умолчанию, можно не указывать)
regdate[from] string дата регистрации от
только дата		 regdate[from]=2019-03-01
regdate[to] string дата регистрации до
только дата		 regdate[to]=2019-03-01
vypdate[from] string ДатаВремя выпуска от vypdate[from]=2019-05-08
vypdate[from]=2021-10-10T10:30:00
vypdate[to] string ДатаВремя выпуска до vypdate[to]=2019-05-08
vypdate[to]=2021-10-20T10:30:00+03:00
lastmsgdate[from] string последнее сообщение ДатаВремя от lastmsgdate[from]= 2019-05-08
lastmsgdate[from]=2021-10-10T10:30:00
lastmsgdate[to] string последнее сообщение ДатаВремя до lastmsgdate[to]=2019-03-01
lastmsgdate[to]=2021-10-20T10:30:00+03:00
decl array ИНН декларанта, можно несколько decl[]=555555
decl[]=666666
tam array Номер таможенного поста, можно несколько tam[]=555
login array Логин, можно несколько login[]=xxx
pid array процедуры pid[]=xxx&pid[]=yyy&pid[]=zzz&..
cmn array Тип ЭД сообщения, можно несколько cmn[]=CMN.11005
decl[]=CMN.11252

В ответ получаем документы

docs array массив документов

Массив docs

Это массив документов, содержит в себе объект doc Список столбцов с их описанием и примерами можно получить отдельным запросом апи /docs/fields/

Получение, Печать документа, Просмотр документа

Теперь, зная список документов, можно получить определенный документ по его ID, вывод данного запроса по умолчанию идет в html виде

/docs/ID/

, где ID = ProccessID_Login, пример: 1a2ab345-1a12-1a01-1234-1234a5678bc1_123456

также можно передать дополнительные параметры

Параметр Тип Описание Пример
format string Формат ответа (html, xml, pdf) format=xml

Получение полей (заголовки столбцов)

/docs/fields/

получение полей, заголовков столбцов с их описанием и примерами

Получение списка привязанных ЭД документов

/docs44/ID/

, где ID = ProccessID_Login, пример: 1a2ab345-1a12-1a01-1234-1234a5678bc1_123456

также можно передать дополнительные параметры - фильтры

у каждого документа, есть вложенные документы, у документа может быть очень много записей в этом параметре, поэтому также есть фильтр по вложенным документам

Параметр Тип Описание Пример
docCode string Код документа, можно указать часть кода , но только от начала строки 0234*, 04031
docNum string Номер документа, можно указать любую часть номера без звездочек VN-RU VN-RU, 18/04/
docDate[from] string Дата от 2018-01-01
docDate[to] string Дата до 2019-05-08
tovNum[] array Номер товара, задается массивом tovNum[]=1
tovNum[]=40

в ответ получаем массив с документами

docName string имя документа
docCode string Код документа
docDate string Дата документа
tovNum string Товары, их номера
elDocId string ID документа в архиве таможни
docNum string Номер документа
elArchId string ID архива таможни

Получение привязанного ЭД документа

Запрос похож на предыдущий, добавляем только ID документа в архиве таможни

/docs44/ID/

, где ID = elDocId_ProccessID_Login, пример: b1b2abcd-1a2b-1a23-a123-a12b345cde1a_1a2ab345-1a12-1a01-1234-1234a5678bc1_123456

Получение сообщений

/messages/ID/

, где ID = ProccessID_Login, пример: 1a2ab345-1a12-1a01-1234-1234a5678bc1_123456

ProccessID и Login обязательны

дополнительные параметры для запроса:

Параметр Тип Описание Пример
date[from] string Дата сообщения от date[from]=2019-03-01
date[to] string Дата сообщения до date[to]=2019-03-01

Массив messages

в ответ получаем объект messages, это массив с элементами message - объект с данными сообщения

messages array массив с сообщениями

сообщение message, элемент этого массива, структура:

messagetype string Тип сообщения CMN.11001
messagename string Наименование сообщения Регистрационный номер ДТ
priority string Служебное поле в заголовке сообщения 4
incoming string 0 - исходящее сообщение, 1 - входящее 1
login string Логин 123456-ca
svdlogin string Логин, с которого пришло сообщение 123456-01
envelopeid string EnvelopeID сообщения BD9D1189-A58E-482B-A108-ADF7D2459BFD
softversion string Версия альбома и спецификации 5.14.2/3.3.21
participantid string ID декларанта
customscode string Код таможни сообщения
initialenvelopeid string EnvelopeID родительского сообщения (на которое ссылается данное сообщение)
preparationdatetime string Дата и время сообщения
exchtype string Служебное поле в заголовке сообщения 19200
proccessid string ID процедуры сообщения 1a2ab345-1a12-1a01-1234-1234a5678bc1
mainproccessid string ID основной процедуры (если есть) 1a2ab345-1a12-1a01-1234-1234a5678bc1
senderinformation string Отправитель сообщения smtp://eps.customs.ru/gateway
receiverinformation string Получатель сообщения smtp://eps.customs.ru/102770123456789.as
sign string Электронная подпись ФЕДЕРАЛЬНАЯ ТАМОЖЕННАЯ СЛУЖБА
canView string 1 – возможен ли просмотр сообщения
type string arch – документ из архива (возможен запрос документа по ArchDocID)
archid string ID архива таможни
archdocid string ID документа в архиве таможни
objects array массив xml-объектов, содержащихся в данном сообщении (в т.ч. дата из поля DateLimit, если есть указан срок ответа)

Получение сообщения

Запрос похож на предыдущий, добавляется только EnvelopeID

/messages/ID/

, где ID = EnvelopeID_ProccessID_Login, пример: b1b2abcd-1a2b-1a23-a123-a12b345cde1a_1a2ab345-1a12-1a01-1234-1234a5678bc1_123456

EnvelopeID, ProccessID и Login обязательны

возвращается сообщение по умолчанию в html виде

если сообщение содержит несколько документов, то все они будут склеены в один html

НО разделены комментариями <!-- next doc -->

лучше показывать каждый документ отдельно, т.к. иногда бывает, что у документов пересекаются стили и они могут выглядеть некорректно, т.к. при склеивании html склеивается тело и стили. Пример как это выглядит: 

<!-- count 2 -->
<!-- id=172987F4-A741-4A71-9780-AE28A38031E4 -->
<!DOCTYPE html ....
 html.... тело документа со всеми стилями
<!-- NEXT DOC -->
<!-- id=2ACB2210-F7E7-4AB0-A2BD-10533FE4FBE4 -->
<!DOCTYPE html ....
 html.... тут следующее тело со стилями

надо ориентироваться, если в начале документа есть параметр count 2, то значит в сообщении 2 документа

также можно передать дополнительные параметры

Параметр Тип Описание Пример
format string Формат ответа (html, xml, pdf) format=xml

Типы данных

string строковый параметр
array массив значений, нумерация элементов начинается с 0, вложенные элементы могут быть всех типов
object объект значений или именованный массив. ключи - могут быть как числовые так и текстовые, вложенные элементы могут быть всех типов

Ошибки

При возникновении ошибки в корневом элементе появляется блок с кодом и описанием ошибки. При работе с сервисом возможны следующие ошибки:

Код Описание
100 Нет обязательных параметров
200 АПИ ключ не найден или не действительный
201 Неверный хэш
202 Ошибка авторизации, обратитесь к администратору
204 Нет права выполнять эту операцию(запрос)
203 Слишком много запросов. Запрос отклонен
210 Необходимо принять оферту на сайте
300 Метод API не найден, возможно неверная версия АПИ
301 В запросе(методе) отсутствует необходимый параметр
Строка запроса содержит синтаксическую ошибку
500 Обработка запроса потерпела неудачу из-за неизвестной ошибки, исключения

пример ошибок 

{
    "error": 200,
    "text": "BAD api key, USER not found"
}
{
    "error": 201,
    "text": "ERROR HASH"
}
{
    "error": 203,
    "q": "v1/decl/",
    "request_wait": 3.05,
    "text": "Sory, You have Limit requests to API:  5 requests per 10 seconds. Please wait 3.05 sec for next request"
}

Примеры реализации простого клиента

простой клиент на питоне

на питоне 2.7, надо установить библиотеку pip install requests 

apikey = "api_key"  # ваш ключ апи
secret = "secret"  # ваш секрет апи
v = 1  # версия
func = "docs"       # вызываемая функция
param = ""    # параметр используется для получения конкретного документа, например  /docs/ID/    /docs/100000000/
# доп параметры запроса
params = {
    'd': '123',
    'param1': 'xxxxx',
    'param2': 'yyyyyy'
}
# урл для запроса
api_url = "https://report.alta.ru/api/v%d/%s/" % (v, func) + (param + "/" if param else "")
 
if __name__ == "__main__":
    # рассчитываем хэш секрет для запроса
    # идем по всем параметрам по порядку
    str = ""
    for p in params:
        str += params[p]
        print p, params[p]
    # и в конце прибавляем ключ
    str = "%d%s%s%s%s" % (v, func + (param if param else ""), str, hashlib.md5(apikey).hexdigest(), hashlib.md5(secret).hexdigest())
    # считаем хэш
    hash = hashlib.md5(str).hexdigest()
    # добавляем эти параметры в запрос
    params['hash'] = hash  # + "1111"
    params['apikey'] = apikey
    print str, hash, api_url
    # делаем запрос, я отключил проверку сертификата SSL  а то не давало сделать запрос
    r = requests.get(api_url, params, verify=False)
    # выдаем ответ
    if r.status_code != 200:
        print r.status_code, "Похоже возникли ошибки: \n", r.text, r.content
    else:
        print "ОТВЕТ", r.content
Источник — https://wiki.alta.ru/index.php?title=API_для_сервиса_report.alta.ru&oldid=1383