QZ Tray Lite — это локальный сервер печати, который полностью эмулирует протокол оригинального QZ Tray, но без его сложной инфраструктуры. Он позволяет печатать чеки на термопринтеры прямо из браузера с помощью библиотеки qz-tray.js — и ваш фронтенд не требует ни единой правки.

Если вы сталкивались с настройкой оригинального QZ Tray, вы знаете, сколько шагов нужно пройти, чтобы получить тихую печать: генерация ключей, настройка сертификатов, создание бекенда для подписи каждого запроса, сбор timestamp, подпись SHA-256 через RSA… Ошибка на любом этапе — и пользователь видит диалог «Allow?», который не должен появляться на кассе.

QZ Tray Lite убирает всё это.

• Подпись запросов (signature, signAlgorithm) принимается, но игнорируется — клиент даже не подозревает, что общается с другой реализацией.

• Сертификаты используются готовые — например, от установленного QZ Tray (корень Windows уже доверяет CN=localhost).

• Бекенд для подписи не нужен. Схема сводится к двум участникам: браузер ↔ локальный процесс.

Преимущества перед оригинальным QZ Tray

Как это работает?

Браузер через qz-tray.js устанавливает WebSocket-соединение (wss://localhost:8181 или ws://localhost:8182). QZ Tray Lite отвечает на те же вызовы, что и оригинал:

• getVersion — сообщает клиенту версию 2.2.6, сохраняя совместимость с современным qz-tray.js;

• certificate — принимает сертификат клиента и отвечает подтверждением;

• printers.find / printers.getDefault — возвращает список принтеров системы (через win32print);

• print — отправляет задание в очередь печати.

Реализована последовательная очередь на каждый принтер: копии не перемешиваются, длительная печать не блокирует WebSocket.

Поддерживаемые форматы печати

1. Сырая печать (ESC/POS)

• Текст с выбором кодировки (encoding) — поддерживаются кодовые страницы от Windows, IBM, ISO, а также GBK, Big5, Shift_JIS, UTF-8.

• Кириллица: кодировка CP1251 + команда ESC t в теле чека (номер страницы подбирается под прошивку принтера).

• Изображения: полная поддержка ESC * (режимы single/double/triple, в том числе legacy) и GS v 0. Квантование: luma, alpha, black.

• Работает через type: "raw" с options.language: "escpos".

2. Растровая печать (pixel)

• Печать через драйвер принтера (GDI) с возможностью масштабирования (scaleContent), полей (margins) и указания единиц измерения (units: дюймы или мм).

• Не требует options.language, подходит для печати логотипов, штрихкодов, этикеток.

• Используется, когда в запросе указан type: "pixel".

Безопасность (важно!)

QZ Tray Lite создан для кассовых компьютеров в доверенной локальной сети. Он не проверяет:

• подпись запросов (signature, signAlgorithm);

• сертификат клиента и цепочку доверия;

• временные метки (timestamp);

• наличие в allowed.dat / blocked.dat.

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

Все действия логируются: каждый запрос, каждый байт, каждый URL, который загружается через format: "image" без явного flavor.

Установка и запуск

Требования: Windows 10/11, Python 3.12+.

git clone <репозиторий>
cd qz-tray-lite
python -m pip install -r requirements.txt

Запуск:

python main.py

Сервер автоматически:

• найдёт порт (если 8181 занят — перейдет на 8282, и так далее);

• использует сертификат от оригинального QZ Tray (если он установлен) — или позволит указать свой через параметры --keystore / --storepass;

• поднимет одновременно wss и ws для обратной совместимости.

Установка как службы Windows / задания Планировщика:

В комплекте идёт скрипт tools/service.ps1, который автоматически выбирает подходящий способ запуска в фоне — как служба (с автозапуском до входа) или как задание (после входа пользователя). Поддерживается ротация логов и мониторинг состояния.

Для кого этот продукт?

• Разработчики POS-систем, которые хотят избавиться от громоздкого QZ Tray и упростить развертывание на кассах.

• Интеграторы, которые устанавливают кассовое ПО десяткам клиентов и устали настраивать сертификаты и бекенд для каждого магазина.

• Владельцы бизнеса, у которых уже есть сайт с qz-tray.js, но нужен стабильный и быстрый локальный сервер печати для чеков на 58-мм термопринтерах.

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

Чего нет в QZ Tray Lite

Мы сознательно не реализовали те возможности, которые редко используются в кассовых сценариях и несут дополнительную сложность:

• печать через serial, usb, hid, file, networking;

• детали принтера (printers.detail), прослушивание статуса (startListening);

• форматы pdf и html для pixel-печати;

• imageEncoding: GS_L, quantization: dither, rotation / orientation.

При попытке вызвать эти методы клиент получит понятное сообщение об ошибке, а не молчаливый отказ.

Тестирование и отладка

В комплекте — утилита tools/probe.py, которая:

• повторяет рукопожатие qz-tray.js;

• отправляет тестовые задания на печать (с логотипом в виде шахматной доски для проверки смещения битов и обрезки);

• может имитировать как правильные, так и заведомо ошибочные запросы, демонстрируя, что подпись не проверяется.

python tools/probe.py --print XP-58         # тестовый чек
python tools/probe.py --print XP-58 --pixel # растровая печать

Также доступен набор юнит-тестов для ESC/POS-конвертера (65 тестов, 831 строка проверок) — байты рассчитаны вручную по оригинальной спецификации Epson.

Лицензия

QZ Tray Lite распространяется под лицензией MIT. Вы можете свободно использовать его в коммерческих проектах, модифицировать и встраивать в свои решения — единственное условие: сохранять текст лицензии и упоминание об авторстве (IDNK Soft, 2026).

Протокол, совместимость с которым реализована, принадлежит QZ Industries, LLC (проект qzind/tray, лицензия LGPL-2.1). QZ Tray Lite — независимая реализация серверной стороны этого протокола на Python.

Поддержка и документация

• Быстрый старт — в файле README.md (украинский / английский).

• Подробности по работе с очередями, кодировками, преобразованием изображений — в комментариях к коду (документирование на украинском).

• Примеры интеграции и варианты конфигурации — по запросу в Issues.

Выбирайте QZ Tray Lite — лёгкую альтернативу, которая делает ровно то, что нужно кассе, и не требует ничего лишнего.