LPSNG

LPSNG

Next Generation Label Printing

FeaturesUse casesDeploymentEditionsInterfacesContact
Start
FeaturesUse casesDeploymentEditionsInterfacesContact
← All posts

2026-10-18

如何通过 API 将 ESL 标签与商品关联

如何通过 API 将 ESL 标签与商品关联
pdf labels barcodes label merge browser based graphical layout editor google sheets addin microsoft excel addon electronic shelf labels esl barcode3 labels label editor

如何通过 API 将 ESL 标签与商品关联

货架图已更新。价格在 ERP 中是正确的，在货架边缘标签模板中是正确的，在商品主数据中也是正确的。然而，三个小时后，某个货架通道仍然显示旧价格——因为附着在该货架位置上的电子货架标签仍然绑定着原来放在那里的商品。必须有人拿着手持设备走过通道，扫描标签，扫描商品，然后重复几百次。

这个手动绑定步骤是货架边缘标签中最后一块抗拒自动化的部分。但它不必如此。借助下一代标签打印系统（LPSNG）中的 ESL Binding API，你可以以编程方式将 ESL 标签与商品关联，通过供应商中立的 JSON 接口将商品数据推送到显示器，并且只有在真正出错时才需要动用扫描器。

本文端到端地介绍这一自动化流程：一次性设置、执行绑定的流水线、需要监控的内容，以及如何保持其可靠性。

一次性设置：准备你的 ESL 环境

每个门店、基站或 MDE（移动数据录入）单元只需执行一次。此后的一切都是计划任务。

1. 注册你的外部系统

LPSNG 使用简化的 OAuth2 注册协议：你通过一个 URL 连接外部系统——ESL 基站、手持 MDE 单元、中间件服务。LPSNG 在该注册背后管理令牌交换，因此你无需从头实现 OAuth2 客户端。

在实践中，这意味着你的集成配置只保存一个注册 URL 和一个凭据，而不是一个令牌刷新状态机：

# lpSng-integration.yaml
esl:
  registration_url: "https://lpsng.rsj.de/..."   # from your LPSNG registration
  client_id: "${LPSNG_CLIENT_ID}"
  client_secret: "${LPSNG_CLIENT_SECRET}"        # keep in a secret store, not in git
  store_id: "store-0417"

将这些值存储在密钥管理器中。注册是唯一一个一旦出错就难以挽回的步骤。

2. 确保硬件可访问

在任何 API 调用能够成功之前，你的 ESL 标签需要已安装并处于其基站或网关的范围内。如果你运行的是 CATIC ESL 硬件，请遵循 CATIC 安装说明——天线放置和标签寻址是最常导致“API 正常但货架上什么都没变”的两个问题。

3. 确认你的显示更新路径

显示内容通过供应商中立的 JSON 文件接口（ESLSEND）更新。从架构角度看，这才是值得关注的部分：载荷是 JSON，而非专有二进制格式，因此你的集成不会被焊死在某一个标签供应商上。我们在供应商中立的 ESL 接口对开发者意味着什么中讨论了其影响。

4. 让 LPSNG 指向你的商品数据

绑定步骤需要有东西可绑定。LPSNG 可以使用 Excel 文件作为数据和查找文件、面向依赖电子表格的团队的 Google Sheets 插件，或将你的 ERP 作为上游数据源。绑定逻辑本身并不关心——它需要一个稳定的键（SKU 或 EAN）以及你希望显示在显示器上的字段。

如果你想走困难路线，你可以手工编写 ESLSEND JSON 文件并自行运行 OAuth2 令牌交换。LPSNG 的托管工作流的存在就是为了让你不必这样做。

自动化流水线：将标签绑定到商品

以下是逐步流程。

步骤 1 — 触发绑定过程

ESL Binding API 是一项专为没有 Web 界面的 MDE 单元构建的 Web 服务：手持设备可以调用它，cron 任务可以调用它，webhook 也可以调用它。一次绑定运行以一个 HTTP 请求开始。

curl -X POST "$LPSNG_BASE/binding/jobs" \
  -H "Authorization: Bearer $LPSNG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "store_id": "store-0417",
        "source": "erp-sync-2026-10-18",
        "mode": "reconcile"
      }'

确切的路径和参数见 Web 服务接口文档；重要的是，绑定运行是你提交的一项作业，而不是你要坐在那里等待的会话。

步骤 2 — 让 LPSNG 将商品映射到标签 ID

这一步取代了扫描器。LPSNG 从你的数据源获取商品标识符（SKU、EAN），并使用系统已知的标签与货架位置关系，将它们与 ESL 标签 ID 匹配。你的代码永远不需要知道哪个物理标签悬挂在哪个货架上方。

如果你自己驱动对账，循环很小：

import os, requests

BASE = os.environ["LPSNG_BASE"]
HEADERS = {"Authorization": f"Bearer {os.environ['LPSNG_TOKEN']}"}

def reconcile(store_id: str, items: list[dict]):
    """items: [{"sku": "...", "ean": "...", "price": "...", "name": "..."}]"""
    resp = requests.post(
        f"{BASE}/binding/jobs",
        headers=HEADERS,
        json={"store_id": store_id, "items": items, "mode": "reconcile"},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["job_id"]

步骤 3 — 将商品数据推送到显示器

一旦标签被绑定，LPSNG 就会通过 ESLSEND JSON 接口用你提供的商品特定值——价格、名称、条形码、布局所使用的任何内容——更新 ESL 显示。一个最小载荷大致如下所示（完整架构见 ESL 接口文档）：

{
  "esl_id": "TAG-0042-1188",
  "item": {
    "sku": "SKU-88213",
    "ean": "4012345678901",
    "name": "Organic Coffee 500g",
    "price": "8.49"
  }
}

由于该格式是供应商中立的，日后更换标签硬件只是一个部署问题，而不是重写。

步骤 4 — 打印仍需打印的标签

有些东西仍然是实体的：促销货架立牌、货架边缘条、箱标签。这些可以从同一份商品数据渲染，因为 LPSNG 的 Web 服务 API 可以提交打印作业并将单个标签渲染为 PDF 或 PNG，而独立 Player 可以从相同的包加数据输入中输出 PDF、PNG、JSON、打印作业或 ESL 更新。一个数据源，两个输出通道。

将整个流程作为计划工作流

每晚对账通常就足够了：

# crontab: every night at 02:15, after the ERP export lands
15 2 * * * /usr/local/bin/python /opt/esl/sync.py --store store-0417 >> /var/log/esl-sync.log 2>&1

# sync.py (sketch)
items = load_from_erp()          # or read the Excel/Sheets export
job_id = reconcile("store-0417", items)
wait_for_job(job_id)             # poll LPSNG for job status
handle_failures(job_id)          # retry or flag

Cron 没问题。来自你 ERP 的 webhook 更好——它会在价格变化的瞬间绑定标签，而不是几小时后。

监控与故障处理

你看不见的自动化是你无法信任的自动化。

  • 在作业队列中跟踪作业。 LPSNG 的作业队列是每个版本核心功能的一部分。绑定运行和显示更新会出现在那里，失败的作业会被记录以供审查。
  • 重试，不要惊慌。 如果某个标签不可达，API 会返回错误。为瞬时故障（暂时超出范围的标签）配置重试逻辑，并将其余的标记出来交由人工处理。
  • 关注标签健康状况。 电池和信号状态可通过 ESL 接口查看。轮询这一点，你就能发现下周会失效的标签，而不是已经失效的那个。
  • 在你这一侧设置告警。 轮询 LPSNG Web 服务以获取作业状态，并将失败推送到你已经在使用的任何告警系统中。你不需要第二套监控栈。
  • 保留手动回退方案。 如果某个标签持续不可达，待其重新上线后在 LPSNG Web UI 中手动重新绑定。同一平台同时管理自动和手动路径，因此两者之间不会出现脑裂。

一个简单的状态检查：

curl -s "$LPSNG_BASE/jobs/$JOB_ID" \
  -H "Authorization: Bearer $LPSNG_TOKEN" | jq '{status, failed: [.results[] | select(.status=="failed")]}'

可靠 ESL 自动化的最佳实践

  • 保持标识符干净。 你的 ERP 键和 ESL 键应该是同一个字符串，在一个地方生成。大多数“绑定失败”工单实际上是“SKU 格式变了”工单。
  • 坚持使用 JSON 接口。 供应商中立的载荷让硬件更换成为一项部署任务。这也意味着相同的载荷结构可以跨门店使用。
  • 先在预发布环境中测试。 针对测试门店运行绑定可以在映射错误影响到实际通道中的 400 个标签之前将其捕获。
  • 轮换凭据。 将 OAuth2 凭据和刷新令牌存储在密钥管理器中，记录谁拥有它们，并按计划轮换。
  • 考虑边缘部署。 对于连接不稳定的门店，嵌入式版本在诸如 Raspberry Pi 之类的单板计算机上运行完整的 LPSNG，因此绑定作业在本地执行，并在链路恢复时同步。
  • 在推送条形码之前先验证它们。 显示器上错误的 EAN 比过时的价格更糟糕——参见如何在打印标签前验证条形码。

常见问题

我需要编写代码才能将 ESL 标签与商品关联吗？

不一定。LPSNG 提供 Web 服务 API 和可通过简单 HTTP 请求触发的托管工作流。不过，要实现完全自动化，你很可能需要编写调用 ESL Binding API 的脚本。供应商中立的 JSON 接口（ESLSEND）使其能够直接与你的现有系统集成。

我可以将 ESL Binding API 与任何 ESL 硬件一起使用吗？

ESL Binding API 被设计为供应商中立，使用 JSON 文件接口（ESLSEND）来更新 ESL 显示。只要各种 ESL 硬件支持该 JSON 格式，它就能与之配合工作。LPSNG 还为 CATIC ESL 硬件提供了具体的安装说明。

LPSNG 如何处理外部系统的身份验证？

LPSNG 使用简化的 OAuth2 注册协议。你通过一个 URL 连接你的外部系统（如 MDE 单元），LPSNG 管理令牌交换。这避免了在每个集成中从头实现 OAuth2。

如果 ESL 标签在更新期间离线会发生什么？

如果某个标签不可达，API 会返回错误。LPSNG 的作业队列会记录该失败，你可以配置重试逻辑或接收告警。对于关键更新，待标签重新上线后，你可以使用 LPSNG Web UI 手动重新绑定它。

结论：一次自动化，持续受益

通过 API 将 ESL 标签与商品关联，从你的流程中移除了走通道的步骤。你提交一个绑定作业，LPSNG 将你的商品标识符与标签 ID 匹配，显示器通过一个不会将你锁定在单一硬件供应商上的 JSON 接口更新。价格在货架图变更之间保持准确，而不是漂移直到有人注意到。

实用的路径是托管路径：用一个 URL 注册每个门店，让下一代标签打印系统处理令牌交换和作业跟踪，并将你自己的代码限制在真正属于你的部分——决定哪些商品放在哪里。

从阅读 ESL 接口文档和 ESL Binding API 参考开始。然后针对云版本进行原型开发，或者如果你希望绑定作业从第一天起就在门店内运行，请下载嵌入式版本。

相关文章

EU label: AI-generated content