Как реализовать ввод остатков обуви по упрощенной схеме через API Честного ЗНАКа в 1С:УТ 10.3?

При переходе на обязательную маркировку обуви многие компании столкнулись с необходимостью автоматизации ввода остатков через API. Особенно это актуально для конфигураций на обычных формах, таких как УправлениеТорговлей10.3, где типовые механизмы интеграции могут отсутствовать или быть ограниченными. В данной статье мы подробно разберем, как программно реализовать упрощенное описание остатков и заказ кодов маркировки.

Понимание архитектуры API: ГИС МТ и СУЗ

Прежде чем приступать к написанию кода, проанализируем структуру сервисов «Честного ЗНАКа». Работа ведется с двумя разными API:

1. ГИС МТ (True API): используется для работы с документами (черновики, ввод в оборот, списание). Адрес взаимодействия обычно содержит api/v3 или выше.
2. СУЗ (Станция управления заказами): отвечает непосредственно за генерацию и выдачу кодов маркировки (DataMatrix). Здесь используются методы api/v2/light/orders.

Для ввода остатков по упрощенной схеме нам необходимо выполнить два последовательных этапа: сначала описать товар (получить «технический» GTIN), а затем заказать коды на этот GTIN.

Шаг 1: Создание черновика описания остатков

Рассмотрим ситуацию, когда нам нужно передать минимальный набор атрибутов для остатков: ИНН организации, пол обуви, способ ввода в оборот и первые два знака кода ТН ВЭД (для обуви это «64»).

Для создания черновика документа в Личном Кабинете ГИС МТ используем метод POST /api/v3/lk/documents/draft/. Разберем структуру JSON-пакета, который необходимо сформировать в 1С:

// Пример формирования JSON для упрощенного описания
{
    "date_saved": "2023-10-25T12:00:00.000Z",
    "document_type": "OST_DESCRIPTION",
    "organisation_inn": "7700000000",
    "document_body": "{
        \"trade_participant_inn\": \"7700000000\",
        \"products_list\": [
            {
                \"product_gender\": \"MALE\",
                \"tnved_code_2\": \"64\",
                \"release_method\": \"PRODUCED_IN_RF\"
            },
            {
                \"product_gender\": \"FEMALE\",
                \"tnved_code_2\": \"64\",
                \"release_method\": \"IMPORTED_INTO_RF\"
            }
        ]
    }"
}

Важные моменты при формировании запроса:

• Поле document_body должно быть передано как строковое значение, содержащее вложенный JSON. Это часто становится причиной ошибок при парсинге на стороне сервера.
• Параметр product_gender принимает значения: MALE (мужская), FEMALE (женская), UNISEX (унисекс) или CHILD (детская).
• Для release_method используйте PRODUCED_IN_RF (произведено в РФ) или IMPORTED_INTO_RF (ввезено в РФ).

Шаг 2: Получение технического GTIN

После успешной отправки черновика и его обработки в системе, товарам присваиваются технические GTIN, начинающиеся на «029...». Выясним, почему это важно: без этого номера вы не сможете заказать коды маркировки. В системе 1С необходимо предусмотреть хранение этих кодов в привязке к категориям товаров или конкретным номенклатурным позициям.

Шаг 3: Заказ кодов маркировки через СУЗ

Когда у нас есть GTIN, мы переходим к заказу самих марок. Проанализируем метод POST /api/v2/light/orders. Здесь структура запроса отличается, так как мы обращаемся к станции управления заказами.

Посмотрим на пример структуры заказа:

{
  "products": [
    {
      "gtin": "02900001234567",
      "quantity": 50,
      "serialNumberType": "SELF_MADE",
      "templateId": 1,
      "is_complete": false
    }
  ],
  "contactPerson": "Иванов И.И.",
  "releaseMethodType": "PRODUCTION",
  "createMethodType": "SELF_MADE"
}

В этом запросе quantity — это количество кодов, которое вы хотите получить. Параметр serialNumberType со значением SELF_MADE означает, что вы могли бы сами генерировать серийные номера, но чаще используется OPERATOR_MADE, чтобы система сгенерировала их автоматически.

Шаг 4: Реализация HTTP-запроса в 1С 8.3 (Обычные формы)

Поскольку в УТ 10.3 работа с интернет-сервисами реализуется через объект HTTPСоединение, разберем типовой алгоритм отправки данных. Выясним, как правильно передать заголовки авторизации.

// Пример функции отправки запроса
Процедура ОтправитьЗапросНаМаркировку(СтруктураДанныхJSON)
    
    Сервер = "честныйзнак.рф"; // Укажите актуальный адрес API
    Токен = "Ваш_Авторизационный_Токен";
    
    Соединение = Новый HTTPСоединение(Сервер, 443, , , , , Новый ЗащищенноеСоединениеOpenSSL());
    
    Заголовок = Новый Соответствие;
    Заголовок.Вставить("Content-Type", "application/json;charset=UTF-8");
    Заголовок.Вставить("Authorization", "Bearer " + Токен);
    
    Запрос = Новый HTTPЗапрос("/api/v3/lk/documents/draft/", Заголовок);
    Запрос.УстановитьТелоИзСтроки(СтруктураДанныхJSON, КодировкаТекста.UTF8);
    
    Попытка
        Ответ = Соединение.ОтправитьДляОбработки(Запрос);
        Если Ответ.КодСостояния = 200 Тогда
            Сообщить("Документ успешно отправлен. ID: " + Ответ.ПолучитьТелоИзСтроки());
        Иначе
            Сообщить("Ошибка при отправке: " + Ответ.КодСостояния);
            Сообщить(Ответ.ПолучитьТелоИзСтроки());
        КонецЕсли;
    Исключение
        Сообщить("Ошибка связи с сервером!");
    КонецПопытки;
    
КонецПроцедуры

Нюансы и ограничения упрощенной схемы

Проанализируем важные правовые и технические аспекты, которые актуальны на текущий момент:

• Срок действия: Упрощенная схема была временным решением для остатков. Согласно законодательству, все коды, полученные по упрощенной атрибутивной модели, должны были быть перемаркированы по полному составу до 31 марта 2023 года. В настоящий момент упрощенный ввод остатков недоступен, однако знание принципов работы с черновиками OST_DESCRIPTION необходимо для поддержки существующих баз данных.
• Стоимость: На этапе запуска маркировки в 2019-2020 годах коды на остатки выдавались бесплатно. Сейчас стандартная стоимость одного кода составляет 50 копеек без НДС.
• Лимиты: При массовой загрузке остатков (тысячи позиций) API может возвращать ошибку 429 (Too Many Requests). В коде 1С следует реализовать паузы (через Сигнал() или обработчики ожидания) между отправкой пакетов.

Обработка асинхронных ответов

Система Честный ЗНАК работает асинхронно. Это означает, что после отправки документа методом POST вы получаете не результат выполнения, а идентификатор документа (documentId). Разберем, как проверить статус:

1. Сохраняем documentId в информационной базе (например, в регистре сведений).
2. Реализуем регламентное задание, которое раз в 5-10 минут опрашивает метод GET /api/v3/lk/documents/{documentId}/status.
3. Только после получения статуса PROCESSED (Обработан) можно считать операцию завершенной и переходить к заказу кодов.

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