Logistics and labels
面向仓库和 3PL 流程的托盘标签 API
为仓库、3PL、零售和物流流程生成托盘标签 PDF，支持 SSCC、GS1-128、文本区块和可安全重打的模板。
主 API JSON Render
ENDPOINT
/api/v1/pdf/render 适用系统 WMS / 3PL 后端 / ERP 导出服务 / 仓库打印服务
要解决的问题
基于 WMS、ERP 或 3PL 数据渲染托盘标签 PDF，让仓库团队能识别托盘、扫描 SSCC 或 GS1 条码，并在收货、发货或库存移动中重打同一标签。
什么时候用这个 API
- 你的 WMS 已经有托盘 ID、SKU 或 GTIN 数据、数量、批次和目的地。
- 你需要带 SSCC、GS1-128 或其他受支持条码格式的 PDF 标签。
- 你希望从同一源 payload 得到可确定的重打结果。
- 你需要把版式变成稳定的 Template Render 合同。
它不替代什么
- 你需要 gPdf 管理库存、组托或仓库任务。
- 你需要 GS1 认证，而不是 PDF 条码渲染。
- 你需要直接输出打印机命令。
应该调用哪个 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": 5,
"y": 7,
"content": "PALLET 12 / DOCK B",
"style": { "font_size": 13, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "sscc-18",
"content": "000123456789012345",
"x": 5,
"y": 28,
"width": 92,
"height": 30,
"barcode_text": { "enabled": true, "position": "bottom" }
},
{
"type": "text",
"x": 5,
"y": 78,
"content": "GTIN 09506000134352\nQTY 48 CASES\nLOT L-2026-05",
"style": { "font_size": 10, "font_family": "NotoSans-Regular" }
}
]
}
]
}
gPdf 负责什么
- 生成包含文本、边框和条码元素的标签尺寸 PDF 页面。
- 在 PDF 输出中渲染 SSCC、GS1-128、Code 128、QR 和其他受支持条码格式。
- 为已批准托盘标签版式绑定模板。
- 为重打和审计证据提供确定性输出。
你的系统负责什么
- 托盘身份、商品数据、批次数据、数量、路由和仓库规则。
- 条码 payload 正确性、check digits、扫码测试和标签材料验证。
- 打印工位路由、重打授权和库存状态。
上线前检查
- 渲染前校验 SSCC 或 GS1 payload。
- 在收货和发货工位用生产扫码设备扫描标签。
- 测试密集数据、长商品名称和多仓库语言需求。
- 记录 template_id、源托盘 ID 和 request ID，用于重打。
- 把仓库状态流转留在 render API 之外。
能力边界
- gPdf 渲染托盘标签 PDF；不管理托盘或仓库库存。
- gPdf 不是 GS1 认证机构。
- 扫码验收和仓库流程正确性仍由你负责。
托盘标签连接 WMS 数据和打印输出
托盘标签流程从你的 WMS 或 ERP 开始。它决定标签上应该出现哪些托盘、商品、数量、批次和路由数据。gPdf 把这些数据转换成仓库打印工位可以输出和重打的 PDF。
当搜索意图明确是 SSCC-18 或 GS1 物流标签时，请使用更窄的 SSCC 页面。本页用于更宽泛的托盘标签流程。
Endpoint 选择
默认调用 /api/v1/pdf/render。当版式仍在调整、调用方需要完整描述页面结构时，使用 JSON Render；当版式已经审批并需要多个系统复用时，把版式发布为模板，再通过 Template Render 传入业务数据。
如果场景涉及 Factur-X / ZUGFeRD 这类带 EN 16931 CII XML 的 PDF/A-3b 电子发票封装，才使用 E-Invoice Render。普通 PDF、标签、收据和报表不要伪装成电子发票流程。
上线前验证
用真实数据和下游系统验证 托盘标签 API。保留 request ID、渲染输出和验收记录，便于支持、审计和重打。gPdf 负责 PDF 渲染；业务规则、外部系统路由、税务判断、承运商验收或 marketplace 合规仍由你的系统负责。
常见问题
- gPdf 可以生成 SSCC 托盘标签吗？
- gPdf 可以在 PDF 输出中渲染 SSCC 条码元素。SSCC 值和 GS1 语义由你的系统负责。
- gPdf 管理托盘库存吗？
- 不管理。库存状态由 WMS 或 ERP 系统负责。gPdf 负责渲染标签 PDF。
- 托盘标签可以使用 Template Render 吗？
- 可以。托盘标签版式批准后，Template Render 通常是生产路径。
- gPdf 会认证 GS1 标签吗？
- 不会。gPdf 渲染矢量 PDF 条码。认证、扫码测试和验收仍由你负责。