Logistics and labels
面向履约流程的装箱单 PDF API
基于订单、发货、箱规和商品数据生成装箱单 PDF，服务于电商、3PL、OMS 和仓库履约流程。
主 API Template Render
ENDPOINT
/api/v1/template-render 适用系统 OMS / WMS / 3PL 后端 / Shopify app 后端
要解决的问题
基于发货、收件人、商品和箱规数据渲染装箱单，让履约团队能为每个出库订单打印或附上一份一致的文档。
什么时候用这个 API
- 你的 OMS 或 WMS 已经有订单商品、数量、收件人数据和发货标识。
- 你需要给仓库打印工位或客户包裹随附物生成 PDF 装箱单。
- 你希望一个已审核版式可复用于多个仓库、品牌或销售渠道。
- 你可能需要用于订单查询或退货入库的条码或 QR code。
它不替代什么
- 你需要购买邮资、询价发货或创建承运商面单。
- 你需要仓库库存管理，而不是文档渲染。
- 你需要法律发票或电子发票语义。
应该调用哪个 endpoint
/api/v1/template-render
Template Render 是这个场景的默认调用路径。
/api/v1/pdf/render
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/template-render - 使用 packing_list 模板渲染一票发货。
{
"template_id": "packing_list",
"data": [
{
"shipment": {
"number": "PL-2026-1001",
"date": "2026-05-29"
},
"shipper": {
"name": "Acme Warehouse",
"address": "1200 Logistics Pkwy"
},
"consignee": {
"name": "Receiver Inc.",
"address": "123 Main St"
},
"items": [
{
"item_no": "1",
"description": "Replacement filter",
"quantity": "2",
"unit": "pcs",
"gross_weight": "1.2 kg",
"net_weight": "1.0 kg"
}
]
}
]
}
gPdf 负责什么
- 为已发布装箱单版式执行 Template Render。
- 在设计阶段或一次性流程中通过 JSON Render 生成自定义装箱单页面。
- 处理表格、商品行、地址块、可选条码和 PDF 输出。
- 相同数据和模板生成可确定的重打结果。
你的系统负责什么
- 订单数据、商品数量、发货状态、仓库路由和客户文案。
- 模板字段映射、打印工位路由和重打策略。
- 任何需要随包裹同行的承运商、海关或发票文档。
上线前检查
- 测试最长 SKU、商品名和地址组合。
- 验证单件、多箱、缺货和部分发货场景。
- 装箱单版式批准后使用 Template Render。
- 为每次履约打印请求记录 template_id 和 X-Request-Id。
- 把承运商面单生成与装箱单渲染分开。
能力边界
- gPdf 渲染装箱单 PDF；不管理库存或履约状态。
- 装箱单不会自动成为税务发票或海关文件。
- 承运商面单购买和运费询价都在 gPdf 之外。
装箱单适合模板路径
装箱单通常结构稳定：发货方、收件人、发货编号、商品行和可选备注。版式批准后，Template Render 往往是很合适的选择。
设计阶段仍然需要 JSON Render。它让团队能在发布稳定 template_id 合同前，调整列宽、间距、条码位置和分页。
Endpoint 选择
默认调用 /api/v1/template-render。当版式仍在调整、调用方需要完整描述页面结构时，使用 JSON Render；当版式已经审批并需要多个系统复用时，把版式发布为模板，再通过 Template Render 传入业务数据。
如果场景涉及 Factur-X / ZUGFeRD 这类带 EN 16931 CII XML 的 PDF/A-3b 电子发票封装，才使用 E-Invoice Render。普通 PDF、标签、收据和报表不要伪装成电子发票流程。
上线前验证
用真实数据和下游系统验证 装箱单 PDF API。保留 request ID、渲染输出和验收记录，便于支持、审计和重打。gPdf 负责 PDF 渲染；业务规则、外部系统路由、税务判断、承运商验收或 marketplace 合规仍由你的系统负责。
常见问题
- 装箱单是单独的 gPdf endpoint 吗？
- 不是。已批准装箱单模板使用 Template Render；如果你的系统直接描述版式，则使用 JSON Render。
- 装箱单可以包含条码吗？
- 可以。gPdf 可以在 PDF 中渲染条码元素。编码的订单、箱号或退货 payload 由你的系统负责。
- gPdf 会创建承运商面单吗？
- 不会。承运商面单是独立流程。gPdf 根据你的承运商或发货系统提供的数据渲染 PDF。
- 一个请求可以渲染多个装箱单吗？
- Template Render 可以在一个请求中接收 data array 来渲染多个项目，但必须在该 endpoint 的公开 API 限制内。