Честный знак: серверная часть интеграции и где она обычно падает

MAATRIX

Когда «Честный знак» «не работает», в 9 случаях из 10 не работает не сама система маркировки, а конкретный сервер, который должен был с ней поговорить — истёк сертификат, канал моргнул в момент пиковой нагрузки, очередь документов забилась и никто не заметил. С точки зрения бизнеса это выглядит одинаково: касса не может продать товар или склад не может провести приёмку. С точки зрения инженера это разные проблемы с разными причинами, и разбираться в них приходится обычно в самый неудобный момент — вечером пятницы или в час пик перед праздником. Разберём, как в общих чертах устроена серверная часть такой интеграции и на каких инфраструктурных узлах она чаще всего спотыкается.

Зачем нужна серверная часть и что она делает

«Честный знак» — государственная система маркировки товаров, обязательная для целого ряда товарных групп (от табака и обуви до отдельных категорий продуктов питания и товаров лёгкой промышленности). С точки зрения розницы или производителя система требует одного: каждое движение маркированного товара — ввод в оборот, приёмка, продажа, списание — должно быть отражено в системе через специальный код маркировки (Data Matrix).

Технически это означает, что где-то должен стоять сервер (или сервис в облаке — концептуально не меняет сути), который умеет:

• принимать и расшифровывать коды маркировки со сканеров на кассах и складе;
• формировать электронные документы о движении товара (приёмка, продажа, возврат, списание) и отправлять их в систему маркировки;
• получать подтверждения и обрабатывать ошибки — если документ отклонён, кто-то (человек или процесс) должен об этом узнать;
• держать локальный буфер («очередь») документов на случай, если сеть или система маркировки временно недоступны;
• синхронизировать состояние с учётной системой (обычно 1С или аналог), чтобы кассы и склад видели актуальный статус кодов.

Важный нюанс: у большинства участников оборота нет прямого канала до государственной системы — обмен идёт через оператора электронного документооборота (ЭДО), который выступает посредником: принимает документы от вашего сервера, проверяет формат, отправляет дальше и возвращает статусы. Это добавляет в цепочку ещё одно звено со своими регламентными окнами, лимитами и точками отказа.

Здесь и дальше мы намеренно не приводим конкретные адреса API, названия протоколов обмена или коды ошибок — это быстро устаревает и различается у разных операторов ЭДО и версий интеграционных модулей. За актуальным списком эндпоинтов, форматом документов и кодами ошибок — в документацию оператора ЭДО и на официальный портал системы маркировки; ниже — про то, что стабильно на уровне инфраструктуры вне зависимости от того, что поменяется в протоколе.

Типовая архитектура: три слоя, а не один сервис

Полезно думать об интеграции не как об одном «модуле обмена с Честным знаком», а как о трёх слоях, у каждого из которых свой профиль отказов.

Слой 1. Точка касания с товаром. Кассы, сканеры на приёмке, терминалы сбора данных на складе. Если этот слой не может достучаться до слоя 2 (например, упал Wi-Fi в магазине), с точки зрения кассира «Честный знак не работает», хотя проблема в локальной сети.

Слой 2. Локальный сервер интеграции. Обычно это отдельный сервис (часто рядом с учётной системой, а иногда как её модуль) — он держит очередь необработанных документов, общается с оператором ЭДО, кэширует статусы кодов, разруливает конфликты (например, если один и тот же код пытаются провести дважды). Это тот компонент, за инфраструктуру которого отвечаете вы — и именно он даёт больше всего практических граблей.

Слой 3. Оператор ЭДО и сама система маркировки. Внешний контур, на который вы не влияете напрямую, но обязаны учитывать его регламентные окна обслуживания, лимиты запросов и собственные сбои — они случаются у любого крупного сервиса, и разумная архитектура закладывает это как штатный сценарий.

Разделение на слои сужает зону поиска при инциденте: не проходят продажи у всех касс сразу — смотрите слой 2 и 3, у одной кассы — скорее слой 1.

Канал связи: почему нестабильность — это норма, а не исключение

Самая частая причина сбоев на практике — не экзотика, а банальная нестабильность канала между сервером интеграции и оператором ЭДО. В рознице это особенно заметно: магазин у дороги, провайдер один, резервного канала нет, и любая просадка связи в момент, когда касса пытается пробить маркированный товар, превращается в очередь недовольных покупателей.

Практические выводы для инфраструктуры:

• Не полагайтесь на единственный канал интернета там, где через него идёт обязательная по закону отправка документов. Резервный канал (второй провайдер, LTE-модем как fallback) — это не избыточность, а страховка от простоя кассы.
• Держите сервер интеграции там, где вы контролируете сетевую связность, а не на маршруте с большим числом непрозрачных промежуточных узлов. Чем короче и предсказуемее путь до оператора ЭДО, тем меньше сюрпризов.
• Логируйте не только факт ошибки, но и её характер — таймаут, разрыв соединения, TLS-ошибка и обычная ошибка бизнес-логики (например, отклонённый документ) выглядят по-разному в логах, и путать их — значит терять время на диагностику именно тогда, когда его нет.
• Отдельно стоит настроить мониторинг доступности эндпоинта оператора ЭДО как обычного внешнего сервиса — простым периодическим запросом с алертом при деградации, до того как это заметит кассир.

Сертификаты: тихая причина внезапной остановки продаж

Обмен с оператором ЭДО и системой маркировки идёт по защищённым каналам, и почти везде в цепочке участвуют TLS-сертификаты и/или сертификаты усиленной электронной подписи (УКЭП), которыми подписываются документы. У обоих типов сертификатов есть срок действия, и оба умеют «тихо» истекать.

Классический сценарий: сертификат для подписи документов или для доступа к API оператора ЭДО был выпущен год назад, автопродление либо не настроено, либо настроено, но зависит от человека, который давно сменил должность. Сертификат истекает не с громким алертом, а с тишиной — сервер продолжает пытаться отправлять документы, получает ошибки авторизации или TLS-рукопожатия, складывает их в очередь как «временный сбой» — а на самом деле сбой постоянный, пока сертификат не заменят.

Что стоит сделать на уровне инфраструктуры:

• вести отдельный, независимый от вендора учёт сроков действия всех сертификатов, участвующих в обмене (TLS-сертификат сервера, сертификат УКЭП для подписи документов, при наличии — клиентские сертификаты для доступа к API);
• настроить мониторинг сроков истечения с оповещением заранее — за 30 и за 7 дней, а не в день Х;
• не привязывать продление критичных сертификатов к одному человеку — процедура должна быть описана и воспроизводима любым дежурным инженером.

Это ровно та же грабля, что регулярно встречается с обычными TLS-сертификатами сайтов — разбор типичного инцидента с похожей механикой (автопродление тихо не сработало, узнали в пятницу вечером) можно посмотреть здесь: сертификат протух в пятницу вечером. Общий принцип мониторинга сроков действия сертификатов и доменов, который стоит применить и к сертификатам для маркировки, описан в статье мониторинг сертификатов и доменов.

Недоступность сервера в пиковой нагрузке

Второй по частоте класс проблем — это не внешний канал и не сертификат, а собственный сервер интеграции, который не выдерживает нагрузку в момент, когда она максимальна. Для розницы пиковая нагрузка предсказуема: вечер пятницы, выходные, дни перед праздниками — именно тогда, когда сервер интеграции критичнее всего, а ресурсов ему обычно закладывают по остаточному принципу.

Типичные причины недоступности сервера под пиковой нагрузкой:

• Нехватка вычислительных ресурсов. Сервис интеграции часто ставят на ту же виртуальную машину, что и учётную систему, без учёта того, что в пиковые часы обе нагрузки складываются, а не размазываются во времени.
• Насыщение очереди в памяти или в базе данных. Если очередь необработанных документов реализована неэффективно (например, без индексов на статус документа), при накоплении тысяч записей операции чтения/записи в очередь начинают тормозить сами по себе — независимо от внешнего канала.
• Отсутствие горизонтального резерва. Один сервер — одна точка отказа. Если он перезагружается на обновление или падает от исчерпания памяти, вся касса встаёт, пока сервис не поднимется вручную.
• Совместное использование сервера с непрофильными задачами — тяжёлые фоновые job'ы, бэкапы, обновления, которые администратор запускает «между делом», ровно в вечер пятницы способны на несколько минут отобрать ресурсы у сервиса маркировки.

Практический ориентир (именно ориентир, не измеренное значение — конкретные требования зависят от числа касс, объёма товарооборота и интеграционного модуля): небольшой точке с несколькими кассами обычно хватает скромной VPS с выделенным ядром CPU и парой гигабайт памяти, если сервис маркировки не делит ресурсы с тяжёлой учётной системой. Для сети из десятков точек или производства с непрерывным потоком маркировки правильнее заложить отдельный сервер под интеграционный слой и резервный узел на случай отказа основного.

Похожая логика разбирается в статье про инфраструктуру для торговли маркированными товарами и алкоголем — там она рассмотрена на конкретном кейсе продуктового магазина: ЕГАИС и «Честный знак» — сервер, которому нельзя падать. А если пиковая нагрузка приходит не плавно, а обвалом одновременных запросов — стоит посмотреть, почему в таких ситуациях чаще падает не канал, а база данных под сервисом: DDoS на API: почему первой падает база, а не канал.

Очередь необработанных документов: где копится риск

Очередь документов — это компонент, который спасает от кратковременных сбоев (сеть на пять минут пропала — документы подождут и уйдут, когда связь вернётся), но при неправильной эксплуатации сам становится источником проблем.

На что обратить внимание:

• Мониторинг размера очереди, а не только факта её существования. Очередь из 20 документов — это норма при кратковременном сбое связи. Очередь из 5000 документов, растущая уже третий день — это сигнал, что где-то системная проблема (неверные учётные данные, отозванный сертификат, изменившийся формат документа), которую ретраи сами не решат.
• Разделение ошибок на временные и постоянные. Документ, отклонённый из-за некорректных данных (например, товар не найден в обороте), не станет валидным после сотой попытки отправки — такие документы нужно выводить в отдельную очередь на ручной разбор, а не крутить в общем цикле ретраев бесконечно.
• Персистентность очереди. Если очередь хранится только в оперативной памяти процесса, перезапуск сервиса (в том числе штатный — после обновления) может её обнулить. Очередь должна переживать перезапуск сервиса и, в идеале, перезагрузку сервера.
• Алертинг по возрасту самого старого документа в очереди, а не только по её размеру — документ, который не может уйти уже три часа, при формальном небольшом размере очереди может означать, что бизнес уже нарушает сроки фиксации оборота товара.

Симптоматически это похоже на любую другую очередь недоставленных сообщений — принципы мониторинга те же, что и для прочих асинхронных интеграций с внешними системами.

Резервирование и план на случай простоя

Полностью исключить простой нельзя — недоступность оператора ЭДО или самой системы маркировки не в вашей власти. Задача инфраструктуры — не гарантировать 100%-ную доступность (это нереалистично), а минимизировать последствия и не терять данные о движении товара.

Разумный минимум:

• Резервный канал связи до оператора ЭДО, отдельный от основного интернет-канала магазина или склада.
• План действий персонала на случай, если система маркировки недоступна — в законодательстве предусмотрены сценарии временной приостановки обязательной проверки кодов при технических сбоях, но это исключение, а не повседневная практика; важно, чтобы кассиры и кладовщики знали, что делать, а не действовали наугад.
• Резервный сервер или как минимум быстро восстанавливаемый бэкап конфигурации сервиса интеграции, чтобы при аппаратном отказе не тратить часы на настройку с нуля.
• Регулярная сверка — раз в неделю или чаще сверять состояние очереди и статусы отправленных документов с личным кабинетом оператора ЭДО, а не полагаться только на локальные логи. Расхождение — ранний признак проблемы, которая ещё не привела к остановке продаж, но приведёт.

Таблица ниже — не норматив, а рабочий чек-лист приоритетов для небольшой команды, которая настраивает или пересматривает такую интеграцию:

Частые вопросы