Máy in bill

import { Aside } from ‘@astrojs/starlight/components’;

Phiên bản tiếng Anh

Settings — receipt printer — English

Tình huống sử dụng

Sau khi thanh toán thành công, hệ thống tự động in 1 bill giấy cho khách. Bài viết này cho chủ cửa hàng cấu hình máy in (không phải cashier bán hàng).

Source: apps/vendor-web/src/app/point-of-sale/pages/settings/settings-hardware-printer-page.tsx + <DeviceSettings hardwareFocus="printers" />.

Hình: Trang cấu hình máy in bill — danh sách thiết bị (TCP / USB / SYSTEM), toggle bật/tắt, nút kích hoạt bridge. Spec owner: cashier-screenshots.spec.ts → "settings — receipt printer".

Trước khi bắt đầu

• Vendor Desktop phải chạy trên PC quầy — máy in bill kết nối qua app này, không chạy được trên trình duyệt.
• Cashier không cần quyền settings để bán, nhưng cần settings ghi để cấu hình máy in (chỉ chủ).
• Biết IP + port của máy in TCP, hoặc tên máy in cục bộ (trong Windows / macOS).

4 bước cấu hình

Bước 1 — Mở trang máy in bill

Từ shell Thu ngân → Cài đặt → Máy in bill (/point-of-sale/settings/printer).

Bước 2 — Thêm thiết bị

Click + Thêm thiết bị → chọn Máy in bill (receipt_printer).

Trường	Bắt buộc	Ghi chú
Tên	✓	Tên hiển thị trong hub
Phương thức	✓	TCP (in qua mạng) hoặc USB (cắm trực tiếp) hoặc SYSTEM (in qua driver hệ điều hành)
IP	chỉ TCP	Địa chỉ IP máy in trên LAN
Port	chỉ TCP	Cổng TCP (thường 9100)
Loại giấy	✓	Mặc định 80mm
Mẫu in	tùy chọn	Liên kết với ReceiptTemplate đã tạo trong Dashboard

Source: device-settings-form.schema.ts.

Bước 3 — Bật thiết bị

Gạt toggle Bật/Tắt sang xanh. Thiết bị tắt sẽ không nhận lệnh in khi thanh toán.

Bước 4 — Kích hoạt bridge (chỉ máy in TCP)

Nếu dùng TCP, component kiểm tra localPrinterReady (resolveLocalReceiptPrinterConfigReady(device)):

IP + port hợp lệ + bật → in được ngay, không cần bật bridge pair.

Nếu muốn bridge pair (đồng bộ trạng thái với server), click “Kích hoạt bridge” → mỗi terminal in tạo 1 lane code.

canOpenPosBridgeActivate cho printer yêu cầu: là receipt_printer AND là TCP AND có IP + port. USB/SYSTEM chỉ in local.

Chế độ in bill

Sau khi thiết bị OK, vào Cài đặt cửa hàng → In bill (trong Dashboard):

Chế độ	Hành vi
Tắt	Không in gì, không hỏi
Hỏi	Sau thanh toán hiện dialog “In / Xem trước / Bỏ qua”
Tự động	In ngay sau thanh toán thành công (mặc định khu vực thường)

Source: ReceiptPrintModeForm (chọn trong form thiết bị).

Kết quả mong đợi

Bill in ra gồm:

1. Logo cửa hàng (PNG ≥ 300dpi, upload trong Dashboard → Branding).
2. Header: tên cửa hàng, địa chỉ, SĐT.
3. Dòng hàng: tên + số lượng + đơn giá + thành tiền.
4. Tổng + giảm giá + thuế (nếu có).
5. Mã vạch hóa đơn — Code128 từ client_order_id (KHÔNG phải EAN-13 từ id số).
6. Metadata terminal khi thanh toán thẻ (mã giao dịch, số terminal, loại thẻ).

Lỗi thường gặp

Triệu chứng	Xử lý
Không in sau thanh toán	Chế độ đang là Tắt; hoặc thiết bị chưa bật
Mở “Xem trước” thay vì in	Đang ở chế độ Hỏi — cashier chọn In thay vì đóng dialog
In ra nhiều bill trùng	Không bấm OK trên dialog xem trước 2 lần — hệ thống coi như 1 đơn
Logo mờ / mất cạnh	Upload lại PNG ≥ 300dpi; bật ảnh nét trong template
Mã vạch không quét được	Đảm bảo dùng Code128, không EAN-13
In lệch font / mất dòng cuối	Khớp chiều rộng giấy (80mm) với cuộn thực tế

Khắc phục sự cố nhanh

Tình huống	Hành động
Bill không in, không hỏi	Kiểm tra thiết bị đã bật + chế độ in trong Cài đặt cửa hàng
Bill in thử OK, đơn thật không in	Vấn đề ở flow thanh toán — kiểm tra tender xong API có trả print=true
USB không nhận	Đổi cáp / cổng; trên macOS kiểm tra Privacy & Security → USB
TCP mất kết nối giữa ca	Ping IP máy in; thử Kết nối lại trong bridge

Xem thêm: FAQ — In & thiết bị.

Kỹ thuật

• Component: <DeviceSettings hardwareFocus="printers"> (DeviceSettings.tsx)
• Form: device-printer-settings-form.tsx
• Constants: device-settings.constants.ts (kiểu receipt_printer, CASH_DRAWER_PRINTER_TYPE)
• API: fetchVendorDevicesSettings, patchVendorDevicesSettings

Xem thêm

• Cấu hình terminal
• Máy in tem, cân & ngăn kéo
• FAQ — in & thiết bị
• POS payments & webhooks (kỹ thuật)