Как получить полные коды маркировки из Честного Знака (СУЗ) через API в самописной 1С?

← На главную

Многие разработчики столкнулись с серьезной проблемой: на стороне системы "Честный Знак" было запрещено получение кодов маркировки в удобном текстовом формате CSV. Для выгрузки оставили только графические форматы PDF и EPS. Программно извлечь из них полные коды маркировки (с криптохвостом) для загрузки в самописную учетную систему практически невозможно — для этой задачи есть готовое решение для работы с кодами маркировки напрямую в 1С.

Давайте разберем по шагам, как обойти эту проблему и настроить получение кодов маркировки средствами API "Честного знака" (СУЗ) (удобно через готовый модуль интеграции с Честным знаком по API), возвращая данные в удобном формате JSON. Рассмотрим, какие параметры нам понадобятся и как сформировать запрос.

Где получить данные для подключения к API?

Для выполнения запроса к СУЗ нам потребуются два ключевых параметра: OMSID (Идентификатор СУЗ) и Токен устройства. Проанализируем, где их взять:

Зайдите в веб-интерфейс личного кабинета СУЗ (Станция управления заказами).
Перейдите в профиль участника (обычно находится в правом верхнем углу).
Там вы найдете ваш OMSID.
В этом же разделе необходимо создать устройство и сгенерировать токен для него. Это и будет тот самый Токен, который мы передадим в заголовках нашего HTTP-запроса.

Важно: Работа с API подразумевает наличие настроенной и установленной УКЭП (усиленной квалифицированной электронной подписи).

Пример формирования запроса к API СУЗ (Версия V2)

Посмотрим на пример кода, который формирует HTTP-запрос к API СУЗ для получения пула кодов маркировки из конкретного бизнес-заказа. Если ваша конфигурация полностью самописная, вы можете использовать типовую функцию ИнтеграцияИСМП.ПолучитьДанныеИзСервиса в качестве основы и скопировать ее в свою систему, так как она имеет минимум зависимостей.

Разберем пример кода:


ПараметрыСУЗ = Новый Структура();
ПараметрыСУЗ.Вставить("Идентификатор", СтруктураПодключения.ИдентификаторСУЗ);  // Ваш OMSID из СУЗ
ПараметрыСУЗ.Вставить("ИспользоватьЗащищенноеСоединение", Истина);
ПараметрыСУЗ.Вставить("Порт", 443);
ПараметрыСУЗ.Вставить("ПредставлениеСервиса", "СУЗ");
ПараметрыСУЗ.Вставить("Сервер", "suzgrid.crpt.ru"); // Адрес сервера СУЗ
ПараметрыСУЗ.Вставить("Таймаут", 60);
ПараметрыСУЗ.Вставить("Токен", СтруктураПодключения.ТокенКСУЗ); // Токен устройства
ПараметрыСУЗ.Вставить("ФорматОбмена", "V2");

ЗаголовокHTTP = Новый Соответствие();
ЗаголовокHTTP.Вставить("Content-Type",   "application/x-www-form-urlencoded;charset=UTF-8");
ЗаголовокHTTP.Вставить("Accept",         "application/json");
ЗаголовокHTTP.Вставить("Accept-Charset", "utf-8");
ЗаголовокHTTP.Вставить("clientToken",    ПараметрыСУЗ.Токен);

ПараметрыURL = Новый Массив;
ПараметрыURL.Добавить(СтрШаблон("omsId=%1",    ПараметрыСУЗ.Идентификатор));
ПараметрыURL.Добавить(СтрШаблон("orderId=%1",  ИдентификаторБизнесЗаказа)); // GUID заказа
ПараметрыURL.Добавить(СтрШаблон("gtin=%1",     GTIN)); // GTIN продукции
ПараметрыURL.Добавить(СтрШаблон("quantity=%1", Формат(КоличествоКодовМаркировки, "ЧГ=0;")));

// Обработка блоков, если кодов много
Если ЗначениеЗаполнено(ИдентификаторБлокаКодов) Тогда
    ПараметрыURL.Добавить(СтрШаблон("lastBlockId=%1", ИдентификаторБлокаКодов));
КонецЕсли;

// Формируем URL в зависимости от товарной группы
// "lp" - легкая промышленность, "shoes" - обувь
URLЗапроса = СтрШаблон("api/v2/lp/codes?%1", СтрСоединить(ПараметрыURL, "&"));

// Выполняем запрос
РезультатЗапроса = ИнтеграцияИСМП.ПолучитьДанныеИзСервиса(URLЗапроса, Неопределено, ПараметрыСУЗ, ЗаголовокHTTP);

В ответ на такой запрос возвращается JSON со списком марок. Это будут полные коды маркировки вместе со специальными символами криптохвоста. Обратите внимание, что в URL мы указываем товарную группу: например, lp используется для текстиля и легкой промышленности, а shoes — для обуви.

Переход на API СУЗ V3 и актуальные требования

Проанализируем текущую ситуацию. Важно учитывать, что методы API версии V2 больше не актуальны. Начиная с 1 сентября 2024 года, СУЗ полностью вывел из эксплуатации API V2, и теперь обмен осуществляется только по протоколу API СУЗ V3.

Посмотрим, какие архитектурные изменения нам необходимо учесть при доработке нашей 1С:

Универсальный URL: В версии V3 структура URL стала универсальной. Нам больше не нужно привязывать URL-адрес к категории товара (указывать lp или shoes).
Передача параметров в теле JSON: Все специфические параметры для конкретной товарной группы теперь передаются не в URL, а в теле JSON-запроса, внутри отдельного блока attributes.
Новые лимиты: Существенно расширены возможности для массовой генерации кодов. Теперь максимальное количество кодов, которые можно запросить за один раз на один GTIN, увеличено до 2 000 000 штук.
Спецсимволы криптохвоста: При получении полных кодов в JSON крайне важно корректно обрабатывать непечатные символы (по стандарту GS1 DataMatrix). Мы настоятельно рекомендуем использовать строгую кодировку Юникод (UTF-8) и отключать автоматическое распознавание типов данных при записи или импорте/экспорте, иначе спецсимволы в криптохвосте будут искажены, и код станет недействительным.

Использование готовых модулей вместо написания "с нуля"

Даже если у вас полностью переписанная или самописная конфигурация 1С, вам не обязательно писать всю интеграцию с API V3 с нуля — для этого подойдёт готовый модуль интеграции 1С с ГИС МТ и СУЗ. Фирма "1С" постоянно обновляет подсистему "Интеграция с ИС МП" (которая входит в БПО).

Рассмотрим оптимальный подход: начиная с современных релизов (например, УТ 11.5.17 и старше), поддержка API СУЗ версии 3.0 уже встроена в общие модули. Чтобы сэкономить время, мы рекомендуем взять свежую типовую конфигурацию, найти там общие модули, связанные с ИнтеграцияИСМП, скопировать их в свою самописную базу и слегка адаптировать вызовы функций под вашу структуру метаданных. Это убережет вас от необходимости вручную собирать сложные JSON-запросы под новые требования "Честного знака".