WMS 打印任务 API（云打印）
最后更新 2026-10-13
提交含 ZPL 的云打印任务、查询状态、取消与重试——手机到 Hub 的云打印链路。
下发云打印任务#
手机 web（无本地 Hub 能力）把 ZPL 经本接口写入 print_jobs（queued）。仓库电脑上的 Device Hub 订阅/轮询拉走后在 Zebra 本地打印，再回写结果。不传 device_id 则使用该仓库的默认标签打印机。
POST /api/wms/print-jobs
{
"device_id": "<uuid>", // optional; default label printer of the warehouse if omitted
"warehouse_id": "<uuid>", // optional; scope for default-printer lookup
"label_kind": "pallet", // required: e.g. pallet | carton | ucc
"ref_type": "pallet", // optional
"ref_id": "<uuid>", // optional
"copies": 2, // optional, default 1
"zpl_content": "^XA\n^FO40,40^FDHello^FS\n^XZ" // required
}查询任务状态#
GET /api/wms/print-jobs/<job-id>
// -> { ok: true, data: {
// id, status: "queued|printing|done|failed|cancelled",
// error, device_id, label_kind, copies, created_at } }
GET /api/wms/print-jobs?status=queued&warehouse_id=<uuid>&page=1&page_size=50
// print-center queue list (page_size default 50, max 200)任务状态机：queued → printing → done；或 → failed（带 error 文本）；或 → cancelled。Hub 以原子条件更新领取任务（UPDATE … WHERE status='queued'），手机侧取消的任务不会被打印。
取消 / 重试#
PATCH /api/wms/print-jobs/<job-id>
{ "action": "cancel" } // only from queued -> cancelled
{ "action": "retry" } // only from failed -> queued (error cleared)
// conditional update: 0 rows affected means the state already changed -> HTTP 409云中继说明：ZPL 会经过云端（租户自己的 Supabase，走 RLS 保护）——migration 211 为此加了 zpl_content 列。等待超 5 分钟的任务在打印中心高亮。设备健康：GET /api/wms/print-devices；last_seen_at 在 2 分钟内算在线。