Грабли интеграции SellerHub с ГИС МТ для маркировки товаров

На первом прогоне интеграции SellerHub с ГИС МТ DataMatrix-коды уже появились, а часть товарных позиций осталась без привязки. Неприятная ситуация: код есть, продавец ждёт маркировку, но в платформе его нельзя безопасно отдать в работу.

Задача выглядела компактно: подключить ГИС МТ для обязательной маркировки товаров, генерировать DataMatrix-коды, привязывать их к товарным позициям и показывать статус маркировки. В SellerHub это касается 300+ продавцов, поэтому ручная проверка «а что там с кодом» быстро превращается в очередь ошибок. Плюс штрафы за нарушения маркировки растут, и цена неверного статуса становится выше, чем цена лишнего состояния в модели данных.

Разбираем грабли, которые поймали на этой интеграции.

Грабли 1. Считать DataMatrix отдельной сущностью без связи с товаром

Первая ошибка — относиться к DataMatrix как к набору строк, которые можно сгенерировать заранее и потом как-нибудь раздать по позициям. Для витрины или отчёта это ещё выглядит терпимо. Для маркировки — нет.

В SellerHub товарная позиция живёт своей жизнью: продавец ведёт каталог, меняет карточки, работает с разными группами товаров. Если код лежит отдельно от позиции, в интерфейсе легко получить серую зону: код вроде создан, но к какому товару он относится — понятно только из внешнего контекста. А внешний контекст теряется первым.

Мы завязали поток на связку:

• товарная позиция в SellerHub;
• запрос в ГИС МТ;
• полученный DataMatrix;
• статус маркировки для этой конкретной позиции.

Если привязка не прошла, код не показывается как готовый. Это важное ограничение: успешная генерация ещё не означает, что продавец может использовать код без риска. На этом месте как раз был спор — считать ли ответ от ГИС МТ финальной точкой. Оказалось, что финальная точка для SellerHub наступает позже: когда код связан с нужной товарной позицией и статус не конфликтует с текущим состоянием.

Грабли 2. Делать статус маркировки булевым

Вторая ошибка напрашивается сама: добавить поле marked: true/false и закрыть задачу. Но интеграция с ГИС МТ не сводится к двум состояниям.

Есть момент, когда запрос отправлен. Есть момент, когда DataMatrix получен. Есть отдельный момент, когда код привязан к товарной позиции. Есть случаи, когда статус надо уточнить во внешней системе, а не верить локальному кешу.

Если показать продавцу «готово» сразу после генерации, можно получить расхождение: в SellerHub всё зелёное, а процесс маркировки ещё не завершён. Для платформы с 300+ продавцов это не мелкая шероховатость, а источник массовых ручных разборов.

Поэтому статус сделали частью процесса, а не декоративным полем. SellerHub хранит и обновляет состояние маркировки, а интерфейс опирается не на факт существования DataMatrix, а на состояние связки «позиция — код — ответ ГИС МТ».

Грабли 3. Обрабатывать пачку так, будто она всегда однородная

Третья грабля — пакетная обработка. В маркировке хочется взять пачку товаров, отправить запросы и получить аккуратный список кодов. В реальности в одной пачке могут оказаться позиции в разном состоянии: по одной всё готово, по другой не хватает данных, третья ждёт обновления статуса.

Если падать всей пачкой из-за одной позиции, продавец видит общий сбой вместо конкретной причины. Если молча пропускать ошибку, получаем ещё хуже: часть товаров промаркирована, часть нет, а в интерфейсе это выглядит одинаково.

Мы разнесли обработку на уровень товарной позиции. Ошибка по одной позиции не блокирует остальные, но остаётся видимой в контексте этой позиции. Так проще повторить операцию, проверить статус и не смешивать техническую ошибку с бизнес-состоянием маркировки.

Что получилось зафиксировать в процессе

Главная польза интеграции не в том, что SellerHub научился получать DataMatrix-коды. Это только один шаг. Рабочая схема появилась после того, как мы связали генерацию, привязку к товарной позиции и отслеживание статуса в один поток.

Для продавца это выглядит проще: меньше ручного копирования, меньше мест, где можно перепутать код и товар. Для платформы — меньше неявных состояний, которые потом приходится искать в логах и переписках.

Следующий практический шаг в таких интеграциях — внимательно смотреть не на happy path, а на промежуточные состояния: код создан, но не привязан; привязан, но статус ещё не подтверждён; статус обновился, а позиция уже изменилась в каталоге.