使用 LPSNG API 自动化条码标签打印
如果你的团队仍然在导出订单数据、打开标签模板、粘贴 SKU，然后逐个包裹点击打印，那么瓶颈并不在打印机。瓶颈在于数据与标签之间的手动中间环节。LPSNG Web Service API 消除了这一环节：你可以通过编程方式提交打印作业，将单个标签渲染为 PDF 或 PNG 用于预览，并将作业直接发送到热敏打印机或标准打印机。
本指南涵盖实用内容：一次性 OAuth2 设置、基础自动化流水线、故障处理，以及随着业务量增长保持标签自动化系统可靠性的最佳实践。
一次性设置：将你的应用程序连接到 LPSNG
在发送任何标签之前，你需要将应用程序连接到 LPSNG。LPSNG 为外部系统使用简化的 OAuth2 注册协议。无需漫长的开发者应用手动配置流程，连接只需一个注册 URL 即可完成。
流程如下：
- 在你的应用程序与 LPSNG 之间发起 OAuth2 注册。
- 批准连接。
- 将返回的凭据存储在你的集成环境中。
- 使用这些凭据请求 bearer token 以调用 API。
同样的单 URL 注册模型也用于外部系统，例如 ESL 基站，因此一旦你的团队完成一次接入，该模式即可在其他集成中复用。
API 的指向取决于你的部署方式。托管的多用户云版本和嵌入式版本都暴露了 Web Service 接口。如果你需要离线或高吞吐量的命令行路径，LPSNG Player 是一个独立的打印引擎，接收包裹和数据输入，并生成 PDF、PNG、JSON、打印或 ESL 输出。
对于非开发人员或重度依赖电子表格的流程，Google Sheets 插件和 Excel 接口是实用的无代码途径。如果你是从电子表格而非代码进行自动化，在构建自定义 API 客户端之前，请参阅如何使用 LPSNG 从 Google Sheets 打印标签。
请将集成凭据置于源代码控制之外：
# .env — 存储在你的密钥管理器或 CI/CD 密钥存储中
LPSNG_BASE_URL=https://<your-lpsng-instance>
LPSNG_CLIENT_ID=<from-oauth2-registration>
LPSNG_CLIENT_SECRET=<from-oauth2-registration>
构建自动化流水线：从数据到打印标签
核心循环很简单：你的订单、库存或发货系统中有记录。你将这些记录打包成作业负载并提交给 LPSNG Web Service API。LPSNG 使用你设计的模板渲染标签，结果要么是发送到已配置打印机的打印作业，要么是渲染后的文件。
这为你提供了三种实用模式：
- 直接打印：提交作业，让 LPSNG 将其发送到目标打印机。
- 渲染以供审批：将单个标签生成为 PDF 或 PNG，用于预览、电子邮件附件或归档。
- 打印并归档：结合两种路径，既打印实体标签，又在系统中存储 PNG/PDF 凭证。
一个最小的 Python 集成可以如下所示。此处的端点路径和负载字段仅为概念性说明——请使用 Web Service API 指南获取确切的请求结构。
import os
import requests
LPSNG_BASE_URL = os.environ["LPSNG_BASE_URL"]
def get_token():
# Exchange OAuth2 registration credentials for a bearer token.
# See the OAuth2 guide for the exact request and response fields.
...
def render_label_preview(template_id: str, record: dict, output_format: str = "png"):
token = get_token()
response = requests.post(
f"{LPSNG_BASE_URL}/<render-endpoint>", # exact path in Web Service API guide
headers={"Authorization": f"Bearer {token}"},
json={
"template_id": template_id,
"data": record,
"format": output_format,
},
timeout=30,
)
response.raise_for_status()
return response.content
def submit_print_job(template_id: str, records: list[dict]):
token = get_token()
response = requests.post(
f"{LPSNG_BASE_URL}/<jobs-endpoint>",
headers={"Authorization": f"Bearer {token}"},
json={
"template_id": template_id,
"records": records,
},
timeout=30,
)
response.raise_for_status()
return response.json()
你的作业负载应仅携带标签模板所需的可变数据。让模板负责布局、条码格式和静态内容。
对于动态标签内容，LPSNG 包含一个 Python 字段脚本 API。你可以将 Python 脚本块附加到标签字段，使其在打印前访问和修改字段值。这对于格式化、清理输入数据或直接在标签内部应用条件逻辑非常有用，而无需将所有这些逻辑构建到你的应用程序中。
# Conceptual field script attached to a barcode or text field.
if record.get("country_code") == "DE":
value = value.strip().upper()
同样的自动化思路也适用于纸质标签之外的场景。对于电子货架标签，LPSNG 提供了一个供应商中立的 JSON 文件接口 ESLSEND 和一个 ESL 绑定 API。如果你的项目包含数字价格标签，请参阅什么是电子货架标签以及它们如何工作？以了解更广泛的背景。
监控与故障处理
可靠的自动化流水线不会将已提交的作业视为已打印的作业。提交打印请求后，需要跟踪作业直到其达到终态。
LPSNG Web 界面包含一个作业队列，为操作员提供人工监督点。该队列可用于发现失败作业、检查标签未打印的原因，以及无需重新提交原始数据即可重新打印。
在你的集成代码中，构建一个简单的状态轮询：
import time
def wait_until_terminal(job_reference: str, timeout: int = 120):
deadline = time.time() + timeout
while time.time() < deadline:
state = get_job_state(job_reference) # from API or job queue
if state in ("printed", "completed", "failed"):
return state
time.sleep(2)
raise TimeoutError(
f"Job {job_reference} did not reach a terminal state in {timeout}s"
)
对于重试，在网络超时后应保持谨慎。超时并不能告诉你作业是否已被接受。在重新提交之前，查询作业队列以查找你之前的尝试。如果你可以附加一个客户端生成的作业引用，请保持其在重试期间稳定，以便检测重复提交。
在生产环境中，至少记录以下字段：
- 作业引用或 API 返回的 ID
- 模板 ID
- 记录标识符，如订单号或 SKU
- 打印机或输出路由
- HTTP 状态和错误响应体
然后对失败作业设置告警，而不仅仅针对服务级错误。一个静默失败的标签比一个报告异常的服务更糟糕。
标签自动化最佳实践
- 围绕可变数据占位符设计模板。 你将布局、条码类型和静态品牌元素保留在模板中的程度越高，日后需要修改的应用程序代码就越少。
- 使用 Python 字段脚本 API 进行标签级转换。 当格式化条码、修剪输入或条件性更改文本属于标签特定逻辑时，应将其放在标签脚本中。
- 使用 Excel 接口进行查找表和数据验证。 如果你的应用程序已经依赖电子表格来管理产品数据、映射或验证，LPSNG 可以使用 Excel 文件作为数据文件和查找文件。
- 对于本地部署或低延迟环境，考虑使用嵌入式版本。 它在 Raspberry Pi 等单板计算机上提供完整的 LPSNG，当云连接中断时标签仍能打印，这一点非常有用。
- 对于 OEM 或经销商构建，请考虑白标解决方案。 如果标签打印嵌入在更大的产品中，白标版本专为打印机制造商、纸张制造商和系统集成商设计。
在 Next Generation Label Printing System 标签工作室中，可复用模板是长期可维护性的关键。一个好的经验法则：如果两个标签仅在数据上有所不同，那么它们应该使用同一个模板。
常见问题
LPSNG API 使用什么认证方法？
LPSNG 使用 OAuth2 和简化的注册协议。你通过单个 URL 注册应用程序，并获得用于认证 API 调用的凭据。
我可以在不打印的情况下渲染标签预览吗？
可以，Web Service API 可以将单个标签渲染为 PDF 或 PNG 文件。这些文件可用于预览、电子邮件附件或归档。
API 是否支持所有条码格式？
LPSNG 支持广泛的 1D 和 2D 条码格式。完整列表请参阅条码格式文档。
是否有离线或本地部署的自动化选项？
有，LPSNG Player 是一个可以在本地运行的独立命令行打印引擎，嵌入式版本则在 Raspberry Pi 等单板计算机上提供完整的 LPSNG 安装。
结论：立即开始自动化
API 驱动的标签打印消除了导致发货缓慢和标签错误的手动复制、粘贴和点击操作。借助 LPSNG Web Service API，驱动订单或库存系统的同一份数据可以直接生成打印标签、PDF 预览和电子货架标签更新，全程无需人工介入。
从小处着手：选择一种标签类型，连接一个应用程序，并与现有流程并行运行，直到你对输出结果建立信任。托管的 Next Generation Label Printing System 为你提供云版本和独立播放器，让你无需先搭建整个打印车间即可评估工作流程。
有关实现细节，请从 Web Service API 文档和 OAuth2 指南开始。
相关文章
