API для сервиса report.alta.ru: различия между версиями

Материал из Alta-Soft Wikipedia
Перейти к навигации Перейти к поиску
м (→‎Получение документов)
(→‎простой клиент на питоне убрал verify)
 
(не показаны 33 промежуточные версии 3 участников)
Строка 1: Строка 1:
−
== Сервис мониторинг таможенного оформления (REPORT ALTA)  ==
+
== Сервис мониторинг таможенного оформления (REPORT.ALTA.RU)  ==
 
Сервис предоставляет разработчикам возможность получения информации из внешних программ и сайтов в JSON-формате. С помощью данного сервиса можно выгружать следующую информацию:
 
Сервис предоставляет разработчикам возможность получения информации из внешних программ и сайтов в JSON-формате. С помощью данного сервиса можно выгружать следующую информацию:
  
 
# Список логинов, к пользователю может быть прикреплено много логинов
 
# Список логинов, к пользователю может быть прикреплено много логинов
 
# Декларанты, таможенные посты
 
# Декларанты, таможенные посты
−
# Получение ДТ
+
# Получение ДТ, ТД, Пассажирских ТД, Заявлений о выпуске до подачи
−
# Получение документов гр.44 (если включено дублирование всех сообщений)
+
# Получение привязанных документов (если включено дублирование всех сообщений)
 
# Получение ЭД сообщений
 
# Получение ЭД сообщений
  
Строка 24: Строка 24:
 
|v1 || '''string''' || Версия апи, текущая версия 1 || v1 v2 … v1.1
 
|v1 || '''string''' || Версия апи, текущая версия 1 || v1 v2 … v1.1
 
|-
 
|-
−
|function || '''string''' || вызываемая функция апи || docs, decl, logins, tam
+
|function || '''string''' || вызываемая функция апи || docs, messages, decl, logins, tam
 
|-
 
|-
 
|apikey || '''string''' || Ключ авторизации, получить в личном кабинете || 5b145adecf42b8eecd4e6f3dc7134f45
 
|apikey || '''string''' || Ключ авторизации, получить в личном кабинете || 5b145adecf42b8eecd4e6f3dc7134f45
Строка 78: Строка 78:
  
 
Получаем массив таможенных постов
 
Получаем массив таможенных постов
 +
 +
=== Получение списка поддерживаемых видов документов ===
 +
 +
<code>/docs/types/</code> 
 +
 +
{| class="wikitable"
 +
!Параметр || Описание || Пример
 +
|-
 +
|title || Краткое наименование документа || ДТ
 +
|-
 +
|toolTip || Полное наименование документа || Декларация на товары
 +
|-
 +
|maxDatePeriod || Максимальное кол-во месяцев в периоде, за который можно запрашивать документы || 3
 +
|-
 +
|filters || Список возможных фильтров для запроса списка документов ||
 +
|}
  
 
=== Получение документов ===
 
=== Получение документов ===
Строка 85: Строка 101:
 
фильтры, передаются как ПАРАМЕТРЫ запроса, пример:
 
фильтры, передаются как ПАРАМЕТРЫ запроса, пример:
  
−
<code><nowiki>https://report.alta.ru/api/v1/docs</nowiki>/?'''regdate[from]=2019-03-01'''&apikey=xxx&hash=xxx&</code>
+
<code><nowiki>https://report.alta.ru/api/v1/docs</nowiki>/?'''doctype=gtd&regdate[from]=2019-03-01'''&apikey=xxx&hash=xxx&</code>
  
 
{| class="wikitable"
 
{| class="wikitable"
 
!Параметр || '''Тип''' || Описание || Пример
 
!Параметр || '''Тип''' || Описание || Пример
 
|-
 
|-
−
|regdate[from] || string || дата регистрации от<br/>только дата || regdate[from]=2019-03-01
+
|'''doctype''' || '''string''' || Вид документа (gtd, td1, arg, passd) || doctype=gtd (по умолчанию, можно не указывать)
 
|-
 
|-
−
|regdate[to] || string || дата регистрации до<br/>только дата || regdate[to]=2019-03-01
+
|regdate[from] || '''string''' || дата регистрации от<br/>только дата || regdate[from]=2019-03-01
 
|-
 
|-
−
|vypdate[from] || string || ДатаВремя выпуска от || vypdate[from]=2019-05-08<br/>vypdate[from]=2021-10-10Т10:30:00
+
|regdate[to] || '''string''' || дата регистрации до<br/>только дата || regdate[to]=2019-03-01
 
|-
 
|-
−
|vypdate[to] || string || ДатаВремя выпуска до || vypdate[to]=2019-05-08<br/>vypdate[to]=2021-10-20Т10:30:00+03:00
+
|vypdate[from] || '''string''' || ДатаВремя выпуска от || vypdate[from]=2019-05-08<br/>vypdate[from]=2021-10-10T10:30:00
 
|-
 
|-
−
|lastmsgdate[from] || string || последнее сообщение ДатаВремя от || lastmsgdate[from]= 2019-05-08<br/>lastmsgdate[from]=2021-10-10Т10:30:00
+
|vypdate[to] || '''string''' || ДатаВремя выпуска до || vypdate[to]=2019-05-08<br/>vypdate[to]=2021-10-20T10:30:00+03:00
 
|-
 
|-
−
|lastmsgdate[to] || string || последнее сообщение ДатаВремя до || lastmsgdate[to]=2019-03-01<br/>lastmsgdate[to]=2021-10-20Т10:30:00+03:00
+
|lastmsgdate[from] || '''string''' || последнее сообщение ДатаВремя от || lastmsgdate[from]= 2019-05-08<br/>lastmsgdate[from]=2021-10-10T10:30:00
 
|-
 
|-
−
|decl || array || ИНН декларанта, можно несколько || decl[]=555555<br/>decl[]=666666
+
|lastmsgdate[to] || '''string''' || последнее сообщение ДатаВремя до || lastmsgdate[to]=2019-03-01<br/>lastmsgdate[to]=2021-10-20T10:30:00+03:00
 
|-
 
|-
−
|tam || array || Номер таможенного поста, можно несколько || tam[]=555
+
|decl || '''array''' || ИНН декларанта, можно несколько || decl[]=555555<br/>decl[]=666666
 
|-
 
|-
−
|login || array || Логин, можно несколько || login[]=xxx
+
|tam || '''array''' || Номер таможенного поста, можно несколько || tam[]=555
 
|-
 
|-
−
|pid || array || процедуры || pid[]=xxx&pid[]=yyy&pid[]=zzz&..
+
|login || '''array''' || Логин, можно несколько || login[]=xxx
 +
|-
 +
|pid || '''array''' || процедуры || pid[]=xxx&pid[]=yyy&pid[]=zzz&..
 +
|-
 +
|cmn || '''array''' || Тип ЭД сообщения, можно несколько || cmn[]=CMN.11005<br/>cmn[]=CMN.11252
 
|}
 
|}
  
 
В ответ получаем документы
 
В ответ получаем документы
 +
 +
{| class="wikitable"
 +
|docs || '''array''' || массив документов ||
 +
|}
 +
 +
==== Массив docs ====
 +
 +
Это массив документов, содержит в себе объект doc
 +
Список столбцов с их описанием и примерами можно получить отдельным запросом апи <code>/docs/fields/</code>
 +
 +
==== Получение, Печать документа, Просмотр документа ====
 +
 +
Теперь, зная список документов, можно получить определенный документ по его ID, вывод данного запроса по умолчанию идет в html виде
 +
 +
<code>/docs/ID/</code>
 +
 +
, где ID = ProccessID_Login, пример: <code>1a2ab345-1a12-1a01-1234-1234a5678bc1_123456</code>
 +
 +
'''также можно передать дополнительные параметры'''
 +
 +
{| class="wikitable"
 +
!Параметр || '''Тип''' || Описание || Пример
 +
|-
 +
|format || '''string''' || Формат ответа (html, xml, pdf) || format=xml
 +
|}
 +
 +
==== Получение полей (заголовки столбцов) ====
 +
 +
<code>/docs/fields/</code>
 +
 +
получение полей, заголовков столбцов с их описанием и примерами
 +
 +
==== Получение списка привязанных ЭД документов ====
 +
 +
<code>/docs44/ID/</code>
 +
 +
, где ID = ProccessID_Login, пример: 1a2ab345-1a12-1a01-1234-1234a5678bc1_123456
 +
 +
'''также можно передать дополнительные параметры - фильтры'''
 +
 +
у каждого документа, есть вложенные документы, у документа может быть очень много записей в этом параметре,
 +
поэтому также есть фильтр по вложенным документам 
 +
 +
{| class="wikitable"
 +
!Параметр || '''Тип''' || Описание || Пример
 +
|-
 +
|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</br>tovNum[]=40
 +
|}
 +
 +
в ответ получаем массив с документами
 +
 +
{| class="wikitable"
 +
|docName || '''string''' || имя документа
 +
|-
 +
|docCode || '''string''' || Код документа
 +
|-
 +
|docDate || '''string''' || Дата документа
 +
|-
 +
|tovNum || '''string''' || Товары, их номера
 +
|-
 +
|elDocId || '''string''' || ID документа в архиве таможни
 +
|-
 +
|docNum || '''string''' || Номер документа
 +
|-
 +
|elArchId || '''string''' || ID архива таможни
 +
|}
 +
 +
==== Получение привязанного ЭД документа  ====
 +
 +
Запрос похож на предыдущий, добавляем только ID документа в архиве таможни
 +
 +
<code>/docs44/ID/</code>
 +
 +
, где ID = elDocId_ProccessID_Login, пример: b1b2abcd-1a2b-1a23-a123-a12b345cde1a_1a2ab345-1a12-1a01-1234-1234a5678bc1_123456
 +
 +
=== Получение сообщений ===
 +
 +
<code>/messages/ID/</code>
 +
 +
, где ID = ProccessID_Login, пример: 1a2ab345-1a12-1a01-1234-1234a5678bc1_123456
 +
 +
ProccessID и Login обязательны
 +
 +
дополнительные параметры для запроса:
 +
 +
{| class="wikitable"
 +
!Параметр || '''Тип''' || Описание || Пример
 +
|-
 +
|date[from] || '''string''' || Дата сообщения от || date[from]=2019-03-01
 +
|-
 +
|date[to] || '''string''' || Дата сообщения до || date[to]=2019-03-01
 +
|}
 +
 +
==== Массив messages ====
 +
 +
в ответ получаем объект messages, это массив с элементами message - объект с данными сообщения
 +
 +
{| class="wikitable"
 +
|messages || array || массив с сообщениями
 +
|}
 +
 +
сообщение message, элемент этого массива, структура:
 +
 +
{| class="wikitable"
 +
|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
 +
 +
<code>/messages/ID/</code>
 +
 +
, где ID = EnvelopeID_ProccessID_Login, пример: b1b2abcd-1a2b-1a23-a123-a12b345cde1a_1a2ab345-1a12-1a01-1234-1234a5678bc1_123456
 +
 +
EnvelopeID, ProccessID и Login обязательны
 +
 +
возвращается сообщение по умолчанию в html виде
 +
 +
если сообщение содержит несколько документов, то все они будут склеены в один html
 +
 +
НО разделены комментариями <nowiki><!-- next doc --> </nowiki>
 +
 +
лучше показывать каждый документ отдельно, т.к. иногда бывает, что у документов пересекаются стили и они могут выглядеть некорректно, т.к. при склеивании html склеивается тело и стили. Пример как это выглядит:
 +
 +
<source lang="xml">
 +
 +
<!-- count 2 -->
 +
<!-- id=172987F4-A741-4A71-9780-AE28A38031E4 -->
 +
<!DOCTYPE html ....
 +
html.... тело документа со всеми стилями
 +
<!-- NEXT DOC -->
 +
<!-- id=2ACB2210-F7E7-4AB0-A2BD-10533FE4FBE4 -->
 +
<!DOCTYPE html ....
 +
html.... тут следующее тело со стилями
 +
</source>
 +
 +
надо ориентироваться, если в начале документа есть параметр count 2, то значит в сообщении 2 документа
 +
 +
'''также можно передать дополнительные параметры'''
 +
 +
{| class="wikitable"
 +
!Параметр || '''Тип''' || Описание || Пример
 +
|-
 +
|format || '''string''' || Формат ответа (html, xml, pdf) || format=xml
 +
|}
 +
 +
== Типы данных ==
 +
 +
{| class="wikitable"
 +
|'''string''' || строковый параметр
 +
|-
 +
|'''array''' || массив значений, нумерация элементов начинается с 0, вложенные элементы могут быть всех типов
 +
|-
 +
|'''object''' || объект значений или именованный массив. ключи - могут быть как числовые так и текстовые, вложенные элементы могут быть всех типов
 +
|}
 +
 +
== Ошибки ==
 +
 +
При возникновении ошибки в корневом элементе появляется блок с кодом и описанием ошибки.
 +
При работе с сервисом возможны следующие ошибки:
 +
 +
{| class="wikitable"
 +
!Код || Описание
 +
|-
 +
|'''100''' || Нет обязательных параметров
 +
|-
 +
|'''200''' || АПИ ключ не найден или не действительный
 +
|-
 +
|'''201''' || Неверный хэш
 +
|-
 +
|'''202''' || Ошибка авторизации, обратитесь к администратору
 +
|-
 +
|'''204''' || Нет права выполнять эту операцию(запрос)
 +
|-
 +
|'''203''' || Слишком много запросов. Запрос отклонен
 +
|-
 +
|'''210''' || Необходимо принять оферту на сайте
 +
|-
 +
|'''300''' || Метод API не найден, возможно неверная версия АПИ
 +
|-
 +
|'''301''' || В запросе(методе) отсутствует  необходимый параметр
 +
|-
 +
|  || Строка запроса содержит синтаксическую ошибку
 +
|-
 +
|'''500''' || Обработка запроса потерпела неудачу из-за неизвестной ошибки, исключения
 +
|}
 +
 +
пример ошибок
 +
 +
<source lang='json'>
 +
{
 +
    "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"
 +
}
 +
</source>
 +
 +
== Примеры реализации простого клиента ==
 +
 +
=== простой клиент на питоне ===
 +
 +
на питоне 2.7, надо установить библиотеку  pip install requests
 +
 +
<source lang="Python">
 +
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
 +
    # делаем запрос
 +
    r = requests.get(api_url, params)
 +
    # выдаем ответ
 +
    if r.status_code != 200:
 +
        print r.status_code, "Похоже возникли ошибки: \n", r.text, r.json()
 +
    else:
 +
        print "ОТВЕТ", r.text, r.json()
 +
</source>
 +
 +
 +
 +
[[Категория:Автоматизация]]

Текущая версия на 20:15, 24 сентября 2026

Сервис мониторинг таможенного оформления (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
cmn[]=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
    # делаем запрос
    r = requests.get(api_url, params)
    # выдаем ответ
    if r.status_code != 200:
        print r.status_code, "Похоже возникли ошибки: \n", r.text, r.json()
    else:
        print "ОТВЕТ", r.text, r.json()
Источник — https://wiki.alta.ru/index.php?title=API_для_сервиса_report.alta.ru&oldid=1402