Python 条码标签生成：分步指南
如果你曾尝试从 Python 脚本生成条码标签，就会知道通常的路径是：选择一个条码库，渲染图像，自己构建标签布局，然后再想办法与热敏打印机通信。本指南采用一种不同的、托管式的方法。你将使用下一代标签打印系统（LPSNG）作为渲染和打印引擎，并通过简单的 HTTP 请求从 Python 驱动它。
完成本指南后，你将拥有一个 Python 脚本，可以：
- 对 LPSNG Web 服务 API 进行身份验证
- 查找标签布局
- 发送动态物料数据，包括条码内容
- 应用基于 Python 的字段自定义
- 将标签渲染为 PDF 或 PNG
- 将其发送到打印机或保存在本地
这非常适合需要在仓库、物流、零售或履约工作流中进行数据驱动标签生成的开发人员——无需构建和维护自定义标签渲染管线。
前置条件
在开始之前，请确保你具备：
- Python 3.x 已安装在你的机器上。
- 一个 LPSNG 账户——可以是云版本或嵌入式版本——并且可以访问 Web 服务 API。
- 一个在 LPSNG 标签工作室中创建的标签布局，或者一个可用于测试的示例布局。该布局应至少包含一个条码字段。
- 用于 API 身份验证的 OAuth2 客户端凭据。有关简化注册流程，请参阅 OAuth2 指南。
- 对 Python 和 REST API 有基本了解。 LPSNG Web 服务是 RESTful 的，返回 JSON，因此具备标准的 HTTP 知识就足够了。
你不需要安装条码字体、ZPL/EPL 驱动程序或打印机专用 SDK。LPSNG 会在其 Web 服务背后处理这些细节。
分步指南：使用 Python 生成条码标签
工作流程很直接：身份验证、识别布局、准备数据、可选地使用 Python 脚本块自定义字段、渲染标签，然后打印或保存。
第 1 步：设置你的 Python 环境
创建一个项目目录并安装 requests 库。LPSNG API 是 RESTful 的，因此你只需要一个标准的 HTTP 客户端。
mkdir lpsng-python-labeling
cd lpsng-python-labeling
python -m venv venv
source venv/bin/activate # or venv\Scripts\activate on Windows
pip install requests
创建一个名为 generate_label.py 的文件。在文件顶部，定义你的 LPSNG 基础 URL 和凭据。将占位符值替换为你实际实例的详细信息。
import requests
import json
from pathlib import Path
# Replace with your LPSNG instance URL, e.g. https://your-instance.lpsng.rsj.de
LPSNG_BASE_URL = "https://your-instance.lpsng.rsj.de"
# Replace with the credentials from your OAuth2 registration
CLIENT_ID = "your-client-id"
CLIENT_SECRET = "your-client-secret"
第 2 步：获取 OAuth2 访问令牌
LPSNG 使用简化的 OAuth2 注册协议。一旦你的外部应用程序完成注册，就可以用客户端凭据换取访问令牌。
下面的示例将令牌端点保留为变量，这样你可以将其指向 Web 服务 API 文档中针对你实例的确切 URL。
def get_access_token():
# Use the token endpoint listed in the LPSNG OAuth2 guide.
token_url = f"{LPSNG_BASE_URL}/oauth2/token"
response = requests.post(
token_url,
data={
"grant_type": "client_credentials",
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET,
},
timeout=30,
)
response.raise_for_status()
return response.json()["access_token"]
在生产代码中，应缓存令牌并在其过期前刷新。在本演练中，你可以每次请求一个新令牌。
第 3 步：获取你的标签布局 ID
LPSNG 中的每个标签布局都有一个 ID。你可以通过打开布局属性从 LPSNG Web 界面复制它，也可以通过 API 查询。
对于首次测试，Web 界面路径最简单。在标签工作室中打开你的标签布局，从 URL 或布局设置中复制布局 ID。
如果你想从 Python 自动化布局查找，可以使用相同的 REST 模式。确切的端点可能因实例而异，因此请根据你的 API 参考填写：
def find_layout_id(token, layout_name):
headers = {"Authorization": f"Bearer {token}"}
# Replace /layouts with the list endpoint documented for your instance.
response = requests.get(
f"{LPSNG_BASE_URL}/layouts",
headers=headers,
timeout=30,
)
response.raise_for_status()
for layout in response.json():
if layout.get("name") == layout_name:
return layout["id"]
raise ValueError(f"Layout not found: {layout_name}")
对于快速脚本，硬编码布局 ID 也可以：
LAYOUT_ID = "your-layout-id"
第 4 步：准备包含条码内容的数据负载
Web 服务 API 提交打印作业并渲染单个标签。你的负载通常包含布局的一组字段值，包括应编码到条码中的值。
以下是一个带有 Code 128 条码的物料标签的示例负载：
label_data = {
"product_name": "Thermal Label Roll 100x150",
"sku": "THR-100-150",
"barcode": "4012345678901",
"quantity": 12,
"batch": "B20260831-04",
}
负载中的字段名称必须与你在 LPSNG 标签工作室中定义的字段名称匹配。如果你的布局有一个名为 barcode 的条码字段，LPSNG 会按照布局中配置的条码格式对你为该字段发送的值进行编码。
第 5 步：使用 Python 字段脚本 API 自定义字段
LPSNG 包含一个 Python 字段脚本 API，允许你将小型 Python 脚本块附加到标签字段。这些脚本在打印前运行，可以访问或修改字段值。
例如，假设你的仓库数据有时包含小写条码或尾部空格，你希望在值到达条码之前对其进行规范化。在 LPSNG 标签工作室中，将类似以下的脚本块附加到条码字段：
# Attached to the barcode field in LPSNG Label Studio.
# The script runs before printing and can access the current value.
if "barcode" in context:
value = str(context["barcode"]).strip().upper()
确切的入口点和可用对象在 Python API 参考中有文档说明。请使用该参考来验证你 LPSNG 版本的确切钩子签名。关键思想是字段级 Python 脚本将格式化逻辑保持在标签附近，而你的外部 Python 应用程序则专注于数据准备和 API 调用。
第 6 步：调用 Web 服务端点渲染标签
现在调用 LPSNG 将标签渲染为 PDF 或 PNG。Web 服务 API 可以渲染单个标签，因此你不需要运行本地渲染器。
def render_label(token, layout_id, data, output_format="pdf"):
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
}
# Use the render endpoint from the LPSNG Web Service API docs.
render_url = f"{LPSNG_BASE_URL}/render"
response = requests.post(
render_url,
headers=headers,
json={
"layout_id": layout_id,
"data": data,
"format": output_format,
},
timeout=60,
)
response.raise_for_status()
return response.content
对于 PNG 输出，将 "png" 作为格式传入。API 响应包含二进制文件内容，你可以直接保存。
token = get_access_token()
pdf_bytes = render_label(token, LAYOUT_ID, label_data, "pdf")
Path("label.pdf").write_bytes(pdf_bytes)
print("Label rendered: label.pdf")
第 7 步：将生成的标签发送到打印机或保存在本地
如果你的 LPSNG 实例已连接到打印机，你可以通过同一个 Web 服务 API 提交打印作业，而不是下载文件。确切的请求结构在 Web 服务接口中有文档说明。
典型的直接打印调用遵循相同的 REST 模式：
def send_to_printer(token, layout_id, data, printer_name):
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
}
# Use the print endpoint documented for your LPSNG instance.
print_url = f"{LPSNG_BASE_URL}/print"
response = requests.post(
print_url,
headers=headers,
json={
"layout_id": layout_id,
"data": data,
"printer": printer_name,
},
timeout=60,
)
response.raise_for_status()
return response.json()
将 "printer" 替换为在你的 LPSNG 环境中配置的打印机名称或 ID。如果你希望将文件保留在本地，请跳过此步骤，使用第 6 步中的 PDF 或 PNG 输出。
验证你的标签输出
不要仅仅因为 PDF 或 PNG 打开时没有报错就认为条码是正确的。请执行以下检查：
- 目视打开生成的文件。 确认文本字段已填充，条码可见，布局与你的标签工作室设计一致。
- 使用扫描应用程序扫描条码。 将基于手机的条码扫描器对准打印的或屏幕上的条码。验证编码数据与你发送到负载中的值匹配。
- 检查字段自定义。 如果你添加了一个将条码值大写或去除空格的 Python 字段脚本，请发送小写或带填充的测试数据，确认输出按预期发生了变化。
- 使用多个数据集进行测试。 使用不同的 SKU、数量和条码值运行脚本，确保没有字段被硬编码或错位。
如果你的输出是 PDF，请在目标热敏打印机上打印一次，以确认标签尺寸和打印浓度。
常见问题排查
身份验证错误
仔细检查你的 OAuth2 客户端凭据和令牌端点。如果令牌已过期，请请求一个新令牌。确认客户端仍在你的 LPSNG 账户中注册，并且该账户具有 API 访问权限。
找不到标签布局
验证布局 ID 以及与你的 OAuth2 客户端关联的用户权限。客户端可能可以访问 API，但无法访问特定布局。精确检查布局名称，包括大小写和空白字符。
条码未渲染
确保条码格式受 LPSNG 支持，并且条码字段中的值对该格式有效。例如，Code 128 字段应接收对 Code 128 有效的数据。有关支持的 1D 和 2D 格式的完整列表，请参阅条码格式文档。
还要检查布局中的条码字段是否确实映射到了你发送的负载键。字段名称不匹配是条码为空的常见原因。
字段脚本错误
如果你的 Python 字段脚本引发错误，API 响应通常包含错误消息。仔细阅读它；它通常会指向脚本块中的行号或异常类型。使用 Python API 参考确认脚本上下文中哪些对象可用。
打印问题
如果标签渲染成功但无法打印，请确认 LPSNG 环境中的打印机连接和驱动程序设置。检查打印调用中的打印机名称是否与 LPSNG 中配置的名称匹配，以及打印机是否在线。
常见问题解答
我可以在不使用 LPSNG Web 服务的情况下在 Python 中生成条码标签吗？
可以，你可以使用 python-barcode 或 reportlab 等原始库，但你需要自己处理标签设计、打印机通信和条码标准。LPSNG 提供了一个带有 Python API 的托管服务，简化了整个流程，包括字段自定义和直接打印。
LPSNG 支持哪些条码格式？
LPSNG 支持广泛的 1D 和 2D 条码格式。有关完整列表，请参阅条码格式文档，包括 Code 128、QR Code、Data Matrix 等。
使用 LPSNG API 需要安装任何特殊的 Python 包吗？
只需要 requests 等标准 HTTP 客户端库。该 API 是 RESTful 的，返回 JSON 响应，因此可以轻松集成到任何 Python 环境中。
我也可以使用 Python API 更新电子货架标签（ESL）吗？
可以，LPSNG 提供了可通过 Python 访问的 ESL 接口和绑定 API。有关以编程方式更新 ESL 显示的详细信息，请查看 ESL 文档。
结论
当你让托管服务处理渲染、条码标准和打印细节时，Python 条码标签生成会变得简单得多。使用 LPSNG，你的 Python 应用程序只需要进行身份验证、发送字段数据并调用 REST 端点。标签设计保留在标签工作室中，而 Python 字段脚本处理字段级格式化。
这种方法可以很好地融入更大的自动化工作流。如果你作为开发人员正在评估标签软件，请参阅面向开发人员的最佳标签设计软件：为什么 LPSNG 脱颖而出。如果你的标签项目扩展到电子货架标签，请继续阅读零售业 ESL 集成：完整指南。如果你的大部分源数据存放在电子表格中，不要错过从 Excel 自动化标签打印：节省时间并减少错误。
准备好构建你的第一个 Python 生成的条码标签了吗？获取你的 OAuth2 凭据，选择一个布局，然后用一个真实的物料运行脚本。下一代标签打印系统负责繁重的工作——你只需编写集成代码。
相关文章
