Работа с API в «Честном Знаке»

В этом обзоре мы узнаем как работать в Каталоге маркированных товаров при помощи методов API на конкретном примере, а также узнаем где взять всю необходимую для работы информацию.   

Начнем с того, что методы API позволяют проводить все те же процессы, что и web-интерфейс. При этом, данный способ позволяет автоматизировать все процессы под удобный для организации формат.

Примечание: В этом обзоре мы осуществляем работу в программе Insomnia. Вы можете выполнять аналогичные операции в любом другом удобном для вас программном обеспечении.

Для получения доступа к API Национального каталога нам необходимо воспользоваться методами авторизации в ГИС МТ и получить токен. Либо обратиться в службу техподдержки, чтобы получить идентификатор владельца товара или простыми словами — ключ.

Отметим, что динамический токен авторизации действует до 10 часов. После чего его нужно будет получить повторно. Также важно помнить, что без токена или ключа вы не сможете проводить бизнес процессы, так как они являются обязательными в запросах.

Рисунок 1

ВАЖНО! В рамках этого обзора все значения случайны. При работе в подсистеме Национальный каталог необходимо, чтобы заполнение атрибутов производилось согласно рекомендациям, расположенным на сайте национальный-каталог.рф

Методы используемые в работе с API

Давайте сгенерируем код товара.

Метод «Generate GTINS»

Этот способ подойдёт, если у нас нет GTIN и необходимо сформировать код на единицу товара, комплект или набор.  Давайте разберем основные параметры

«Quantity»

Этот параметр отвечает за количество кодов, которые будут сгенерированы. В ответ на наш запрос мы получим новый код товара в строке «gtin» (см рис. 2). Соответственно, если мы запросили несколько кодов, то в блоке «drafts» будет несколько gtin.

Рисунок 2

«Attributes»

Когда код товара сгенерирован мы можем перейти к созданию карточки товара, но перед этим рекомендуется создать запрос «attributes». Данный метод позволяет нам получить все атрибуты карточки товара по определенному коду ТН ВЭД (см. рис 3а).

Рисунок 3а

В этом примере мы запросили все атрибуты для карточки товара по товарной группе «Духи и туалетная вода». Но мы также можем запросить все атрибуты, указав в типе атрибута значение «а», либо запросить только опциональные, указав значение «о». В ответ, в нашем примере мы получили все обязательные для системы атрибуты, указав значение «m» (см. рис 3б).

Рисунок 3б

Вот все значения, которые может принимать атрибут «attr_type» (тип атрибута):

• a — вернуть все атрибуты (используется по умолчанию)

• m — вернуть только обязательные атрибуты

• r — вернуть только рекомендуемые атрибуты

• o — вернуть только опциональные атрибуты

Если же нам необходимо создать карточку черновика и не отправлять ее на модерацию (например, для создания КИЗ, но без их ввода в оборот), то следует обратить внимание на параметр «second_layer» (см. рис 3в) Он отвечает за обязательность атрибута для ввода товара в оборот.

Рисунок 3в

Следовательно, если создавать только черновик карточки, то данные параметры можно не указывать при ее создании.

Метод «Feed»

Этот метод создает новую карточку товара. Здесь же, в теле запросы мы указываем запрашиваемые ранее атрибуты товара. В зависимости от типа создаваемой карточки — единица, набор или техническая карточка, параметры тела запроса будут отличаться.

Тип «feed» — «Единица товара»

При создании новой карточки типа «Единица товара» мы должны указать сгенерированный ранее GTIN. А в параметре «is_tech_gtin» (технический GTIN) должно быть значение «false» (см. рис. 4а). Либо данный параметр может вовсе отсутствовать.

Рисунок 4а

Тип «feed» — «Техническая карточка»

Если мы создаем техническую карточку, то в ней наоборот GTIN отсутствует, так он будет сгенерирован автоматически. А вот в параметре «is_tech_gtin» должно быть значение «true» либо «1» (см. рис. 4б)

Рисунок 4б

Если нам нужно, чтобы карточка товара была сразу отправлена на модерацию, то в строке «good_attrs» должны находится все обязательные для системы атрибуты. Варианты заполнения можно посмотреть в предыдущем запросе «attributes», (см. рис. 3а выше). В противном случае, если мы их не заполним, то система пришлет уведомление, что необходимых сведений не хватает.

Тип «feed_status» — «Единица товара»

Когда наш запрос сформирован и отправлен, в ответ мы получим «feed_id» (см. рис. ). То есть, идентификатор задачи, статус которой мы узнаем, используя метод «feed_status»

Рисунок 5

Воспользуемся этим методом на примере технической карточки, указав его feed_id в запросе (см. рис 6а).

Рисунок 6а

После чего мы получим ответ, в котором будет статус, gtin и good_id (см. рис. 6б). Последний мы сможем использовать в методах запроса информации по карточке, а также в методе внесения изменений в карточку.

Рисунок 6б

Метод «feed_product»

Чтобы увидеть всю информацию, содержащуюся в карточке товара воспользуемся методом feed_product. В ответ мы получим всю информацию по данному gtin (см. рис. 7).

Рисунок 7.

Ввиду того, что техническая карточка в этом примере была создана на демо-аккаунте, и в ней отсутствует фотоконтент, модерацию она прошла автоматически. Нам остается только подписать ее. Кстати, какие сервисы использовать для создания качественного и нестандартного фотоконтента мы разбирали в этом обзоре.

Методы «feed_roduct_document» и «feed_roduct_sign»

Для того чтобы это сделать, нам потребуется использовать два метода. Первый — «feed_roduct_document». Он возвращает структуру документа для подписания карточки товара. используя данный метод, нам необходимо в теле запроса указать код товара, который требуется подписать. В ответ мы получим goodID — внутренний идентификатор системы, сма код товара и структуру документа в формате xml (см. рис. 8).

Рисунок 8

Именно ее и goodID мы используем в теле последнего метода «feed_product_sign», то есть подписания карточки товара. После этого запроса наша карточка будет успешно подписана и опубликована. Это мы можем увидеть по полученному ответу и массиву «signed» (см. рис 9). Также статус карточки можно увидеть в web-интерфейсе системы маркировки «Честный знак»

Рисунок 9

Если же были допущены ошибки при проведении данного процесса, то в ответе мы получим массив «errors» с текстом самой ошибки.

В завершении обзора отличная новость! Облачный сервис Selsup способен взять на себя целый ряд рутинных операций, связанных с маркировкой продукции в частности и работой с маркетплейсами в целом.