Best practices¶

How to build printing into a POS that cashiers can rely on. For a ready-made settings page and printing module that follow these rules, see Printer setup in your POS.

Setup¶

1. Make the address and token settings, not code. Each computer has its own token. Add Bridge address and Access token fields to your POS settings and store them on that device. Never commit a token.
2. Check the bridge when the POS starts. Call GET /health (no token). If it fails, show "Hardware bridge not running" with a hint to open it from the Start menu.
3. Show printer status. Subscribe to WS /events and show a small indicator from bridge.status, so cashiers spot an unplugged printer before a customer is waiting. Reconnect every few seconds if the socket drops.

Printing¶

1. Save the sale first, then print. A printer problem must never block or undo a completed sale. If printing fails, show the bridge's message and a Reprint button.
2. Don't retry prints automatically. A 502 means nothing printed, so offering Reprint is safe. A timeout or dropped connection is different: the receipt may already have printed. Ask the cashier first.
3. Mark reprints (a REPRINT banner) so duplicates are easy to spot.
4. Send receipts line by line, format money in the POS, and let the bridge fit the paper. Don't pad with spaces.
5. Set a timeout on requests, e.g. AbortSignal.timeout(15000).

Several printers¶

1. Make printer names settings too. Let the shop choose which API name to use for receipts, kitchen tickets and invoices (load the choices from GET /printers) instead of hard-coding them.
2. Leave out printer for the everyday case. Receipts then go to the default receipt printer, so the shop can swap printers in the bridge without touching the POS.
3. Print to each printer independently. If the kitchen printer fails, the customer's receipt should still print.

Errors¶