ESL 绑定 API 教程：将标签连接到商品
你手里有一块电子货架标签（ESL），目录里有一件商品。你需要让这块标签显示正确的价格、商品名称和附加数据，而无需走一遍专有手持设备的操作流程。本教程将展示如何在下一代标签打印系统（LPSNG）中使用 ESL 绑定 API，通过一次简单的 HTTPS 调用将 ESL 标签连接到商品。
学完本教程后，你将能够从外部系统（如移动数据录入（MDE）单元）以编程方式绑定标签、验证绑定结果，并在标签更换商品时解绑或重新绑定。
前置条件
开始之前，请确保你具备以下条件：
- 一个具有 ESL 绑定 API 访问权限的 LPSNG 账户。绑定 API 是 LPSNG 核心功能的一部分，所有版本均可用。
- 支持绑定接口的兼容 ESL 硬件，例如 CATIC ESL 设备。
- 一个已通电的 ESL 基站，且要绑定的标签在其信号范围内。
- 对 REST API 和 JSON 有基本了解。
- LPSNG Web 服务的基础 URL，如账户配置中所示。
- 用于身份验证的 OAuth2 客户端凭据。如果你尚未注册外部系统，请先按照 OAuth2 文档操作。
你不需要直接与供应商特定的基站协议通信。困难的做法是逆向工程你的 ESL 硬件所使用的底层通信协议。受支持的路径是让 LPSNG 托管服务来处理这种转换，而你只需使用一个 HTTPS API。
分步指南：将 ESL 标签绑定到商品
第 1 步：获取 OAuth2 访问令牌
LPSNG 为外部系统使用简化的 OAuth2 注册协议。集成注册完成后，你从租户令牌端点请求访问令牌，并在每次 API 调用中包含该令牌。
确切的端点和注册流程取决于你的账户。在大多数设置中，客户端凭据请求如下所示：
curl -s -X POST "https://<YOUR-LPSNG-BASE>/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-u "<CLIENT_ID>:<CLIENT_SECRET>" \
-d "grant_type=client_credentials"
成功响应中包含一个 Bearer 令牌：
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600
}
在绑定请求的 Authorization 头中使用该 access_token 值。如果你的租户使用不同的令牌请求格式，请查看 OAuth2 指南。
第 2 步：确定商品和标签
在绑定任何内容之前，你需要两个标识符：
- 商品标识符：通常是已存在于你的 LPSNG 数据源中的 SKU、EAN 或内部物料编号。
- 标签标识符：唯一的 ESL 标签 ID。这通常印在标签本身，或通过 MDE 单元扫描标签获取。
例如，一件商品可能标识为 EAN-4001234567890，一个标签可能标识为 CATIC-001234。请将这两个值准备好，用于 JSON 载荷。
第 3 步：构造绑定请求
绑定请求是发送到绑定端点的 JSON 对象。必填字段是商品标识符和标签标识符。根据你的标签布局和 ESL 配置，你还可以发送可选字段，如 price 或 labelData 对象。
{
"itemId": "EAN-4001234567890",
"tagId": "CATIC-001234",
"price": "19.90",
"labelData": {
"name": "Organic Oat Milk 1L",
"unit": "L"
}
}
并非所有部署都会使用 price 和 labelData。如果你的标签完全由 LPSNG 中的商品主数据驱动，你可以只发送 itemId 和 tagId。请检查你的标签布局，确定标签应显示哪些附加字段。
第 4 步：向绑定端点发送 POST 请求
本教程中我们使用 /api/esl/bind 作为绑定端点。你的 LPSNG 安装可能暴露相同的路径或租户特定的路径，因此请在你的环境中确认 ESL 绑定 API 文档中的确切端点。
将载荷保存到文件中，以便 curl 命令保持可读：
{
"itemId": "EAN-4001234567890",
"tagId": "CATIC-001234",
"price": "19.90",
"labelData": {
"name": "Organic Oat Milk 1L",
"unit": "L"
}
}
然后发送请求：
curl -s -X POST "https://<YOUR-LPSNG-BASE>/api/esl/bind" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
--data @binding-payload.json
LPSNG 接收请求，在你的数据源中解析商品数据，并指示 ESL 基站更新标签。
第 5 步：处理响应
成功绑定通常返回 200 OK 响应，并带有状态对象：
{
"status": "bound",
"tagId": "CATIC-001234",
"itemId": "EAN-4001234567890",
"updatedAt": "2026-09-21T10:15:00Z"
}
常见错误响应包括：
400表示数据无效，例如 JSON 正文格式错误或缺少必填字段。401表示身份验证失败，例如访问令牌已过期或缺失。
检查响应正文中的错误消息，了解哪个字段出了问题。如果 API 返回其他 4xx 状态，请检查标签或商品是否未知，或者标签是否已在其他地方绑定。
第 6 步：通过查询标签状态验证绑定
如果你的部署暴露了标签状态端点，你可以查询当前绑定情况。确切端点可能有所不同；以下是一个示例形式：
curl -s "https://<YOUR-LPSNG-BASE>/api/esl/status/CATIC-001234" \
-H "Authorization: Bearer <ACCESS_TOKEN>"
类似以下的响应确认标签已绑定到预期的商品：
{
"tagId": "CATIC-001234",
"boundItemId": "EAN-4001234567890",
"lastSeen": "2026-09-21T10:15:00Z"
}
如果你的租户没有暴露状态端点，请使用 LPSNG 中的 ESL 管理仪表板查看标签状态。
第 7 步：可选 — 解绑或重新绑定标签
当商品移动到新位置或标签被重复使用时，你需要解绑或重新绑定它。确切方法取决于你的 LPSNG 绑定端点。
常见的解绑请求使用 DELETE：
curl -s -X DELETE "https://<YOUR-LPSNG-BASE>/api/esl/bind/CATIC-001234" \
-H "Authorization: Bearer <ACCESS_TOKEN>"
要将同一标签重新绑定到不同的商品，发送 PUT 请求：
curl -s -X PUT "https://<YOUR-LPSNG-BASE>/api/esl/bind/CATIC-001234" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"itemId":"EAN-4001234567891"}'
请查看 ESL 绑定 API 文档，了解你的安装中确切的解绑和重新绑定行为。
验证绑定
API 调用返回成功后，请通过多种方式确认绑定：
- 实际检查 ESL 显示屏 — 标签现在应显示商品的价格和名称。如果显示屏仍为空白或显示旧数据，请等待几秒钟后再次检查。
- 通过 ESL 接口查询标签状态（如果你的部署提供了该接口）。状态响应应显示预期的
boundItemId。 - 打开 LPSNG 中的 ESL 管理仪表板并查找该标签。其状态应从未绑定或之前的商品变为新商品。
- 用不同的商品进行测试并重新绑定同一标签。如果显示屏正确更新，说明你的集成已端到端正常工作。
常见问题排查
身份验证错误
仔细检查你的 OAuth2 客户端 ID 和密钥。访问令牌会过期，因此如果在一段时间后收到 401 响应，请续期令牌。
找不到标签
确保标签 ID 完全正确，包括任何前缀或前导零。同时确认标签已通电且在 ESL 基站的信号范围内。最近未上报的标签可能无法用于绑定。
找不到商品
验证商品标识符是否存在于你的 LPSNG 数据源中。绑定 API 解析的是与你的标签使用的相同数据，因此 EAN 或 SKU 中的拼写错误将导致绑定失败。
绑定冲突
标签可能已绑定到另一件商品。请先解绑标签，然后发送新的绑定请求。某些安装会拒绝未经显式解绑步骤的直接重新绑定。
网络问题
如果请求超时，请检查你的客户端、LPSNG Web 服务和 ESL 基站之间的连接。基站必须可从 LPSNG 访问，而不是直接从你的客户端访问。
常见问题解答
什么是 ESL 绑定 API？
ESL 绑定 API 是下一代标签打印系统（LPSNG）提供的 Web 服务，允许外部系统（如移动数据录入单元）将电子货架标签绑定到特定商品。它通过 HTTPS 使用简单的 JSON 请求。
我可以将多个标签绑定到一件商品吗？
通常，一个标签绑定到一件商品。但是，根据你的 ESL 硬件和 LPSNG 配置，你可能可以将多个标签绑定到同一件商品，用于冗余或不同的显示位置。请查看你的硬件文档。
如何解绑标签？
要解绑标签，你可以向绑定端点发送带有空值或 null 商品标识符的请求，或者使用专用的解绑方法（如果可用）。请参阅 API 文档了解确切的端点和载荷。
绑定 API 在所有 LPSNG 版本中都可用吗？
是的，ESL 绑定 API 是 LPSNG 核心功能的一部分，所有版本均可用，包括云解决方案和嵌入式版本。但是，你需要兼容的 ESL 硬件才能使用它。
结论
绑定工作流是一个简单的循环：身份验证、收集商品和标签 ID、发送绑定请求、验证显示屏。一旦这个循环正常工作，你就可以从 MDE 单元、履约流程或任何其他需要将 ESL 标签分配给商品的外部系统调用它。
ESL 绑定 API 只是更广泛的 LPSNG ESL 解决方案的一部分。LPSNG 还提供了供应商中立的 ESL 接口用于更新显示屏、OAuth2 指南用于身份验证，以及 LPSNG Player用于命令行 ESL 输出工作流。
如果你是第一次集成 ESL 硬件，请从 ESL 绑定 API 文档开始，并在投入生产前使用备用标签进行测试。
相关文章
