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

Материал из Alta-Soft Wikipedia
Перейти к навигации Перейти к поиску
(→‎Ошибки)
(→‎Объект doc)
Строка 133: Строка 133:
 
|-
 
|-
 
|envelopeid || '''string''' || EnvelopeID текущего сообщения с ДТ || BD9D1189-A58E-482B-A108-ADF7D2459BFD
 
|envelopeid || '''string''' || EnvelopeID текущего сообщения с ДТ || BD9D1189-A58E-482B-A108-ADF7D2459BFD
 +
|-
 +
|messagetype || '''string''' || Тип текущего ЭД сообщения с ДТ || CMN.11010
 
|-
 
|-
 
|status || '''string''' || Статус процедуры в числовом виде || 3
 
|status || '''string''' || Статус процедуры в числовом виде || 3
 
|-
 
|-
 
|softver || '''string''' || Версия альбома и спецификации || 5.14.2/3.3.21
 
|softver || '''string''' || Версия альбома и спецификации || 5.14.2/3.3.21
 +
|-
 +
|ver || '''string''' || Системная версия списка колонок || 1.06
 
|-
 
|-
 
|ProccessID || '''string''' || ID процедуры || 1a2ab345-1a12-1a01-1234-1234a5678bc1
 
|ProccessID || '''string''' || ID процедуры || 1a2ab345-1a12-1a01-1234-1234a5678bc1
 +
|-
 +
|ExProccessID || '''string''' || Список дополнительных ID процедур по основной || 1a2ab345-1a12-1a01-1234-1234a5678bc1
 
|-
 
|-
 
|LastMessageDate || '''string''' || Дата последнего сообщения по процедуре  ||
 
|LastMessageDate || '''string''' || Дата последнего сообщения по процедуре  ||

Версия 09:22, 4 июля 2024

Сервис мониторинг таможенного оформления (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-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&..

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

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

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

Массив docs

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

Объект doc

messagetype string Тип текущего сообщения с ДТ CMN.11023
login string Catchall Логин 123456-ca
svdlogin string Логин СВД 123456-01
envelopeid string EnvelopeID текущего сообщения с ДТ BD9D1189-A58E-482B-A108-ADF7D2459BFD
messagetype string Тип текущего ЭД сообщения с ДТ CMN.11010
status string Статус процедуры в числовом виде 3
softver string Версия альбома и спецификации 5.14.2/3.3.21
ver string Системная версия списка колонок 1.06
ProccessID string ID процедуры 1a2ab345-1a12-1a01-1234-1234a5678bc1
ExProccessID 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 Особенности процедуры ПТД

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

1 Открытие процедуры
2 Присвоен номер
3 Идет проверка
4 Идет досмотр
5 Проверка закончена
6 Условно выпущена
7 Выпуск разрешен
10 Отказано в выпуске
11 Товар прибыл (ПТД)
12 Выпуск с обеспечением
13 Отзыв
14 Считается не поданной
15 Выпуск приостановлен
17 Частично выпущена
26 Выпуск под обеспечение
27 Идет осмотр
28 Идет экспертиза
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 Слишком много запросов. Запрос отклонен
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=1343