Как изменить описание товара для кода маркировки Честный Знак и особенности работы с API СУЗ

При работе с системой маркировки «Честный Знак» (ГИС МТ) многие технические специалисты сталкиваются с ситуацией, когда при передаче данных через API поле с описанием товара игнорируется системой. Вместо переданного текста в Личном кабинете и приложении отображается стандартное наименование, присвоенное коду при его генерации. В этой статье мы подробно разберем, почему это происходит, как на самом деле устроена архитектура данных в Честном Знаке и какие методы API следует использовать для корректного управления заказами марок.

Почему описание товара нельзя изменить через обычный API-запрос

Проанализируем архитектуру системы маркировки. В «Честном Знаке» существует жесткая иерархия данных. Каждый индивидуальный Код Маркировки (КМ) является экземпляром определенной товарной позиции, которая идентифицируется по GTIN (Global Trade Item Number). Все характеристики товара, включая его наименование, состав, бренд и текстовое описание, хранятся не в самом коде маркировки, а в Национальном каталоге и жестко привязаны к GTIN.

Рассмотрим причины, по которым ваши попытки передать описание через поле product_description в API могут не давать результата:

1. Приоритет Национального каталога: Система ГИС МТ всегда подтягивает описание из карточки товара, зарегистрированной владельцем GTIN. Даже если в документе ввода в оборот вы укажете иное описание, система отобразит данные из каталога.
2. Права владения карточкой: Изменять описание товара может только владелец GTIN (как правило, это производитель или импортер). Если вы являетесь перепродавцом (оптовиком или розницей), вы технически не имеете прав на редактирование карточки чужого товара.
3. Статичность документа: В логике «Честного Знака» отсутствует понятие редактирования уже созданного и подписанного документа. Если в документе допущена ошибка, его нельзя исправить — необходимо аннулировать старый и подать новый.

Важный вывод: Если вам необходимо изменить описание, которое видят покупатели в мобильном приложении, это нужно делать через редактирование карточки товара в Национальном каталоге (подсистема ГИС МТ). После публикации изменений в каталоге описание обновится автоматически для всех кодов с этим GTIN.

Работа с заказами через API СУЗ (Станция управления заказами)

Для разработчиков 1С, реализующих прямой обмен с Честным Знаком, критически важно правильно выстроить процесс получения кодов. Разберем по шагам, как взаимодействовать с API v2 для эффективного управления заказами.

Проанализируем ситуацию: когда вы создаете заказ в СУЗ, система формирует так называемый «буфер» кодов. Ваша задача — отследить готовность этого буфера и забрать коды. Рассмотрим основные методы.

Проверка готовности марок (Статус буфера)

Вместо того чтобы пытаться получить статус всего заказа (что система делать не рекомендует в штатном режиме), мы будем проверять статус конкретного GTIN в рамках заказа. Используем метод получения статуса буфера:

GET http://[адрес_сервера]/api/v2/[товарная_группа]/buffer/status?omsId=[ID_СУЗ]&orderId=[ID_заказа]>in=[GTIN]

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

Получение кодов маркировки

Когда статус буфера подтверждает наличие кодов, мы выполняем запрос на их получение. Обратите внимание на параметр lastBlockId — он необходим для порционного получения данных, если заказ большой.

GET http://[адрес_сервера]/api/v2/[товарная_группа]/codes?omsId=[ID_СУЗ]&orderId=[ID_заказа]>in=[GTIN]&quantity=[количество]&lastBlockId=[ID_блока]

Практический совет: Если в процессе получения кодов произошел сбой (например, обрыв интернет-соединения), Честный Знак не позволит получить те же самые коды простым повторным запросом codes. В этом случае необходимо использовать метод retry:

GET http://[адрес_сервера]/api/v2/[товарная_группа]/codes/retry?orderId=[ID_заказа]>in=[GTIN]&blockId=[ID_блока]

Закрытие подзаказа (буфера)

После того как вы успешно получили все заказанные марки по конкретному GTIN, крайне желательно закрыть этот буфер вручную. Хотя система делает это автоматически через некоторое время, ручное закрытие освобождает ресурсы СУЗ (лимит на количество активных заказов).

GET http://[адрес_сервера]/api/v2/[товарная_группа]/buffer/close?orderId=[ID_заказа]>in=[GTIN]&omsId=[ID_СУЗ]&lastBlockId=[ID_блока]

Обработка ошибок и статусов в 1С

При реализации обмена в 1С важно правильно обрабатывать ответы сервера. Выясним причину возможных проблем:

1. Ошибки 404 и 500: Чаще всего являются временными сбоями на стороне серверов ГИС МТ. Рекомендуется игнорировать их в моменте и повторять запрос через интервал (например, 5-10 минут).
2. Статус заказа СУЗ: Если вам все же нужно получить статус всего документа заказа, используйте метод orders?omsId, но помните об ограничении (не более 100 запросов в секунду). Однако Честный Знак в документации прямо указывает, что этот метод предназначен для восстановления данных после сбоев, а не для регулярного опроса.
3. Логика «Черновиков»: Помните, что в API нет понятия «черновика». Любой отправленный JSON — это попытка регистрации. Если ваша система 1С хранит локально объект «Заказ марок», то его статусы (Черновик, К подписи, Выполнен) должны управляться внутренней логикой 1С на основе ответов от API.

Рекомендации по реализации в коде 1С

Рассмотрим пример логики получения марок в цикле. Мы должны проверять каждую позицию (GTIN) в документе 1С ЗаказНаЭмиссиюКодовМаркировки.

Алгоритм действий:

1. Перебираем строки документа.
2. Для каждого GTIN запрашиваем статус буфера.
3. Если буфер готов, вызываем метод получения кодов.
4. Сохраняем полученные коды в регистр или привязываем к документу.
5. Если количество полученных кодов совпадает с заказанным — вызываем buffer/close.
6. Когда все строки (GTIN) обработаны и закрыты — переводим статус документа в 1С в состояние «Коды получены».

Использование такого подхода гарантирует, что вы не потеряете коды при сбое связи и не превысите лимиты системы СУЗ на количество открытых заказов (особенно актуально для крупных импортеров, заказывающих сотни GTIN одновременно).