Решение для Честного Знака: Массовый вывод кодов маркировки и упрощенная работа с ЭЦП

Данное Python-приложение предназначено для работы с системой Честный Знак, обеспечивая функционал по получению отчетных данных о документах и кодов маркировки, а также по формированию и отправке документов массового вывода из оборота.

Интерфейс для просмотра документов в Честном Знаке.

Актуальность решения

В процессе оборота маркированной продукции пользователи сталкиваются с ситуациями, когда коды маркировки (КМ) остаются в статусе "в обороте". Это может происходить по причинам, не связанным с фактической реализацией или использованием, например, из-за ошибочных универсальных передаточных документов (УПД). Однако, коды также могут "зависать" и быть связанными с фактической реализацией, когда товар был продан конечному потребителю, но по различным причинам (например, отсутствие интеграции с Честным Знаком у покупателя, технические сложности или отсутствие необходимого программного обеспечения на момент продажи) вывод из оборота не был осуществлен своевременно. Стандартные методы вывода таких КМ из оборота могут быть трудоемкими и требовать значительных временных затрат.

Предлагаемое решение обеспечивает возможность массового вывода из оборота КМ, идентифицированных по конкретным документам (например, УПД) и за определенный период. Это позволяет оперативно и корректно списывать КМ, находящиеся в "зависшем" статусе, минимизируя временные издержки на их обработку.

"Информация о кодах маркировки и функция фильтрации по статусу."

Функциональные возможности

• Получение списка документов из Честного Знака: Предоставляется возможность фильтрации документов по периоду, типу, товарной группе.

• Автоматическое извлечение кодов маркировки из содержимого документов: Приложение анализирует XML- и JSON-содержимое документов (УПД, чеков и др.) для автоматического выделения связанных КМ. Данная функция позволяет получать КМ, непосредственно связанные с конкретными входящими или исходящими документами.

• Получение детальной информации о КМ: Осуществляется загрузка актуальных статусов и полной информации для каждого идентифицированного кода маркировки из API Честного Знака.

• Загрузка остатков кодов маркировки в обороте: Для получения всех кодов маркировки, которые числятся на остатках вашей организации по выбранным товарным группам, используйте кнопку "Загрузить остатки КМ в обороте" (расположена на вкладке "Коды маркировки" слева от кнопки "Выгрузить КМ в CSV"). При нажатии на эту кнопку в таблицу загружаются актуальные на текущую дату остатки КМ по выбранным группам.  Обратите внимание: при загрузке остатков через этот способ некоторые поля (например, наименование товара, код ТН ВЭД, вид оборота, состояние кода и др.) могут быть не заполнены — это связано с особенностями работы API Честного Знака. В таблице будут только те данные, которые возвращает сервис остатков. Для получения более подробной информации по каждому коду (например, наименования и других характеристик) используйте загрузку КМ через документы.
  
   

• Фильтрация и анализ КМ: Реализована функция фильтрации КМ по их статусам (например, "В обороте", "Выбыл", "Заблокирован") через специализированный диалог.

• Массовый вывод КМ из оборота:

  • Особенность: Поддерживается вывод из оборота КМ, полученных по документам за указанный период, что является инструментом для работы с "зависшими" кодами.

  • Автоматизация формирования документов: Программа формирует необходимые документы вывода из оборота в формате JSON.

  • Параметризация причин вывода: Предусмотрен выбор причины вывода из оборота (розничная продажа, госконтракт, экспорт и др.) с возможностью заполнения соответствующих полей (FIAS ID, ID контракта, код страны, описание).

  • Разбиение на транши: Реализовано автоматическое разбиение больших объемов КМ на несколько документов для отправки, с учетом лимитов API Честного Знака.

• Экспорт данных: Предусмотрена функция выгрузки списка кодов маркировки в формат CSV для последующего анализа или учета.

• Система логирования: Все операции приложения, включая запросы и ответы API, а также системные сообщения и ошибки, отображаются в реальном времени на отдельной вкладке "Логи".

"Диалог вывода из оборота с автоматической группировкой по товарным группам."

Технические подробности и интеграция (для специалистов)

Архитектура решения:

Решение состоит из двух компонентов:

1. Основная программа на Python (PySide6):

   • Графический интерфейс: Реализован на базе PySide6.

   • Взаимодействие с API Честного Знака: Осуществляет отправку HTTP-запросов к API Честного Знака.

   • Парсинг документов: Анализирует XML- и JSON-содержимое документов для извлечения кодов маркировки.

   • Многопоточность: Использует асинхронную загрузку содержимого документов и информации по КМ, предотвращая зависание UI.

   • Управление данными: Обеспечивает эффективное отображение и обновление табличных данных.

   • Настройки и логирование: Включает интегрированную систему логирования для вывода информации в UI и на диск, а также менеджер настроек.

2. Отдельный компонент на C# (ChZnakAuth.exe):

   • Авторизация и Электронная Подпись (ЭЦП): Данный компонент отвечает за криптографические операции при взаимодействии с Честным Знаком. Он использует нативные возможности C# для работы с системными криптопровайдерами (например, КриптоПро CSP) с целью:

     • Получения токена авторизации API (подпись "челленджа" или формирование JWT-токена).

     • Выполнения квалифицированной электронной подписи (КЭП) формируемых документов вывода из оборота.

   • Межпроцессное взаимодействие: Python-программа вызывает ChZnakAuth.exe посредством subprocess, передавая необходимые параметры (ИНН, ID сертификата, пин-код, данные для подписи) и получая результат (токен, подписанные данные) через стандартный вывод или временные файлы.

   • Обоснование разделения: Использование C# обеспечивает прямой доступ к российской криптографии и изолирует данный функционал от основной логики Python-приложения.

Схема взаимодействия:

1. Пользователь вводит данные в GUI Python-приложения.

2. Python-приложение инициирует вызов ChZnakAuth.exe для получения токена авторизации (на старте или по запросу).

3. Python-приложение использует полученный токен для выполнения запросов к API Честного Знака (получение документов, информации по КМ).

4. При необходимости вывода КМ из оборота, Python-приложение формирует документ в формате JSON.

5. Python-приложение вызывает ChZnakAuth.exe для подписания сформированного JSON-документа.

6. ChZnakAuth.exe возвращает подписанный документ.

7. Python-приложение отправляет подписанный документ на API Честного Знака.

Системные требования и особенности развертывания:

• Операционная система: Windows 10 или новее.

• Криптографическое ПО: Установленный КриптоПро CSP версии 5.x.

• Электронная подпись: Наличие действующего сертификата электронной подписи (ЭЦП) для работы с Честным Знаком. Рекомендуется запускать программу с правами пользователя, имеющего доступ к сертификату ЭЦП.

• Подключение к Интернету: Для корректной работы требуется стабильное интернет-соединение.

• Автономность: Все исполняемые .exe файлы содержат полный набор необходимых компонентов, что не требует дополнительных установок, кроме КриптоПро CSP. Программа готова к работе сразу после распаковки.

Самостоятельное использование C#-компонента (ChZnakAuth.exe)

Компонент ChZnakAuth.exe представляет собой отдельную утилиту, способную выполнять криптографические операции (авторизацию и подписание) независимо от основного Python-приложения. Это позволяет интегрировать функционал работы с ЭЦП Честного Знака в любые другие приложения (например, 1С, собственные скрипты или системы), где требуется получение токена или подписание документов.

Ценность самостоятельного использования:

Данный компонент значительно упрощает интеграцию с Честным Знаком для сторонних систем, которым требуется работа с ЭЦП. Разработчикам не нужно самостоятельно реализовывать сложные криптографические операции и взаимодействие с КриптоПро CSP, достаточно вызывать ChZnakAuth.exe с необходимыми параметрами и парсить его JSON-вывод. Это делает процесс авторизации и подписания документов универсальным и доступным для различных программных сред, включая 1С, PowerShell скрипты, другие языки программирования и консольные утилиты.

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

Состав публикации и файлы для скачивания

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

1. Основная программа (ChZnak_MarkingData_Processor.zip):

   • Архив содержит исполняемый файл Python-программы (.exe) со всеми необходимыми компонентами, а также файл помощи (help_usage.txt). Важно: данный архив НЕ включает C#-компоненту ChZnakAuth.exe. Без этой компоненты функциональность основной программы будет ограничена: автоматическое получение токена авторизации и подписание документов будут недоступны, токен потребуется вводить вручную. Для полноценной работы программы необходимо также скачать и разместить ChZnakAuth.exe в той же папке, что и основное приложение.

2. C#-компонента (ChZnak_AuthSign_Component.zip):

   • Архив включает только исполняемый файл ChZnakAuth.exe. Этот компонент отвечает за взаимодействие с ЭЦП и криптографические операции (авторизация и подпись данных) для API Честного Знака. Его можно использовать как автономную утилиту для интеграции в любые внешние системы, включая 1С.

3. Пример 1С-обработки (ChZnak_1C_AuthExample.epf):

   • Отдельный файл внешней обработки для 1С:Предприятия. Демонстрирует пример программного вызова C#-компоненты ChZnakAuth.exe из среды 1С для получения токена авторизации. Это наглядное пособие для разработчиков, желающих интегрировать функционал работы с ЭЦП Честного Знака в свои 1С-решения.

Важное примечание

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

Программа прошла тестирование на определенных конфигурациях и товарных группах, однако, в силу специфики взаимодействия с API Честного Знака и разнообразия пользовательских сценариев, возможны незначительные задержки в работе интерфейса ("подлагивания") или неполное отображение данных при первом запросе. Рекомендуется внимательно отслеживать информацию на вкладке "Логи" и при необходимости повторять операции для достижения желаемого результата.