Інтеграція 1С-Бітрікс із системою Чесний Знак
Інтернет-магазини, які торгують маркованими товарами, стикаються з жорсткими вимогами: під час продажу необхідно вивести код Data Matrix з обігу. Ручне введення кодів вручну — помилки, штрафи та втрата часу. Штраф за невиведення з обігу сягає 300 000 рублів на юридичну особу згідно зі ст. 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%. Економія на операційних витратах склала близько 180 000 рублів на рік.
| Показник | До | Після |
|---|---|---|
| Ручне виведення з обігу | 1.5–2 години/день | Автоматично |
| Помилки виведення (неправильний код) | ~3%/міс | < 0.3% |
| Повернення до Чесного Знаку | Пропускалися | Автоматично при оформленні повернення |
Як перевірити код перед продажем?
Перед відвантаженням — перевірка статусу коду в ЧЗ (чи не виведений вже з обігу іншим шляхом):
$codeInfo = $chestnyZnak->httpGet("/facade/identificationtools?uitCode={$code}");
if ($codeInfo['status'] !== 'IN_CIRCULATION') {
throw new \Exception("Код {$code} не знаходиться в обігу: {$codeInfo['status']}");
}
Типові помилки при інтеграції:
- Відсутність обробки повернень: коди залишаються в статусі
soldі губляться. - Неправильний формат Data Matrix — API ЧЗ суворий до структури.
- Закінчення сесії КЕП: токени потрібно оновлювати регулярно.
- Відсутність моніторингу: документи можуть висіти в статусі
PROCESSINGбез сповіщення.
Покрокова інтеграція
- Реєстрація в Чесному Знаку, отримання КЕП, налаштування аутентифікації.
- Розробка PHP-клієнта для роботи з API (аутентифікація, створення документів).
- Створення ORM-таблиці для зберігання кодів маркування.
- Імпорт кодів від постачальників (Excel, CSV, 1С).
- Інтеграція зі складським обліком: резервування та звільнення кодів.
- Автовиведення з обігу при відвантаженні та обробка повернень.
- Моніторинг статусів документів та оповіщення про помилки.
- Тестування та навчання співробітників.
| Етап | Тривалість |
|---|---|
| Базова інтеграція (виведення, повернення) | 4–6 тижнів |
| З розширеним функціоналом (імпорт, склад, сканування) | 10–16 тижнів |
Що входить у роботу?
- Реєстрація в Чесному Знаку, отримання КЕП, підключення до API
- Розробка PHP-клієнта для аутентифікації та роботи з документами
- Створення ORM-таблиці для зберігання кодів маркування
- Імпорт кодів від постачальників (Excel, CSV, 1С)
- Інтеграція зі складським обліком: резервування кодів при замовленні
- Автовиведення з обігу при відвантаженні та повернення при поверненні
- Моніторинг статусів документів та помилок
- Документація та навчання співробітників
- Підтримка після запуску та оновлення при змінах в API ЧЗ
Чому обирають нас?
- Понад 7 років досвіду в розробці на 1С-Бітрікс та інтеграціях з Чесним Знаком
- Більше 50 успішних проєктів для інтернет-магазинів різного масштабу
- Індивідуальний підхід: ми не використовуємо шаблонні рішення, а адаптуємо інтеграцію під ваш бізнес-процес
- Прозора звітність: ви бачите статуси кожного документа ЧЗ у реальному часі
"За даними API Чесного Знака, автоматизація знижує кількість помилок виведення в 10 разів." — офіційна документація.
Терміни та вартість
Базова інтеграція (виведення при продажу, повернення) — 4–6 тижнів. З розширеним функціоналом (імпорт кодів, складський облік, мобільне сканування) — 10–16 тижнів. Точна вартість розраховується після аудиту вашого проєкту. Замовте консультацію — ми підготуємо кошторис та дорожню карту.
Автоматизація маркування не тільки позбавляє від штрафів, але й прискорює обробку замовлень. Зв'яжіться з нами, щоб впровадити інтеграцію у ваш магазин.