如何通过 Web 服务 API 打印标签：开发者实战指南
你的应用程序早已知道标签上该写什么——订单号、SKU、条码值、装箱单。麻烦的从来不是数据，而是输出环节：驱动程序、打印机语言、后台打印程序，还有那台偏要把你的字体渲染得大两个磅值的仓库打印机。
本实战指南将完全跳过这一整套技术栈。你将学会如何通过 Web 服务 API 打印标签：注册一次外部系统，在浏览器中设计一次标签，然后从你自己的代码中提交打印任务——或获取渲染好的 PDF 和 PNG。无需打印机驱动，无需 SDK，无需原始打印机命令。
你将构建的内容：通过 Web 服务 API 打印标签
通常你会想要两种结果，好消息是它们共享相同的请求结构：
- 提交打印任务。 你的应用发送一个标签引用加上数据负载。任务进入队列，并被分发到已配置的打印机。
- 渲染单个标签。 相同的标签和数据以 PDF 或 PNG 形式返回——用于 UI 中的预览、邮件附件、审批或审计存档。
Next Generation Label Printing System（LPSNG）正是将这一能力作为托管式 Web 服务 API 对外提供。你调用一个端点；服务负责整个打印技术栈。同一套 API 还涵盖直接打印（绕过队列直达设备）和电子价签更新，因此你今天构建的集成在需求增长时依然可用。
我们将按以下路径推进：
- 使用 OAuth2 注册外部系统。
- 在标签工作室中设计一次标签。
- 从你的应用提交打印任务。
- 将单个标签渲染为 PDF 或 PNG。
- 验证任务确实落到了纸上。
确切的端点路径和参数名称见 Web Service Interface 和 External Application Integration 文档——本文为你提供整体结构和操作顺序，文档则提供字节级的细节。
调用 API 前的准备工作
在发出第一个请求之前，请准备好以下内容：
- 一个包含 Web 服务接口的 LPSNG 账户或版本。 Cloud Solution、运行在单板计算机上的 Embedded Edition，以及多用户 Enterprise Features 都具备 Use Cases 中描述的相同核心功能——Web UI、标签工作室、任务队列、PDF 生成和 Web 服务接口。
- 一个已存在于标签工作室中的标签布局， 其字段已映射到你打算发送的数据。API 通过标识符引用布局；它不会即时构建布局。
- 来自注册流程的 OAuth2 凭据，用于连接外部系统。
- 任何支持 HTTPS 的 HTTP 客户端。 Python、Node、Go、curl——协议本身并不挑剔。
- 可选： 一台测试打印机，或者 LPSNG Player（如果你想在接入设备之前先有一条本地渲染路径）。
第 1 步：使用 OAuth2 注册你的外部系统
LPSNG 使用简化的 OAuth2 注册协议，通过单个 URL 连接外部系统。这是大多数集成在自行实现时容易出错的部分：针对原始打印协议手工实现令牌刷新和设备认证，是数周与标签毫无关系的工作。
托管流程只需一步：
# 1. Open the registration URL that LPSNG generates for your external system.
# You complete the consent step once, in a browser.
open "$REGISTRATION_URL"
# 2. Store the credentials LPSNG hands back for that registered system.
export LPSNG_CLIENT_ID="<client-id>"
export LPSNG_CLIENT_SECRET="<client-secret>"
# 3. Exchange them for a token your API calls will use.
# Exact parameter names: see https://lpsng.rsj.de/en/oauth2.md
有两点值得注意：
- 授权同意是一次性步骤。 注册之后，你的应用程序在后续每次 API 调用中都使用生成的凭据——你不需要为每个打印任务都让真人走一遍浏览器流程。
- 这与 ESL 基站使用的是同一模型。 如果你之后连接货架标签，你会立刻认出这个模式。详情见 ESL 和 ESL Interface 文档。
像存储任何其他密钥一样存储令牌：环境变量或密钥管理器，绝不放进代码仓库。
第 2 步：在标签工作室中设计一次标签
打开 Web UI，像构建文档一样构建布局：文本块、图像、条码，以及 API 数据将要落入的字段占位符。
几个日后会有回报的决策：
- 使用受支持的条码符号体系。 LPSNG 原生渲染 1D 和 2D 格式——Barcode Formats 页面列出了可用格式。如果你选择了受支持的格式，API 无需你这边做任何额外工作即可渲染。
- 需要逻辑时，为字段附加 Python 脚本块。 Field Script API 允许脚本块在打印前访问和修改字段的值——便于格式化日期、截断过长的供应商名称，或推导校验位。
# Example: a script block attached to a field, formatting a raw value
# before it reaches the printer. See https://lpsng.rsj.de/api.html
value = str(value).strip().upper()
if len(value) > 30:
value = value[:27] + "..."
- 保存布局并记下其标识符。 该标识符就是你的 API 调用所引用的内容——把它当作配置值，而不是埋在代码里的魔法字符串。
- 将布局与数据分离。 布局定义标签长什么样；请求定义它说什么。正是这种分离让一个布局可以服务成千上万个任务。
第 3 步：从你的应用程序提交打印任务
现在来看调用本身。结构始终相同：认证、引用标签、为字段传入数据负载。
import os
import requests
BASE = os.environ["LPSNG_BASE_URL"] # your LPSNG instance
TOKEN = os.environ["LPSNG_ACCESS_TOKEN"] # from the OAuth2 registration
job = {
"label": "shipping-label-4x6", # identifier from the label studio
"printer": "warehouse-01", # a printer configured in LPSNG
"data": {
"order_no": "SO-10432",
"customer": "Nordwind Handel GmbH",
"sku": "HND-2200-BLK",
"qty": "12",
"barcode": "SO-10432-HND-2200-BLK",
},
}
resp = requests.post(
f"{BASE}/<print-job-endpoint>", # exact path: see the Web Service Interface docs
json=job,
headers={"Authorization": f"Bearer {TOKEN}"},
timeout=30,
)
resp.raise_for_status()
print(resp.json()) # job identifier + status
在服务端，任务进入队列并被分发到已配置的打印机。你的应用程序无需与设备保持长连接，也无需知道那台打印机说的是 ZPL、EPL 还是别的什么语言。
值得了解的变体：
- 直接打印。 当你希望标签直接送往设备而不是在队列中排队等待时，接口提供了直接打印路径。
- 批处理。 每次调用都是一个标签引用加上数据，因此遍历订单行只是你代码中的一个循环——每行一个任务，按你的打包站所需的顺序排列。
关于确切的端点、参数名称和响应字段，请使用 Web Service Interface 和 External Application Integration 参考文档。
第 4 步：将单个标签渲染为 PDF 或 PNG
当需要人工先查看标签，或者你需要一份标签存在过的记录时，渲染优于打印：
- 在有人确认执行之前，在你自己的 UI 中进行预览。
- 发给供应商或客户的邮件附件。
- 由审核人签核稿件的审批步骤。
- 独立于打印机而存续的审计存档。
这个调用看起来和打印任务一样，只是它返回字节而不是将工作入队：
# PDF for archiving or attaching
curl -sS -X POST "$LPSNG_BASE_URL/<render-endpoint>" \
-H "Authorization: Bearer $LPSNG_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"label":"shipping-label-4x6","format":"pdf",
"data":{"order_no":"SO-10432","sku":"HND-2200-BLK"}}' \
-o label-SO-10432.pdf
# PNG for a preview thumbnail — same layout, same data, same output geometry
curl -sS -X POST "$LPSNG_BASE_URL/<render-endpoint>" \
-H "Authorization: Bearer $LPSNG_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"label":"shipping-label-4x6","format":"png",
"data":{"order_no":"SO-10432","sku":"HND-2200-BLK"}}' \
-o label-SO-10432.png
由于两条路径使用相同的布局和相同的数据，你预览的就是你打印的。这正是把这一切放在同一个系统中完成、而不是把 PDF 库拼接到打印机驱动上的全部意义所在。
两个实用提示：
- 离线或嵌入式渲染。 LPSNG Player 是一个独立的命令行打印引擎，接收包和数据，输出 PDF、PNG、JSON、打印输出或 ESL 更新。当你需要无需服务器往返的输出时，它就是正确的工具。
- 积极缓存。 重复的标签——同一个货架标签、同一个托盘 ID——不需要每次都重新渲染。以布局 + 数据哈希为键存储 PDF，跳过 API 调用。
第 5 步：验证打印任务是否成功
HTTP 200 意味着任务被接受。它并不意味着标签从打印机出来了。按以下顺序验证：
- 在 Web UI 中检查任务队列。 确认任务已被接受并完成，且发往了你预期的打印机。
- 将渲染结果与现实对比。 把 PDF 或 PNG 放在实体标签旁边。缩放问题和条码静区问题就是在这里暴露的，此时发现比在客户现场发现要便宜得多。
- 扫描条码。 读码器是检验数据能否往返的唯一诚实测试——检查扫描出的值是否与你的应用程序发送的值逐字符一致。
- 记录响应和任务标识符。 将两者与你的内部订单或发货记录关联存储。当有人问“这件货是带着标签发出的吗？”，你希望从数据库得到答案，而不是靠猜。
- 如果使用 ESL，也检查显示屏。 更新后的货架显示屏是一个独立的第二信号，表明相同的数据到达了服务。ESL Interface 和 ESL Binding API 涵盖了那一侧。
排查常见问题
认证失败。 如果调用开始返回认证错误，令牌很可能被撤销了，或者外部系统的注册发生了变化。重新运行 OAuth2 注册——它按设计就是一步流程，所以恢复成本很低。参见 OAuth2 页面。
标签上字段空白或缺失。 几乎总是键不匹配：你的 data 负载中的键必须与布局中的字段名完全一致，包括大小写。在责怪打印机之前，先把标签渲染为 PNG 并检查。
条码输出错误。 检查两件事：你选择的格式是否在受支持的 Barcode Formats 列表中，以及数据类型是否与符号体系的预期相符。仅支持数字的格式会愉快地把含有字母的字符串渲染成乱码。
打印机收不到任务。 任务只能被分发到 LPSNG 中已配置且在线的打印机。如果队列显示任务停在那里不动，问题出在目标设备，而不是你的请求。
渲染结果与打印结果看起来不同。 对比布局与实体介质之间的 DPI 和标签尺寸。为一种尺寸设计并发送到不同尺寸纸张的布局，会以破坏条码可读性的方式缩放。
常见问题
我需要在我的服务器上安装打印机驱动或 SDK 才能通过 Web 服务 API 打印标签吗？
不需要。Next Generation Label Printing System 为你处理整个打印技术栈：你通过 Web 服务 API 提交任务或请求渲染，托管服务负责其余一切。如果你需要用于本地输出的独立命令行引擎，可以使用 LPSNG Player。
提交打印任务和渲染单个标签有什么区别？
提交打印任务通过任务队列将标签发送到已配置的打印机。渲染则将标签以 PDF 或 PNG 形式返回，以便你在不打印的情况下预览、存档或附加。两者使用相同的布局和相同的数据，因此输出是一致的。
外部系统的 OAuth2 注册是如何工作的？
LPSNG 使用简化的 OAuth2 注册协议，通过单个 URL 连接外部系统。你完成一次授权同意步骤，生成的凭据用于后续 API 调用。ESL 基站也使用相同的模型，因此这一模式在各种集成中保持一致。
同一个 API 也能更新电子价签吗？
可以。LPSNG 包含一个厂商中立的 JSON 接口（ESLSEND）和一个用于 ESL 标签的绑定 API，因此你可以从同一个集成中同时管理打印标签和电子价签。如需深入了解，请参阅我们的配套文章：ESL Binding API 和 electronic shelf label integration APIs。
结语
这个模式短到可以记在脑子里：用 OAuth2 注册一次，在标签工作室中设计一次标签，然后从你的应用程序提交任务或获取渲染结果。过去所有与打印机相关的问题——驱动、命令语言、字体缩放、条码库——都被统一在一个 API 界面之后处理，该界面涵盖打印任务、直接打印、PDF 和 PNG 渲染以及 ESL 更新。
Next Generation Label Printing System 正是让这一切成为完整集成、而非其中一部分的托管服务。先从 Web Service Interface 文档了解确切的端点，在标签工作室中设计你的第一个布局，并在自动化其余部分之前先向单台打印机发送一个测试任务。如果你还在权衡各种选择，我们的 Zebra Designer alternative comparison 是一篇不错的后续阅读。
相关文章
- Zebra Designer Alternative: Label Printing Software to Compare
- ESL Binding API: Documentation and Examples
- Understanding Electronic Shelf Label Integration APIs
