BEFORE YOU START
确认商用授权,桌面端已开启 API 服务并复制调用地址与令牌。
STEP 01
开启服务,拿到调用地址
在桌面端侧边栏「API 服务」打开服务开关(商用版专属)。默认只监听本机 127.0.0.1,需要局域网内其他机器调用时再显式打开「允许局域网访问」;令牌在管理页一键复制。开关状态会持久化,电脑重启后自动恢复,集成链路不断。
服务开启且调用地址可用
STEP 02
先取模板与打印机清单
GET /api/v1/templates 返回模板列表与每个模板的变量清单,data 里该传哪些字段一目了然;GET /api/v1/printers 列出已配置的打印机。集成前先调这两个接口对齐字段。
模板变量清单已获取
STEP 03
提交打印任务
POST /api/v1/print,携带 X-Api-Token 请求头,body 里给模板名、可选打印机与 data 数据(单条对象或数组批量),服务返回 202 和 jobIds 表示任务已受理入队,异步执行不阻塞调用方。
打印任务提交返回 202
STEP 04
轮询状态与排错
用 GET /api/v1/jobs/{id} 查询任务进度与结果;/health 免令牌,用于探活和版本确认。常见错误码:401 令牌缺失或错误,403 非商用版,409 锁屏或未登录,422 参数或模板校验失败。
任务状态查询通过
STEP 05
两个实用约定
收到 503 或网络错误时任务可能已经入队,重试前先查任务状态,避免重复打印;大批量渲染耗时随行数线性增长,建议每批不超过 100 行分批提交。
分批策略与重试语义确认
完成前,核对这三件事。
0 / 3阅读辅助清单,仅用于当前页面,不代表真实任务已执行。
本文为产品使用指南,不包含虚构的发布日期或实测结论。操作与版本范围以实际桌面端为准。