Просмотр кода страницы API для сервиса report.alta.ru

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

# Список логинов, к пользователю может быть прикреплено много логинов
# Декларанты, таможенные посты
# Получение ДТ
# Получение документов гр.44 (если включено дублирование всех сообщений)
# Получение ЭД сообщений

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

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

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

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

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

<code>/api/v1/docs/?apikey=XXX&hash=YYY</code>

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

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

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


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

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

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


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

== Список всех функций API ==
Для наглядности опустим тут обязательную часть запроса, оставим только конкретику

<code><nowiki>https://report.alta.ru/api/v1</nowiki>/'''FUNC/param0'''/?apikey=XXX&hash=YYY</code>

=== Получение логинов ===
<code>/logins/</code>

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

=== Получение декларантов === 
<code>/decl/</code>

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

=== Получение таможенных постов === 
<code>/tam/</code>

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

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

<code>/docs/</code>   

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

<code><nowiki>https://report.alta.ru/api/v1/docs</nowiki>/?'''regdate[from]=2019-03-01'''&apikey=xxx&hash=xxx&</code>

{| class="wikitable"
!Параметр || '''Тип''' || Описание || Пример
|-
|regdate[from] || '''string''' || дата регистрации от<br/>только дата || regdate[from]=2019-03-01
|-
|regdate[to] || '''string''' || дата регистрации до<br/>только дата || regdate[to]=2019-03-01
|-
|vypdate[from] || '''string''' || ДатаВремя выпуска от || vypdate[from]=2019-05-08<br/>vypdate[from]=2021-10-10T10:30:00
|-
|vypdate[to] || '''string''' || ДатаВремя выпуска до || vypdate[to]=2019-05-08<br/>vypdate[to]=2021-10-20T10:30:00+03:00
|-
|lastmsgdate[from] || '''string''' || последнее сообщение ДатаВремя от || lastmsgdate[from]= 2019-05-08<br/>lastmsgdate[from]=2021-10-10T10:30:00
|-
|lastmsgdate[to] || '''string''' || последнее сообщение ДатаВремя до || lastmsgdate[to]=2019-03-01<br/>lastmsgdate[to]=2021-10-20T10:30:00+03:00
|-
|decl || '''array''' || ИНН декларанта, можно несколько || decl[]=555555<br/>decl[]=666666
|-
|tam || '''array''' || Номер таможенного поста, можно несколько || tam[]=555
|-
|login || '''array''' || Логин, можно несколько || login[]=xxx
|-
|pid || '''array''' || процедуры || pid[]=xxx&pid[]=yyy&pid[]=zzz&..
|}

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

{| class="wikitable"
|docs || '''array''' || массив документов	 || 
|}

из выдачи убрали заголовки столбцов, для их получения есть запрос апи <code>/docs/fields/</code>

==== Массив docs ====

Это массив документов, содержит в себе объект doc

==== Объект doc ====

{| class="wikitable"
!messagetype || '''string''' || Тип текущего сообщения с ДТ || CMN.11023
|-
|login || '''string''' || Catchall Логин || 123456-ca
|-
|svdlogin || '''string''' || Логин СВД || 123456-01
|-
|envelopeid || '''string''' || EnvelopeID текущего сообщения с ДТ || BD9D1189-A58E-482B-A108-ADF7D2459BFD
|-
|status || '''string''' || Статус процедуры в числовом виде || 3
|-
|softver || '''string''' || Версия альбома и спецификации || 5.14.2/3.3.21
|-
|ProccessID || '''string''' || ID процедуры || 1a2ab345-1a12-1a01-1234-1234a5678bc1
|-
|LastMessageDate || '''string''' || Дата последнего сообщения по процедуре  || 	
|-
|DeclarantOrganizationName || '''string''' || Наименование организациии || ООО \"Альта-Софт\"
|-
|DeclarantINN || '''string''' || ИНН декларанта || 1234567890
|-
|DeclarantOGRN || '''string''' || ОГРН декларанта	 || 
|-
|DeclarantFIO || '''string''' || ФИО декларанта из гр.54 || 
|-
|consignorName || '''string''' || Отправитель || 
|-
|consignorAddres || '''string''' || Адрес отправителя	 || 
|-
|consigneeName || '''string''' || Получатель	 || 
|-
|consigneeAddres || '''string''' || Адрес получателя	 || 
|-
|sellerName || '''string''' || Продавец (ДТС)	 || 
|-
|Transp || '''string''' || Номера транспортных средств || 
|-
|TrCount || '''string''' || Количество транспортных средств || 
|-
|Contract || '''string''' || Номер контракта || 
|-
|TrDoc || '''string''' || Номер транспортных документов || 
|-
|Cont || '''string''' || Номера контейнеров	
|-
|NetWeightQuantity || '''string''' || Нетто || 20160.00
|-
|GrossWeightQuantity || '''string''' || Брутто || 20640.00
|-
|CustomsCost || '''string''' || Таможенная стоимость || 1989792.00
|-
|InvoicedCost || '''string''' || Фактурная стоимость || 1989792.00
|-
|ContractCurrencyCode || '''string''' || Валюта контракта || RUB
|-
|sborSum || '''string''' || Сумма таможенных сборов || 30000.00
|-
|poshSum || '''string''' || Сумма таможенных пошлин || 1989792.00
|-
|ndsSum || '''string''' || Сумма НДС || 1989792.00
|-
|akcizSum || '''string''' || Сумма акциза || 1989792.00
|-
|platSum || '''string''' || Сумма платежей || 1989792.00
|-
|REGNUM || '''string''' || Номер ДТ || 10000000/010121/0123456 
|-
|PackageNumber || '''string''' || Кол-во мест	 || 
|-
|GoodsCount || '''string''' || Кол-во товаров	 || 1
|-
|BorderCustoms || '''string''' || Код поста гр.29	 || 10000000
|-
|UD || '''string''' || Код поста гр.30	 || 10000000
|-
|UDName || '''string''' || Наименование поста гр.30	 || ФТС России
|-
|CustomsProcedure || '''string''' || Режим || ИМ
|-
|CustomsModeCode || '''string''' || Процедура || 40
|-
|DeclarationKind || '''string''' || Особенности процедуры || ПТД
|}

=== Наименования статусов ===
{| class="wikitable"
|1 || Открытие процедуры
|-
|2 || Присвоен номер
|-
|3 || Идет проверка
|-
|4 || Идет досмотр
|-
|5 || Проверка закончена
|-
|6 || Условно выпущена
|-
|7 || Выпуск разрешен
|-
|10 || Отказано в выпуске
|-
|11 || Товар прибыл (ПТД)
|-
|12 || Выпуск с обеспечением
|-
|13 || Отзыв
|-
|14 || Считается не поданной
|-
|15 || Выпуск приостановлен
|-
|17 || Частично выпущена
|-
|26 || Выпуск под обеспечение
|-
|27 || Идет осмотр
|-
|28 || Идет экспертиза
|-
|8192 || Отказано в приеме
|-
|16384 || Переход на "бумагу"
|-
|32768 || Запрошен отзыв
|}

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

Теперь, зная список документов, можно получить определенный документ по его 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>

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

=== Получение вложенных документов из графы 44 ===

<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 архива таможни	
|}

=== Получение тела документа 44. Печать в html  ===

Запрос похож на предыдущий, добавляем только спереди 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, это массив с элементами message - объект с данными сообщения

{| class="wikitable"
|messages || array || массив с сообщениями	
|}

сообщение message, элемент этого массива, структура:
 
{| class="wikitable"
|MessageType || '''string''' || Тип сообщения || CMN.11001
|-
|Priority || '''string''' || Служебное поле в заголовке сообщения || 4
|-
|Incoming || '''string''' || 0 - исходящее сообщение, 1 - входящее || 1
|-
|login || '''string''' || Логин || 123456
|-
|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
|-
|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 документа в архиве таможни	 || 
|}

запрос также проверяет доступ к ИНН, если не прописан доступ к ИНН, то вернет ошибку

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

Запрос похож на предыдущий, добавляется только 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''' || Слишком много запросов. Запрос отклонен. 
|-
|'''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
    # делаем запрос, я отключил проверку сертификата 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
</source>



[[Категория:Автоматизация]]