How to set up receipt printers with QZ Tray

Receipt printing in HotelBee uses QZ Tray as the bridge between the browser and your physical printers. This article walks through installing it, mapping printers in HotelBee, and choosing the right print mode per POS point so service is fast.

Step 1 — Install QZ Tray

Download from qz.io and install on every device that needs to print. Free for non-commercial use; paid license for commercial. After install, QZ Tray runs in the background and listens on port 8181. Allow it through any firewall.

Step 2 — Verify HotelBee can see QZ Tray

Open HotelBee → POS → POS Points → POS Places → click any place. The form tries to connect to QZ Tray when it loads. If it succeeds, you'll see your installed printers in the dropdown. If you see the warning 'qz_tray_not_found', QZ Tray isn't running or isn't reachable — start it (or check the firewall) and refresh the page.

Step 3 — Configure POS point print options

POS → POS Points → open the POS point. Three print categories with three options each:

• Fiscal receipt — the customer-facing fiscal invoice with QR.
• Non-fiscal receipt — provisional bill, table check, intermediate prints.
• Waiter report — end-of-shift summary for the waiter.

For each, pick a printing mode:

• default — opens the browser print dialog. User picks printer and clicks Print. Slow but flexible — use when the staff prints from many printers ad-hoc.
• silent — sends to the system's default printer with no dialog. Fast; assumes the right printer is the system default.
• silent_to_printer — sends to a specific printer you pick from QZ's discovered list. Best for fixed setups (cashier station has one receipt printer at the desk).

Step 4 — Test print

Take a test order and close it. The fiscal receipt should print silently (or with a dialog if you set default). Verify the layout, paper size, and that the QR is scannable. Tweak printer settings (margins, font scale) in your OS printer preferences if anything is cropped — HotelBee uses your driver's settings for layout.

Common gotchas

• Two waiters on two devices, but only one has QZ Tray — the other can't silent-print. Install on every device or fall back to a shared print server.
• Printer changed name in the OS — silent_to_printer config breaks. Re-pick from the dropdown after the rename.
• Browser blocks the QZ Tray WebSocket — usually a corporate proxy or aggressive antivirus. Allow the connection or whitelist QZ Tray.
• Reboot loses connection — QZ Tray on Mac/Linux may not auto-start. Add it to startup items.