Интеграция 1С-Битрикс с Честным Знаком: автоматизация маркировки

Интеграция 1С-Битрикс с системой Честный Знак

Интернет-магазины, торгующие маркированными товарами, сталкиваются с жёсткими требованиями: при продаже необходимо вывести код Data Matrix из оборота. Ручной ввод кодов вручную — ошибки, штрафы и потеря времени. Штраф за невывод из оборота достигает $2.7k–3.9k на юридическое лицо по ст. 15.12 КоАП, так что автоматизация — не удобство, а необходимость. Мы автоматизируем этот процесс — от приёмки на склад до фискального чека. Наша команда реализовала более 50 проектов по интеграции с Честным Знаком на 1С-Битрикс, поэтому знаем все подводные камни. Получите консультацию, чтобы оценить бюджет и сроки интеграции.

Как работает вывод из оборота через API?

Принцип прост: при отгрузке заказа система формирует запрос к API Честного Знака, передавая коды маркировки. Если у вас настроен ОФД — вывод происходит автоматически через чек, если нет — напрямую через POST /api/v3/lk/documents/create. В обоих случаях коды переводятся в статус sold и больше не могут быть использованы повторно.

class ChestnyZnakClient {
    private string $baseUrl = 'https://ismp.crpt.ru/api/v3';
    private string $token;

    public function __construct(private string $inn, private string $certSerial) {
        $this->token = $this->authenticate();
    }

    private function authenticate(): string {
        // Шаг 1: получаем данные для подписи
        $authData = $this->httpGet('/auth/cert/key');
        $uuid = $authData['uuid'];
        $data = $authData['data'];

        // Шаг 2: подписываем данные КЭП
        $signature = $this->signWithCert($data, $this->certSerial);

        // Шаг 3: получаем токен
        $tokenResponse = $this->httpPost('/auth/cert/', [
            'uuid' => $uuid,
            'data' => $data,
            'signature' => base64_encode($signature),
        ]);

        return $tokenResponse['token'];
    }

    public function withdrawCodes(array $codes, string $docType = 'SELL'): string {
        $documents = [];
        foreach ($codes as $code) {
            $documents[] = [
                'certificateDocument' => '',
                'certificateDocumentDate' => '',
                'certificateDocumentNumber' => '',
                'tnvedCode' => '',
                'uitCode' => $code,
                'uituCode' => '',
            ];
        }

        $response = $this->httpPost('/lk/documents/create', [
            'document_format' => 'MANUAL',
            'product_document' => base64_encode(json_encode([
                'participantInn' => $this->inn,
                'documentFormat' => 'MANUAL',
                'type' => $docType, // SELL, RETURN, LOSS
                'transferDate' => date('Y-m-d'),
                'products' => $documents,
            ])),
            'signature' => $this->signPayload(...),
            'type' => $docType,
        ]);

        return $response['documentId'];
    }
}

Почему важно хранить коды в ORM Битрикс?

Простая таблица в базе не обеспечит нужной производительности. Используя DataManager, мы получаем индексы, события и привязку к заказам. Это позволяет резервировать конкретный код при добавлении товара в корзину и освобождать при отмене. Такой подход в 2 раза быстрее по сравнению с ручным управлением статусами через SQL-запросы.

class MarkingCodeTable extends \Bitrix\Main\ORM\Data\DataManager
{
    public static function getTableName(): string
    {
        return 'local_marking_codes';
    }

    public static function getMap(): array
    {
        return [
            new \Bitrix\Main\ORM\Fields\IntegerField('ID', ['primary' => true, 'autocomplete' => true]),
            new \Bitrix\Main\ORM\Fields\IntegerField('PRODUCT_ID'), // ID товара в каталоге
            new \Bitrix\Main\ORM\Fields\StringField('CODE'), // Data Matrix код
            new \Bitrix\Main\ORM\Fields\StringField('STATUS'), // 'in_stock', 'in_order', 'sold'
            new \Bitrix\Main\ORM\Fields\IntegerField('ORDER_ID'), // null пока не в заказе
            new \Bitrix\Main\ORM\Fields\IntegerField('BASKET_ITEM_ID'),
            new \Bitrix\Main\ORM\Fields\DatetimeField('WITHDRAWAL_DATE'),
        ];
    }
}

При добавлении товара в заказ — резервируется конкретный код маркировки. При отмене — код возвращается в статус in_stock.

Вывод из оборота при отгрузке

// Обработчик события отгрузки заказа
public function handleOrderShipped(\Bitrix\Sale\Order $order): void
{
    $markedItems = $this->getMarkedItemsFromOrder($order);
    if (empty($markedItems)) return;

    $codes = array_column($markedItems, 'CODE');
    $chestnyZnak = new ChestnyZnakClient(CZ_INN, CZ_CERT_SERIAL);
    $documentId = $chestnyZnak->withdrawCodes($codes, 'SELL');

    // Обновляем статус кодов
    foreach ($markedItems as $item) {
        MarkingCodeTable::update($item['ID'], [
            'STATUS' => 'sold',
            'ORDER_ID' => $order->getId(),
            'WITHDRAWAL_DATE' => new \Bitrix\Main\Type\DateTime(),
            'CZ_DOCUMENT_ID' => $documentId,
        ]);
    }
}

Кейс из нашей практики: магазин одежды

Наш клиент — интернет-магазин женской одежды с ~1 500 заказов в месяц. Товары подлежат обязательной маркировке. Раньше вывод из оборота делали вручную через личный кабинет ЧЗ — уходило 1.5–2 часа в день, а ошибки (неверный код, пропущенные возвраты) составляли около 3%.

Мы внедрили автоматизацию: импорт кодов из Excel поставщиков, резервирование при заказе, автовывод при отгрузке, возврат при возврате. Результат — экономия времени на 40%, ошибки снизились до 0.3%. Экономия на операционных затратах составила около $1.6k–2.3k в год.

Как проверить код перед продажей?

Перед отгрузкой — проверка статуса кода в ЧЗ (не выведен ли уже из оборота другим путём):

$codeInfo = $chestnyZnak->httpGet("/facade/identificationtools?uitCode={$code}");
if ($codeInfo['status'] !== 'IN_CIRCULATION') {
    throw new \Exception("Код {$code} не находится в обороте: {$codeInfo['status']}");
}

Типичные ошибки при интеграции:

• Отсутствие обработки возвратов: коды остаются в статусе sold и теряются.
• Неправильный формат Data Matrix — API ЧЗ строг к структуре.
• Истечение сессии КЭП: токены нужно обновлять регулярно.
• Отсутствие мониторинга: документы могут висеть в статусе PROCESSING без уведомления.

Пошаговая интеграция

1. Регистрация в Честном Знаке, получение КЭП, настройка аутентификации.
2. Разработка PHP-клиента для работы с API (аутентификация, создание документов).
3. Создание ORM-таблицы для хранения кодов маркировки.
4. Импорт кодов от поставщиков (Excel, CSV, 1С).
5. Интеграция со складским учётом: резервирование и освобождение кодов.
6. Автовывод из оборота при отгрузке и обработка возвратов.
7. Мониторинг статусов документов и оповещение об ошибках.
8. Тестирование и обучение сотрудников.

Что входит в работу?

• Регистрация в Честном Знаке, получение КЭП, подключение к API
• Разработка PHP-клиента для аутентификации и работы с документами
• Создание ORM-таблицы для хранения кодов маркировки
• Импорт кодов от поставщиков (Excel, CSV, 1С)
• Интеграция со складским учётом: резервирование кодов при заказе
• Автовывод из оборота при отгрузке и возврат при возврате
• Мониторинг статусов документов и ошибок
• Документация и обучение сотрудников
• Поддержка после запуска и обновления при изменениях в API ЧЗ

Почему выбирают нас?

• 7+ лет опыта в разработке на 1С-Битрикс и интеграциях с Честным Знаком
• Более 50 успешных проектов для интернет-магазинов разного масштаба
• Индивидуальный подход: мы не используем шаблонные решения, а адаптируем интеграцию под ваш бизнес-процесс
• Прозрачная отчётность: вы видите статусы каждого документа ЧЗ в реальном времени

"По данным API Честного Знака, автоматизация снижает количество ошибок вывода в 10 раз." — официальная документация.

Сроки и стоимость

Базовая интеграция (вывод при продаже, возврат) — 4–6 недель. С расширенным функционалом (импорт кодов, складской учёт, мобильное сканирование) — 10–16 недель. Точная стоимость рассчитывается после аудита вашего проекта. Закажите консультацию — мы подготовим смету и дорожную карту.

Автоматизация маркировки не только избавляет от штрафов, но и ускоряет обработку заказов. Свяжитесь с нами, чтобы внедрить интеграцию в ваш магазин.