如何通过 Web 服务 API 打印标签：开发者实战指南

你的应用程序已经知道标签上该写什么——订单号、SKU、条码值、装箱单。麻烦的从来不是数据，而是输出环节：驱动程序、打印机语言、后台处理程序，还有某台仓库打印机非要把你的字体渲染得大上两个点。

本指南完全跳过这一整套技术栈。你将学会如何通过 Web 服务 API 打印标签：注册一次外部系统，在浏览器中设计一次标签，然后从你自己的代码中提交打印任务——或拉取渲染好的 PDF 和 PNG。无需打印机驱动，无需 SDK，无需原始打印机指令。

你将构建的内容：通过 Web 服务 API 打印标签

通常你会想要两种结果，好消息是它们共享相同的请求结构：

• 提交打印任务。 你的应用发送一个标签引用加上数据载荷。任务进入队列，并被分发到已配置的打印机。
• 渲染单个标签。 相同的标签和数据以 PDF 或 PNG 形式返回——用于 UI 中的预览、邮件附件、审批或审计归档。

Next Generation Label Printing System（LPSNG）正是以此作为托管式 Web 服务 API 对外提供。你调用一个端点；服务方负责整个打印技术栈。同一套 API 还涵盖直接打印（绕过队列，直达设备）和电子价签更新，因此你今天构建的集成在需求增长时依然可用。

以下是我们将要走的路径：

1. 通过 OAuth2 注册外部系统。
2. 在标签工作室中设计一次标签。
3. 从你的应用提交打印任务。
4. 将单个标签渲染为 PDF 或 PNG。
5. 验证任务确实落到了纸上。

确切的端点路径和参数名称见 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 原生渲染一维和二维格式——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 意味着任务被接受，并不意味着标签从打印机里出来了。按以下顺序验证：

1. 在 Web UI 中检查任务队列。 确认任务已被接受并完成，而且发往了你预期的打印机。
2. 将渲染结果与现实比对。 把 PDF 或 PNG 放在实体标签旁边。缩放问题和条码静区问题就是在这里暴露出来的，而现在发现比在客户现场发现要便宜得多。
3. 扫描条码。 读码器是检验数据能否往返的唯一诚实测试——检查扫描到的值与你的应用发送的值是否逐字符一致。
4. 记录响应和任务标识符。 将两者与你的内部订单或发货记录关联存储。当有人问“这批货是带着标签发的吗？”，你希望答案来自数据库，而不是猜测。
5. 如果使用 ESL，也要检查显示屏。 更新后的货架显示屏是一个独立的第二信号，表明同样的数据到达了服务端。ESL Interface 和 ESL Binding API 涵盖了这一侧。

常见问题排查

认证失败。 如果调用开始返回认证错误，很可能是令牌被撤销了，或者外部系统的注册发生了变化。重新执行 OAuth2 注册——它按设计就是一步流程，所以恢复成本很低。参见 OAuth2 页面。

标签上字段空白或缺失。 几乎总是键不匹配：你的 data 载荷中的键必须与布局中的字段名完全一致，包括大小写。先把标签渲染成 PNG 检查一下，再去找打印机的麻烦。

条码输出错误。 检查两件事：你选择的格式是否在受支持的 Barcode Formats 列表中，以及数据类型是否符合该符号体系的预期。仅支持数字的格式遇到含字母的字符串会照样渲染出乱码。

打印机收不到任务。 任务只能被分发到在 LPSNG 中已配置且在线的打印机。如果队列显示任务停在那里不动，问题出在目标设备，而不是你的请求。

渲染结果与打印结果不一致。 比较布局与实体介质之间的 DPI 和标签尺寸。为一种尺寸设计的布局发送到不同尺寸的纸张上，会以破坏条码可读性的方式缩放。

FAQ

通过 Web 服务 API 打印标签，我的服务器上需要打印机驱动或 SDK 吗？

不需要。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