设备与 Device Hub API
最后更新 2026-10-13
云端设备台账、Hub 配对与本地 Device Hub 打印协议。
云端设备台账#
GET /api/wms/print-devices?warehouse_id=<uuid>&hub_id=<uuid>&page=1&page_size=50
// -> items: id, name, model, device_type, connection, address,
// is_default_label_printer, status, last_seen_at, hub_id, hub_name,
// warehouse_id, warehouse_name, created_at在线/离线按 last_seen_at 心跳计算（阈值 2 分钟）。配对后 Hub 会自动把打印机同步到该台账，包括云打印使用的默认标签打印机标记。
Device Hub 本地协议#
配对和本地打印走工作站电脑上 Device Hub 托盘应用的 WebSocket（ws://127.0.0.1:18443），JSON 请求/响应（action + params）；事件以 { event, data } 推送。hub.info 与 hub.pair 免鉴权，其余 action 需要配对得到的 token。
// 1. user reads the 6-digit code shown in the Device Hub tray app
// 2. pair (no auth required):
ws -> { "action": "hub.pair", "params": { "code": "482910" }, "id": "1" }
ws <- { "id": "1", "ok": true, "data": { "token": "<hub-token>" } }
// 3. store the token locally; all later requests send it (see device-hub lib).
// success envelope: { id, ok: true, data }
// error envelope: { id, ok: false, error: { code, message } }- hub.info —— Hub 版本/平台信息，免鉴权。
- printer.list → { printers }（id、name、model、connection）；printer.discover 触发 USB + 网络（mDNS）扫描，结果以 printer.discovered 事件推送。
- printer.print { device_id, data: "<zpl>", copies } → { job_id }；完成/失败以 print.job_completed 事件通知。
- printer.status { device_id } —— 打印机实时状态（缺纸/缺碳带/开盖等）。
- device.register { device_id, name, is_default } —— 注册发现的设备（同时上报云端台账）。
云中继绑定#
ws -> { "action": "hub.cloud_bind", "params": {
"supabase_url": "https://<ref>.supabase.co",
"supabase_anon_key": "<anon-key>",
"organization_id": "<uuid>",
"warehouse_id": "<uuid>" // optional
}, "id": "2" }
ws <- { "id": "2", "ok": true, "data": {} }
// after binding, the Hub pulls print_jobs with its cloud credentials and syncs the device ledger.