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

Материал из Alta-Soft Wikipedia
Перейти к навигации Перейти к поиску
м (→‎Получение сообщения. Печать в html)
м (→‎Типы данных)
Строка 397: Строка 397:
  
 
== Типы данных ==
 
== Типы данных ==
 +
 +
{| 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>
 +
 +
== Примеры реализации простого клиента ==
  
  
  
 
[[Категория:Автоматизация]]
 
[[Категория:Автоматизация]]

Версия 12:05, 12 августа 2022

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

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

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

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

Получение сообщения. Печать в html

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


Типы данных

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"
}

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

Источник — https://wiki.alta.ru/index.php?title=API_для_сервиса_report.alta.ru&oldid=1244