API «Честного Знака»: архитектура интеграции с 1С, WMS и производством

Интеграция с ГИС МТ нужна, когда личный кабинет и ручной обмен файлами уже не справляются с объёмом производства. Цель проекта — не просто «подключить API», а обеспечить согласованное движение кодов между учётной системой, производственной линией, складом, ЭДО и «Честным Знаком».

CRM может участвовать в процессе, но обычно не является главным источником данных о маркировке. Для производства ядром чаще становятся 1С или ERP, система управления заказами кодов, программное обеспечение линии и WMS. Поэтому архитектуру нужно строить вокруг жизненного цикла товара и кода, а не вокруг названия одной программы.

Какие интерфейсы участвуют в обмене

В проекте маркировки обычно используются разные контуры:

True API — для операций и документов ГИС МТ, получения статусов и контроля результата;
СУЗ и его интерфейсы — для заказа и получения кодов эмиссии;
API или штатные механизмы 1С/ERP — для производственных заданий, номенклатуры и документов;
WMS — для приёмки, агрегации, перемещения и отгрузки;
ЭДО — для УПД и передачи сведений между участниками оборота;
программное обеспечение линии — для сериализации, печати, верификации и отбраковки.

Набор операций зависит от товарной группы и роли компании. Нельзя переносить готовую интеграцию для розницы на производителя: у производителя появляются заказ кодов, нанесение, агрегация и ввод в оборот.

Эталонная схема интеграции

Надёжная архитектура разделяет бизнес-системы и внешний API промежуточным интеграционным слоем.

ERP или 1С создаёт производственное задание с GTIN, партией, количеством и сроками.
Интеграционный сервис проверяет мастер-данные и формирует заявку на коды.
Полученные коды помещаются в защищённый буфер и выдаются конкретному заданию.
Линия печатает Data Matrix, камера или сканер проверяет читаемость.
Система фиксирует использованные, отбракованные и неиспользованные коды.
При упаковке создаются связи единица → короб → палета.
После контрольной сверки формируются отчёты о нанесении и вводе в оборот.
WMS получает подтверждённые коды и агрегаты для складских операций.
1С/ERP и ЭДО формируют документы отгрузки.
Интеграционный слой контролирует ответы ГИС МТ и не закрывает операцию, пока не получен конечный успешный статус.

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

Почему одного успешного HTTP-ответа недостаточно

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

запрос сформирован;
отправлен;
принят транспортным контуром;
находится в обработке;
выполнен;
отклонён;
требует повторной отправки или ручного решения.

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

Идемпотентность и защита от дублей

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

Практический алгоритм:

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

Без такого механизма обычный сетевой сбой может привести к повторной отправке документа, расхождению статусов или ручной сверке тысяч кодов.

Авторизация и УКЭП

Интеграция с защищёнными методами строится с использованием УКЭП и актуальной схемы аутентификации ГИС МТ. Форматы токенов и методы меняются, поэтому их нельзя навсегда зашивать в статью или техническое задание.

По официальному обновлению от 11 июня 2026 года для единой аутентификации используется запрос пары через /auth/key, подписание полученных данных УКЭП и получение токена UUID. Поддержка JWT заявлена до конца 2026 года. Перед разработкой необходимо сверить текущую документацию True API и требования конкретной товарной группы.

Закрытый ключ УКЭП нельзя передавать в CRM, хранить в исходном коде или журнале. Подписание выполняют в защищённом контуре, а доступы разделяют по ролям. В логах маскируют токены, подписи и чувствительные данные.

Какие данные должны совпадать

Главная причина проблем — несогласованность систем. Для каждой партии нужно сверять:

GTIN и карточку товара;
количество заказанных, полученных и нанесённых кодов;
использованные, отбракованные и свободные коды;
состав агрегатов;
статусы ввода в оборот;
физический складской остаток;
коды в УПД и документах отгрузки;
итоговые статусы в ГИС МТ.

Если линия считает палету собранной, WMS хранит другой состав, а 1С уже сформировала реализацию, ошибка обнаружится слишком поздно. Очерёдность должна быть жёсткой: подтверждение упаковки и агрегации → приём данных складом → разрешение на документ отгрузки.

Мониторинг и работа при сбоях

Интеграция должна сама показывать проблему, а не ждать звонка со склада. Минимальный мониторинг включает:

очередь необработанных операций;
возраст самой старой операции;
число ошибок по типам;
срок действия авторизации;
расхождения между локальным журналом и ГИС МТ;
остаток кодов по заданиям;
простой линии из-за маркировки;
повторные ошибки одной партии.

Ошибки делят на временные, требующие безопасного повтора, и бизнес-ошибки, которые нельзя исправить повторной отправкой. Для критичных ситуаций задают SLA и ответственных: оператор, IT, владелец процесса, склад и производство.

Сценарий работы при отказе должен быть согласован заранее. Локальный буфер может продолжать контролируемую печать только в пределах утверждённых правил; операции, требующие ответа ГИС МТ до следующего этапа, нельзя считать завершёнными без подтверждения.

Интеграция с производственной линией

Для линии важны не только API-вызовы, но и физический контур:

получение кодов в правильной последовательности;
управление принтерами;
верификация качества Data Matrix;
автоматическая отбраковка;
повторная печать по регламенту;
агрегация кодов;
остановка при превышении порога ошибок;
передача факта нанесения без ручного Excel.

Подробно связанные узлы разобраны в материалах об агрегации кодов, проблемах печати Data Matrix и выборе уровня автоматизации.

План внедрения

1. Обследование

Опишите товарные группы, роли компании, объёмы, скорость линий, используемые системы и все операции с кодами. Зафиксируйте текущие ручные файлы и точки повторного ввода.

2. Модель данных и состояний

Определите источник истины для карточки, задания, кода, агрегата и документа. Согласуйте статусы и переходы между ними.

3. Прототип одного сценария

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

4. Тестовый контур и нагрузка

Проверьте интеграцию в доступной тестовой среде, затем оцените скорость при реальном объёме кодов. Отдельно испытайте восстановление после перезапуска.

5. Пилот и промышленный запуск

На пилоте сравнивайте данные линии, интеграционного журнала, ERP/WMS и ГИС МТ. Промышленный запуск проводите с планом отката, дежурными ответственными и запрещёнными ручными обходами.

Критерии приёмки

Интеграцию нельзя принимать только по демонстрации одного запроса. Критерии должны включать:

полный сценарий по реальной товарной группе;
отсутствие потери и повторного использования кодов;
корректное восстановление после сбоя;
конечные статусы документов;
согласованность агрегатов и складских остатков;
журналирование без раскрытия секретов;
мониторинг и уведомления;
инструкции оператору и IT;
измеренный предел производительности.

Когда нужен отдельный проект автоматизации

Если предприятие печатает коды партиями, использует несколько линий, агрегирует упаковки или связывает 1С с WMS и ЭДО, «подключение API» превращается в интеграционный проект. Ошибка в одном узле влияет на выпуск, склад и отгрузку.

Компания «Современные технологии» проводит обследование, проектирует контур и внедряет автоматизацию маркировки от оборудования до ГИС МТ. Запросить разбор текущей схемы можно на странице автоматизации маркировки.

Источники и дата проверки

Материал проверен 2 сентября 2026 года:

Перед реализацией сверяйте актуальные версии True API, СУЗ и правила своей товарной группы в личном кабинете и официальной документации.