Интеграция 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 недель. Точная стоимость рассчитывается после аудита вашего проекта. Закажите консультацию — мы подготовим смету и дорожную карту.
Автоматизация маркировки не только избавляет от штрафов, но и ускоряет обработку заказов. Свяжитесь с нами, чтобы внедрить интеграцию в ваш магазин.