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

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

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

1. Список логинов, к пользователю может быть прикреплено много логинов
2. Декларанты, таможенные посты
3. Получение ДТ
4. Получение документов гр.44 (если включено дублирование всех сообщений)
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, 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/

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

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

Параметр	Тип	Описание	Пример
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-10Т10:30:00
vypdate[to]	string	ДатаВремя выпуска до	vypdate[to]=2019-05-08 vypdate[to]=2021-10-20Т10:30:00+03:00
lastmsgdate[from]	string	последнее сообщение ДатаВремя от	lastmsgdate[from]= 2019-05-08 lastmsgdate[from]=2021-10-10Т10:30:00
lastmsgdate[to]	string	последнее сообщение ДатаВремя до	lastmsgdate[to]=2019-03-01 lastmsgdate[to]=2021-10-20Т10: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&..

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

docs

array

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

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

Массив docs

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

Объект doc

messagetype	string	Тип текущего сообщения с ДТ	CMN.11023
login	string	Логин	123456
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	Адрес получателя
Transp	string	Номера транспортных средств
TrDoc	string	Номер транспортных документов
Cont	string	Номера контейнеров
NetWeightQuantity	string	Нетто	20160.00
GrossWeightQuantity	string	Брутто	20640.00
CustomsCost	string	Таможенная стоимость	1989792.00
InvoicedCost	string	Фактурная стоимость	1989792.00
ContractCurrencyCode	string	Валюта контракта	RUB
REGNUM	string	Номер ДТ	10000000/010121/0123456
PackageNumber	string	Кол-во мест
GoodsCount	string	Кол-во товаров	1
UD	string	Код поста гр.30	10000000
UDName	string	Наименование поста гр.30	ФТС России
CustomsProcedure	string	Режим	ИМ
CustomsModeCode	string	Процедура	40
DeclarationKind	string	Особенности процедуры	ПТД

Наименования статусов

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

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

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

/docs/ID/

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

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

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

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

/docs/fields/

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

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

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

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

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

messages

array

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

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

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

/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	Слишком много запросов. Запрос отклонен.
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