API подбор кода ТНВЭД для экспресс-грузов: различия между версиями

Материал из Alta-Soft Wikipedia
Перейти к навигации Перейти к поиску
 
(не показано 5 промежуточных версий этого же участника)
Строка 10: Строка 10:
 
<pre>
 
<pre>
 
<xml>
 
<xml>
−
     <i id="1" descr="Описание товара 1"/>
+
     <i id="1" group="Описание группы товаров 1">
−
     <i id="2" descr="Описание товара 2"/>
+
        <name>Описание товара 1</name>
 +
        <name>Дополнительное описание товара 1</name>
 +
        ...
 +
    </i>
 +
     <i id="2">
 +
        <name>Описание товара 2</name>
 +
    </i>
 
     ...
 
     ...
−
    <i id="N" descr="Описание товара N"/>
 
 
</xml>
 
</xml>
 
</pre>
 
</pre>
 +
 +
{| class="wikitable" width="50%"
 +
|-
 +
|xml||Корневой элемент документа
 +
|-
 +
|i|| Узел с информацией об одном товаре
 +
|-
 +
|id|| Идентификатор товара: порядковый номер, артикул или какая-либо другая информация, уникальная для каждого товара в рамках запроса
 +
|-
 +
|group|| ''(Необязательно)'' Короткое описание группы товаров. При подборе кода ТНВЭД предпочтение будет отдаваться кодам, соответствующим этому описанию
 +
|-
 +
|name|| Описание товара. Для каждого товара может быть указано несколько полей name
 +
|}
 
   
 
   
 
Пример: для отправки запроса, содержащего один товар с описанием "брюки женские" нужно сформировать XML следующего вида:
 
Пример: для отправки запроса, содержащего один товар с описанием "брюки женские" нужно сформировать XML следующего вида:
Строка 21: Строка 39:
 
<pre>
 
<pre>
 
<xml>
 
<xml>
−
     <i id="1" descr="брюки женские"/>
+
     <i id="1">
 +
        <name>брюки женские</name>
 +
    </i>
 
</xml>
 
</xml>
 
</pre>
 
</pre>
Строка 32: Строка 52:
 
Accept-Encoding: gzip, deflate
 
Accept-Encoding: gzip, deflate
 
Host: www2.alta.ru
 
Host: www2.alta.ru
−
Content-Length: 198
+
Content-Length: 170
 
Connection: Close
 
Connection: Close
  
−
slogin=sa00000&xml=%3Cxml%3E%3Ci+id%3D%221%22+descr%3D%22%D0%B1%D1%80%D1%8E%D0%BA%D0%B8+%D0%B6%D0%B5%D0%BD%D1%81%D0%BA%D0%B8%D0%B5%22%2F%3E%3C%2Fxml%3E
+
slogin=sa00000&xml=%3Cxml%3E%3Ci%20id%3D%221%22%3E%3Cname%3E%D0%B1%D1%80%D1%8E%D0%BA%D0%B8%20%D0%B6%D0%B5%D0%BD%D1%81%D0%BA%D0%B8%D0%B5%3C%2Fname%3E%3C%2Fi%3E%3C%2Fxml%3E
 
</pre>
 
</pre>
  
Строка 43: Строка 63:
 
Accept-Encoding: gzip, deflate
 
Accept-Encoding: gzip, deflate
 
Host: www2.alta.ru
 
Host: www2.alta.ru
−
Content-Length: 860
+
Content-Length: 285
 
Connection: Close
 
Connection: Close
  
Строка 53: Строка 73:
 
Content-Disposition: form-data; name="xml"
 
Content-Disposition: form-data; name="xml"
  
−
<xml><i id="1" descr="брюки женские"/></xml>
+
<xml><i id="1"><name>брюки женские</name></i></xml>
 
-----------------------------7e6ad602d2--
 
-----------------------------7e6ad602d2--
 
</pre>
 
</pre>
Строка 77: Строка 97:
  
 
===Получение списка кодов ТНВЭД===
 
===Получение списка кодов ТНВЭД===
−
Для получения списка кодов ТНВЭД по идентификатору запроса (requestid) необходима авторизация с помощью сервисного логина и пароля.
+
Для получения списка кодов ТНВЭД по идентификатору запроса (requestid) необходимо выполнить GET-запрос, для которого требуется авторизация с помощью сервисного логина и пароля.
−
'''Для авторизации с помощью пары логин/пароль''' необходимо в GET-запрос добавить логин в открытом виде и MD5-хеш от сгенерированной строки '''requestid + логин + md5-хэш от пароля''', разделенный знаком двоеточия «:», например для пользователя с логином testlogin и паролем testpassword и requestid = 12345:<br>
+
 
−
вычисляем хеш:
+
Параметры, которые нужно передать в GET-запросе:
 +
{| class="wikitable" width="50%"
 +
|-
 +
|requestid||Идентификатор запроса, полученный при выполнении POST-запроса
 +
|-
 +
|slogin||Сервисный логин
 +
|-
 +
|hash||MD5-хеш от сгенерированной строки '''requestid + логин + md5-хэш от пароля''', разделенный знаком двоеточия «:»
 +
|-
 +
|payment||''(Необязательно)'' Укажите этот параметр со значением "packet" для списания из предоплаченного пакета, или "balance" для списания со счета. Значение по умолчанию (если не параметр не указан) - "packet"
 +
|-
 +
|tnveddescr||''(Необязательно)'' Укажите этот параметр со значением "1", если требуется к каждому найденному коду ТНВЭД добавить описание из справочника
 +
|}
 +
 
 +
Пример вычисления значения параметра '''hash''' для пользователя с логином testlogin, паролем testpassword и requestid = 12345:<br>
 
<pre>
 
<pre>
 
   hash = md5("12345:testlogin:" + md5("testpassword"));
 
   hash = md5("12345:testlogin:" + md5("testpassword"));
 
</pre>
 
</pre>
−
Итоговый URL: https://www2.alta.ru/tools/autotnved/v2/?requestid=12345&slogin=testlogin&hash=2b7283149605bc5ac1c17de3c34fc786
+
Итоговый URL: https://www2.alta.ru/tools/autotnved/v2/?requestid=12345&slogin=testlogin&hash=2b7283149605bc5ac1c17de3c34fc786&payment=balance&tnveddescr=1
  
 
XML-ответ в случае успешного выполнения запроса:
 
XML-ответ в случае успешного выполнения запроса:
Строка 94: Строка 128:
 
         <item>
 
         <item>
 
             <id>1</id>
 
             <id>1</id>
−
             <code>6404199000</code>
+
             <code>6204623100</code>
−
             <codeWeight>4249</codeWeight>
+
             <codeWeight>12784</codeWeight>
−
             <probability>0.30639</probability>
+
             <probability>0.19389</probability>
 +
            <descr>Прочие брюки и бриджи женские или для девочек из денима, или джинсовой ткани</descr>
 
         </item>
 
         </item>
 
     </response>
 
     </response>
 +
    <balance>100.00</balance>
 +
    <bonus>0</bonus>
 +
    <packet>
 +
        <item>
 +
            <id>1</id>
 +
            <started>2024-11-25 15:41:00</started>
 +
            <days>30</days>
 +
            <request_count>1000</request_count>
 +
            <used_count>3</used_count>
 +
            <left_count>997</left_count>
 +
        </item>
 +
    </packet>
 
</result>
 
</result>
 
</pre>
 
</pre>
Строка 111: Строка 158:
 
|-
 
|-
 
|response|| Блок, содержащий детальную информацию о всех найденных кодах ТНВЭД
 
|response|| Блок, содержащий детальную информацию о всех найденных кодах ТНВЭД
 +
{| class="wikitable"
 
|-
 
|-
 
| item || Блок, содержащий информацию о коде ТНВЭД для одного товара
 
| item || Блок, содержащий информацию о коде ТНВЭД для одного товара
 +
{| class="wikitable"
 
|-
 
|-
−
| id || Идентификатор товара (порядковый номер) в соответствии с исходным запросом
+
| id || Идентификатор товара в соответствии с исходным запросом
 
|-
 
|-
 
| code || Найденный код ТНВЭД
 
| code || Найденный код ТНВЭД
Строка 122: Строка 171:
 
| probability || Уровень доверия к найденному коду (доля найденного кода по отношению ко всем кодам, которые были использованы для декларирования товаров со схожим описанием)
 
| probability || Уровень доверия к найденному коду (доля найденного кода по отношению ко всем кодам, которые были использованы для декларирования товаров со схожим описанием)
 
|-
 
|-
 +
| descr || Описание кода из справочника ТНВЭД. Для включения этого поля в ответ, необходимо при выполнении GET-запроса добавить к URL параметр '''tnveddescr=1'''
 
|}
 
|}
 +
|}
 +
|-
 +
| balance || Доступный остаток на счете в рублях
 +
|-
 +
| bonus || Доступное количество запросов на подбор кода ТНВЭД
 +
|-
 +
| packet || Информация о доступных пакетах предоплаченных запросов
 +
{| class="wikitable"
 +
|-
 +
| id || Идентификатор пакета
 +
|-
 +
| active || Состояние пакета - используется или нет
 +
|-
 +
| started || Дата и время активации пакета
 +
|-
 +
| days || Количество дней, в течение которого пакет доступен для использования
 +
|-
 +
| request_count || Полное количество запросов в пакете
 +
|-
 +
| used_count || Количество использованных запросов в пакете
 +
|-
 +
| left_count || Доступное количество запросов в пакете
 +
|}
 +
|}
 +
 +
Информация о доступном остатке на счете и о предоплаченных пакетах доступна только при первом запросе на получение подобранных кодов ТНВЭД. При последующих запросах с использованием того же самого '''requestid''' эта информация в ответ сервера не включается.
  
 
==Ошибки==
 
==Ошибки==

Текущая версия на 10:56, 14 июля 2025

О сервисе

Сервис предназначен для автоматизированного определения 10-значных кодов ТНВЭД по описаниям товаров

API

Доступ к API предоставляется по URL https://www2.alta.ru/tools/autotnved/v2/.

Отправка исходных данных

Для отправки списка описаний товаров, для которых необходимо определить коды ТНВЭД, нужно отправить POST-запрос, в который должны быть включены параметр "slogin" со значением, соответствующим логину вашей учетной записи, и "xml", значение которого должно иметь следующий формат: 

<xml>
    <i id="1" group="Описание группы товаров 1">
        <name>Описание товара 1</name>
        <name>Дополнительное описание товара 1</name>
        ...
    </i>
    <i id="2">
        <name>Описание товара 2</name>
    </i>
    ...
</xml>
xml Корневой элемент документа
i Узел с информацией об одном товаре
id Идентификатор товара: порядковый номер, артикул или какая-либо другая информация, уникальная для каждого товара в рамках запроса
group (Необязательно) Короткое описание группы товаров. При подборе кода ТНВЭД предпочтение будет отдаваться кодам, соответствующим этому описанию
name Описание товара. Для каждого товара может быть указано несколько полей name

Пример: для отправки запроса, содержащего один товар с описанием "брюки женские" нужно сформировать XML следующего вида: 

<xml>
    <i id="1">
        <name>брюки женские</name>
    </i>
</xml>

Отправить его можно одним из следующих способов: 

POST /tools/autotnved/v2/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept-Encoding: gzip, deflate
Host: www2.alta.ru
Content-Length: 170
Connection: Close

slogin=sa00000&xml=%3Cxml%3E%3Ci%20id%3D%221%22%3E%3Cname%3E%D0%B1%D1%80%D1%8E%D0%BA%D0%B8%20%D0%B6%D0%B5%D0%BD%D1%81%D0%BA%D0%B8%D0%B5%3C%2Fname%3E%3C%2Fi%3E%3C%2Fxml%3E

POST /tools/autotnved/v2/ HTTP/1.1
Content-Type: multipart/form-data; boundary=---------------------------7e6ad602d2
Accept-Encoding: gzip, deflate
Host: www2.alta.ru
Content-Length: 285
Connection: Close

-----------------------------7e6ad602d2
Content-Disposition: form-data; name="slogin"

sa00000
-----------------------------7e6ad602d2
Content-Disposition: form-data; name="xml"

<xml><i id="1"><name>брюки женские</name></i></xml>
-----------------------------7e6ad602d2--

Если запрос выполнится успешно, ответ сервера будет иметь следующий вид: 

<result>
    <message>Запрос поставлен в очередь</message>
    <requestid>7</requestid>
</result>
result Корневой элемент документа
message Элемент с информацией о статусе запроса
requestid Идентификатор запроса, который понадобится в дальнейшем

Получение списка кодов ТНВЭД

Для получения списка кодов ТНВЭД по идентификатору запроса (requestid) необходимо выполнить GET-запрос, для которого требуется авторизация с помощью сервисного логина и пароля.

Параметры, которые нужно передать в GET-запросе:

requestid Идентификатор запроса, полученный при выполнении POST-запроса
slogin Сервисный логин
hash MD5-хеш от сгенерированной строки requestid + логин + md5-хэш от пароля, разделенный знаком двоеточия «:»
payment (Необязательно) Укажите этот параметр со значением "packet" для списания из предоплаченного пакета, или "balance" для списания со счета. Значение по умолчанию (если не параметр не указан) - "packet"
tnveddescr (Необязательно) Укажите этот параметр со значением "1", если требуется к каждому найденному коду ТНВЭД добавить описание из справочника

Пример вычисления значения параметра hash для пользователя с логином testlogin, паролем testpassword и requestid = 12345:

  hash = md5("12345:testlogin:" + md5("testpassword"));

Итоговый URL: https://www2.alta.ru/tools/autotnved/v2/?requestid=12345&slogin=testlogin&hash=2b7283149605bc5ac1c17de3c34fc786&payment=balance&tnveddescr=1

XML-ответ в случае успешного выполнения запроса: 

<result>
    <handled>true</handled>
    <message>Запрос обработан</message>
    <response>
        <item>
            <id>1</id>
            <code>6204623100</code>
            <codeWeight>12784</codeWeight>
            <probability>0.19389</probability>
            <descr>Прочие брюки и бриджи женские или для девочек из денима, или джинсовой ткани</descr>
        </item>
    </response>
    <balance>100.00</balance>
    <bonus>0</bonus>
    <packet>
        <item>
            <id>1</id>
            <started>2024-11-25 15:41:00</started>
            <days>30</days>
            <request_count>1000</request_count>
            <used_count>3</used_count>
            <left_count>997</left_count>
        </item>
    </packet>
</result>
result Корневой элемент документа
handled Состояние запроса: обработан или еще нет (стоит в очереди)
message Описание состояния запроса
response Блок, содержащий детальную информацию о всех найденных кодах ТНВЭД
item Блок, содержащий информацию о коде ТНВЭД для одного товара
id Идентификатор товара в соответствии с исходным запросом
code Найденный код ТНВЭД
codeWeight Вес кода (количество товаров со схожим описанием, задекларированных с найденным кодом)
probability Уровень доверия к найденному коду (доля найденного кода по отношению ко всем кодам, которые были использованы для декларирования товаров со схожим описанием)
descr Описание кода из справочника ТНВЭД. Для включения этого поля в ответ, необходимо при выполнении GET-запроса добавить к URL параметр tnveddescr=1
balance Доступный остаток на счете в рублях
bonus Доступное количество запросов на подбор кода ТНВЭД
packet Информация о доступных пакетах предоплаченных запросов
id Идентификатор пакета
active Состояние пакета - используется или нет
started Дата и время активации пакета
days Количество дней, в течение которого пакет доступен для использования
request_count Полное количество запросов в пакете
used_count Количество использованных запросов в пакете
left_count Доступное количество запросов в пакете

Информация о доступном остатке на счете и о предоплаченных пакетах доступна только при первом запросе на получение подобранных кодов ТНВЭД. При последующих запросах с использованием того же самого requestid эта информация в ответ сервера не включается.

Ошибки

При возникновении ошибки в корневом элементе появляется блок с кодом и описанием ошибки. 

<Error>
    <ErrorCode>201</ErrorCode>
    <ErrorDescr>Запрос #12345 не найден</ErrorDescr>
</Error>

При работе с сервисом возможны следующие ошибки:

Код Описание
100 Пользователь не авторизован
110 Лимит запросов для данного пользователя исчерпан
120 Ошибка тарификации
140 Недостаточно средств для выполнения запроса
Источник — https://wiki.alta.ru/index.php?title=API_подбор_кода_ТНВЭД_для_экспресс-грузов&oldid=1388