Честный ЗНАК из WooCommerce в кассу: как правильно передавать данные о маркировке

Честный ЗНАК из WooCommerce в кассу нужно передавать через корректную фискализацию. Разберём схему интеграции, данные чека и ошибки. Читайте инструкцию и проверьте свою интеграцию.

Продажа маркированных товаров через интернет-магазин сложнее обычной оплаты. WooCommerce знает товар и заказ. Касса отвечает за фискальный чек. Система «Честный ЗНАК» контролирует движение маркированного товара. Между этими системами должен работать понятный обмен данными.

Если связать системы неправильно, заказ может оплатиться. При этом чек не передаст код маркировки. В результате данные о выбытии товара не попадут в систему маркировки.

Ниже разберём, как построить интеграцию правильно. Покажем типовую архитектуру и пример кода для WooCommerce.

Как работает передача Честного ЗНАКА из WooCommerce в кассу

Главная ошибка — считать WooCommerce кассовой системой. WooCommerce управляет интернет-магазином. Он хранит товары, заказы, клиентов и статусы оплаты.

Касса выполняет другую задачу. Она формирует фискальный документ. Затем данные передаются оператору фискальных данных и в систему маркировки.

Типовая схема выглядит так:

WooCommerce → сервис фискализации → онлайн-касса → ОФД → Честный ЗНАК

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

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

Важно разделить три сущности:

• товар в WooCommerce;
• конкретный код маркировки;
• фискальная позиция в чеке.

Один товар WooCommerce может иметь разные коды маркировки. Поэтому нельзя хранить код маркировки только как обычный артикул товара.

Что именно передавать в кассу

При интеграции нужно передать не просто название товара.

Для фискализации обычно требуется набор данных:

Данные	Источник	Назначение
Наименование	WooCommerce	Позиция чека
Цена	WooCommerce	Расчёт
Количество	WooCommerce	Количество товара
Ставка НДС	WooCommerce	Налоговые данные
Признак предмета расчёта	Настройки магазина	Тип операции
Код маркировки	Заказ или кассовая система	Маркировка
Способ оплаты	WooCommerce	Форма расчёта
Email/телефон	Заказ	Электронный чек

Для ФФД 1.2 структура данных маркированного товара отличается от старых форматов. ФНС отдельно описывает реквизиты, связанные с кодом товара, проверкой и результатом обработки маркировки.

Поэтому интеграцию нельзя строить по принципу «добавим строку с кодом в чек».

Нужно учитывать формат фискальных документов, требования кассового ПО и конкретного провайдера.

Честный ЗНАК из WooCommerce в кассу: где хранить код маркировки

Код маркировки относится к конкретному экземпляру товара.

Представим заказ:

• Футболка — 2 шт.
• Куртка — 1 шт.

У каждой единицы может быть собственный Data Matrix.

Поэтому структура заказа должна позволять связать:

товар → количество → конкретный код маркировки.

Хранить один код в метаполе товара нельзя. Такой подход ломается уже при продаже двух экземпляров.

Лучше использовать структуру данных на уровне позиции заказа.

Например:

$order_item->add_meta_data(
    '_marking_code',
    $marking_code,
    true
);

Но это только пример хранения.

Само наличие метаполя не передаёт данные в кассу. WooCommerce должен передать код в запросе к используемому сервису фискализации.

Почему нельзя просто добавить код в название товара

Иногда разработчик решает проблему так:

$product_name .= ' ' . $marking_code;

Это неправильный подход.

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

Кроме того, такой код попадёт в обычные данные товара. Это создаёт путаницу в заказах и аналитике.

Код маркировки должен передаваться в предусмотренном API-поле кассового решения.

Откуда WooCommerce получает код маркировки

Есть несколько вариантов.

Сканирование при комплектации

Оператор собирает заказ. Он сканирует Data Matrix.

Система получает код и связывает его с товарной позицией заказа.

Это удобный вариант для склада.

Ввод через интерфейс заказа

Оператор может указать код вручную.

Такой способ подходит для небольшого объёма заказов. Но он повышает риск ошибки.

Получение из внешней системы

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

Такой вариант удобен при интеграции с 1С или складской системой.

На практике важно определить источник истины.

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

Что происходит после оплаты заказа

Рассмотрим типовой сценарий.

Вы столкнулись с проблемой: WooCommerce переводит заказ в статус «Оплачен», но касса не получает код маркировки.

Мы решаем её: добавляем отдельный этап подготовки фискальной позиции. На этом этапе система собирает данные товара, НДС, цены и код маркировки. Затем формирует запрос к API кассового сервиса.

Результат: касса получает структурированные данные. Фискальный документ содержит необходимые сведения о маркированном товаре.

Логика может выглядеть так:

$order = wc_get_order($order_id);

foreach ($order->get_items() as $item_id => $item) {

    $product = $item->get_product();

    $marking_code = $item->get_meta('_marking_code');

    $receipt_item = [
        'name'     => $item->get_name(),
        'quantity' => (float) $item->get_quantity(),
        'price'    => (float) $order->get_line_total($item),
        'vat'      => get_product_vat_rate($product),
    ];

    if ($marking_code) {
        $receipt_item['marking_code'] = $marking_code;
    }

    $receipt_items[] = $receipt_item;
}

Это условный пример архитектуры. Название поля marking_code зависит от API кассового сервиса.

Нельзя копировать этот массив напрямую в любую кассу. Сначала нужно изучить документацию конкретного провайдера.

Как не потерять код маркировки при передаче

У интеграции должен быть контроль каждого этапа.

Рекомендуем проверять:

1. Код получен.
2. Код связан с правильным товаром.
3. Код связан с правильным количеством.
4. Код не потерялся при формировании запроса.
5. API кассы приняло данные.
6. Касса сформировала чек.
7. Фискальный документ получил нужный реквизит.
8. Данные корректно ушли дальше по цепочке.

Особенно важен пункт номер пять.

WooCommerce не должен считать чек успешно созданным только потому, что API вернул HTTP 200.

Нужно анализировать тело ответа.

Например:

$response = wp_remote_post(
    $cash_api_url,
    [
        'headers' => [
            'Content-Type' => 'application/json',
        ],
        'body' => wp_json_encode($receipt),
        'timeout' => 30,
    ]
);

if (is_wp_error($response)) {
    throw new Exception(
        'Ошибка соединения с кассовым сервисом'
    );
}

$body = json_decode(
    wp_remote_retrieve_body($response),
    true
);

if (empty($body['success'])) {
    throw new Exception(
        'Касса не подтвердила создание чека'
    );
}

В реальном проекте структура ответа будет другой.

ФФД 1.2: почему старая интеграция может перестать работать

Одна из частых проблем — старая интеграция с кассой.

В документации ФНС указано, что в ФФД 1.2 изменилась структура данных по маркированным товарам. В ней предусмотрены отдельные документы и реквизиты для работы с кодами маркировки.

Это означает простой вывод:

нельзя ориентироваться только на старую интеграцию с тегом 1162.

Для ФФД 1.2 применяются новые реквизиты. В материалах ФНС указаны, в частности, тег 1163, контрольный код КМ и результат проверки сведений о товаре.

Поэтому перед разработкой нужно узнать:

• версию ФФД;
• модель кассы;
• версию прошивки;
• используемый фискальный накопитель;
• кассовое ПО;
• API кассового сервиса;
• способ передачи маркировки.

Без этой информации разработчик рискует сделать интеграцию под устаревшую схему.

Ошибка: передавать маркировку только после оплаты

Это ещё одна распространённая проблема.

Допустим, WooCommerce получил оплату. После этого запускается фискализация.

Но код маркировки ещё не связан с заказом.

Система пытается отправить чек без него.

В итоге появляется цепочка ошибок:

оплата → попытка чека → нет кода → ошибка фискализации → ручная обработка.

Правильнее заранее определить момент получения кода.

Например:

оплата → сбор заказа → сканирование → подготовка чека → фискализация.

Конкретная схема зависит от модели торговли и способа расчёта.

Для интернет-магазина особенно важно учитывать дистанционную продажу. ФНС отдельно разъясняла правила указания кода маркированного товара при доставке и расчётах через интернет-магазин.

Ошибка: один код на несколько единиц товара

Представим заказ:

Кроссовки × 3.

У вас есть три физических пары. У каждой свой код маркировки.

Нельзя отправить один код три раза.

Нужно передать три соответствующих идентификатора. Система должна понимать связь между количеством товара и кодами.

Поэтому ещё на этапе проектирования нужно определить структуру:

Товар
 ├── Единица 1 → код маркировки A
 ├── Единица 2 → код маркировки B
 └── Единица 3 → код маркировки C

Это особенно важно для складских сценариев.

Как проверить интеграцию WooCommerce и кассы

Не стоит тестировать только успешный заказ.

Создайте отдельный набор тестов.

Чек-лист

• Обычный товар продаётся без ошибок.
• Маркированный товар передаётся в кассу.
• Код маркировки сохраняется в заказе.
• Код привязан к правильной позиции.
• Несколько единиц получают разные коды.
• Возврат корректно обрабатывается.
• Отмена заказа не создаёт ошибочный чек.
• Повторная отправка не создаёт дубликат.
• Ошибка API фиксируется в журнале.
• Статус фискализации сохраняется.
• Электронный чек содержит корректные данные.
• Касса работает с используемой версией ФФД.

Последний пункт особенно важен.

Сколько стоит ошибка в интеграции

Цена ошибки выше стоимости одного невыставленного чека.

Проблема может затронуть:

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

ФНС указывает, что отсутствие обязательных сведений о маркированном товаре в чеке может рассматриваться как нарушение требований к применению ККТ.

Для примера: в разъяснениях ФНС по отдельным случаям указаны штрафы от 1 500 до 3 000 рублей для должностных лиц и от 5 000 до 10 000 рублей для организаций. Конкретная ответственность зависит от обстоятельств и применимых норм.

Поэтому интеграцию лучше проектировать до запуска продаж.

Как мы интегрируем WooCommerce с кассой

В студии «Компьюти» мы начинаем не с написания PHP-кода.

Сначала анализируем бизнес-процесс.

Этап 1. Проверяем текущую систему

Изучаем:

• WooCommerce;
• плагины оплаты;
• кассу;
• ОФД;
• систему маркировки;
• складской учёт;
• 1С или другую ERP;
• текущую интеграцию.

Этап 2. Определяем источник кода

Нужно понять, где появляется код маркировки.

Он может поступать со склада. Его может сканировать оператор. Его может предоставлять внешняя система.

Этап 3. Проектируем обмен

Определяем:

какие данные → откуда → куда → в какой момент → с каким результатом.

Этап 4. Реализуем интеграцию

Используем API и хуки WooCommerce. При необходимости пишем собственный плагин.

Например, обработчик может запускаться после изменения статуса заказа:

add_action(
    'woocommerce_order_status_processing',
    'company_send_receipt'
);

function company_send_receipt($order_id)
{
    $order = wc_get_order($order_id);

    if (!$order) {
        return;
    }

    // Получаем позиции заказа.
    // Проверяем маркировку.
    // Формируем данные чека.
    // Отправляем запрос в кассовый API.
    // Сохраняем результат фискализации.
}

На реальном проекте такой код дополняется защитой от повторной отправки.

Также нужны журналирование, обработка ошибок и контроль статусов.

Этап 5. Тестируем реальные сценарии

Мы проверяем не только успешную оплату.

Отдельно тестируем:

• оплату;
• отмену;
• возврат;
• повторную отправку;
• несколько маркированных товаров;
• частичный возврат;
• ошибку кассы;
• недоступность API;
• повторную попытку фискализации.

Такой подход снижает количество проблем после запуска.

Что важно подготовить до начала работ

Чтобы интеграция прошла быстрее, подготовьте:

1. Версию WooCommerce.
2. Список используемых плагинов оплаты.
3. Модель кассы.
4. Версию ФФД.
5. Кассовое ПО.
6. Данные API используемого сервиса.
7. Сценарий доставки.
8. Сценарий возврата.
9. Источник кодов маркировки.
10. Описание складского процесса.

Также полезно предоставить тестовый заказ.

Чем точнее исходные данные, тем меньше переделок потребуется разработчику.

Заключение

Честный ЗНАК из WooCommerce в кассу нельзя передавать как обычное поле товара. Код маркировки должен пройти через корректную цепочку фискализации.

Главные правила просты:

• связывайте код с конкретной единицей товара;
• учитывайте актуальную версию ФФД;
• используйте API кассового решения;
• контролируйте ответ кассы;
• не допускайте повторной фискализации;
• отдельно тестируйте возвраты и ошибки.

ФНС подтверждает обязательность корректного отражения сведений о маркированных товарах в кассовых документах.

Если Честный ЗНАК из WooCommerce в кассу сейчас передаётся с ошибками или интеграции ещё нет, студия «Компьюти» может провести аудит и разработать решение под вашу связку WooCommerce, кассы и складской системы.

Нужна интеграция без ручной обработки заказов? Оставьте заявку в «Компьюти». Мы разберём текущую схему и предложим безопасный вариант интеграции.