Logistics and labels
面向 WMS 和 ERP 打印流程的仓库标签 API
基于 WMS 或 ERP 数据生成托盘、箱件、库位、库存和仓库作业标签 PDF，并支持确定性重打。
主 API JSON Render
ENDPOINT
/api/v1/pdf/render 适用系统 WMS / ERP / 仓库打印服务 / 库存流程
要解决的问题
基于 WMS 或 ERP 数据为托盘、箱件、库位、资产、位置和库存移动渲染仓库标签，同时把库存状态、拣货规则和仓库作业留在调用方系统中。
什么时候用这个 API
- 你需要托盘、箱件、库位、位置、库存或资产标签 PDF。
- 你的 WMS 或 ERP 已经负责 SKU、批次、库位、SSCC 和库存数据。
- 你需要在标签损坏或工位重试时确定性重打。
- 你希望已批准的标签版式通过 Template Render 复用。
它不替代什么
- 你需要 gPdf 管理库存、分配库位或运行仓库工作流。
- 你需要 gPdf 提供扫码 app、打印工位 agent 或标签路由系统。
- 你需要 GS1 认证，而不是条码渲染。
应该调用哪个 endpoint
/api/v1/pdf/render
JSON Render 是这个场景的默认调用路径。
/api/v1/template-render
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/pdf/render - 带 SSCC 条码数据的托盘标签。
{
"pages": [
{
"size": "label_4_6_in",
"elements": [
{
"type": "text",
"x": 6,
"y": 8,
"content": "PALLET LAX-01-2026-00042",
"style": { "font_size": 12, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "sscc-18",
"content": "012345678901234567",
"x": 6,
"y": 30,
"width": 88,
"height": 26,
"barcode_text": { "enabled": true, "position": "bottom" }
},
{
"type": "text",
"x": 6,
"y": 70,
"content": "SKU: CASE-001\nQTY: 48\nLOCATION: A-14-02",
"style": { "font_size": 10, "font_family": "NotoSans-Regular" }
}
]
}
]
}
gPdf 负责什么
- 为仓库打印流程生成 PDF 标签。
- 处理矢量条码、文本、边框、标签页面尺寸和模板绑定。
- 为重打和审计流程提供确定性输出。
- 用 JSON Render 支持自定义版式，用 Template Render 支持已批准标签合同。
你的系统负责什么
- 库存状态、SKU 数据、批次/序列号数据、SSCC 值和库位语义。
- 打印机路由、工位设置、扫码验证和仓库流程规则。
- 模板选择、重试，以及生成 PDF 或源数据的存储。
上线前检查
- 按真实打印机和标签材料验证标签尺寸。
- 扫描仓库流程中使用的每一种条码格式。
- 保持 WMS/ERP 状态权威，只把最终标签数据发送给 gPdf。
- 多个系统或工位会打印的标签使用 Template Render。
- 记录源文档 ID 和 request ID，用于重打追踪。
能力边界
- gPdf 渲染仓库标签 PDF；不管理库存或仓库状态。
- 调用方负责条码 payload 语义和扫码验收。
- Template Render 可以稳定标签版式，但不能替代 WMS 规则。
仓库标签是运营记录
仓库标签用于识别托盘、箱件、库位、资产、库存移动和位置。它们与 WMS 或 ERP 中的运营状态绑定。gPdf 应接收最终标签数据并渲染；它不应决定库存含义或仓库流程状态。
Template Render 让打印工位更简单
对于多个工位共用的标签，请将已批准版式发布为模板。打印服务随后只需发送 template_id 和 WMS 数据，而不必在每个调用方里重建坐标。
重打确定性
仓库会重打标签。标签损坏、打印机卡纸或工位重试，都不应该生成略有不同的文档。请把源标签数据绑定到仓库记录，并使用确定性的 render 输入来重打。
常见问题
- gPdf 管理仓库库存吗？
- 不管理。库存状态、库位、SKU、批次和流程规则由你的 WMS 或 ERP 负责。gPdf 根据最终数据渲染标签 PDF。
- 仓库标签可以使用 GS1 或 SSCC 条码吗？
- 可以，gPdf 可以在 PDF 输出中渲染受支持的条码格式。条码 payload 和扫码验收由你的系统负责。
- 复用仓库标签应该使用模板吗？
- 通常应该。标签版式批准后，Template Render 为打印工位提供稳定 template_id 和 data 合同。
- 重打应该怎么做？
- 将源标签数据或生成的 PDF 与仓库记录一起保存，然后用原始运营 ID 渲染或取回同一标签。