Інтеграція 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 тижнів. Точна вартість розраховується після аудиту вашого проєкту. Замовте консультацію — ми підготуємо кошторис та дорожню карту.

Автоматизація маркування не тільки позбавляє від штрафів, але й прискорює обробку замовлень. Зв'яжіться з нами, щоб впровадити інтеграцію у ваш магазин.