Logistics and labels
面向 4×6 英寸 PDF 面单的快递面单 API
基于订单 JSON 生成可打印的 4×6 英寸快递面单 PDF，支持矢量条码、面单页面尺寸和确定性的仓库重打。
主 API JSON Render
ENDPOINT
/api/v1/pdf/render 适用系统 WMS / OMS / 3PL 后端 / 发货后端
要解决的问题
基于订单、收件人、服务和追踪数据渲染标签尺寸 PDF，让仓库或电商后端在履约时可靠打印同一张 4×6 英寸面单，并在需要时确定性重打。
什么时候用这个 API
- 你的系统已经有追踪号、目的地、服务文本和条码 payload。
- 你需要为 Zebra、SATO、Honeywell 或其他热敏打印流程输出 PDF。
- 你希望使用矢量条码模块，而不是把栅格条码图片贴进 PDF。
- 你需要同一个 payload 渲染出同一张面单，用于重打和审计证据。
它不替代什么
- 你需要购买邮资、运费询价，或通过承运商账号创建承运商面单。
- 你需要 ZPL 替代 endpoint。gPdf 返回 PDF，而不是打印机命令语言。
- 你需要 gPdf 提供承运商认证。扫码和承运商验收测试仍由你负责。
应该调用哪个 endpoint
/api/v1/pdf/render
JSON Render 是这个场景的默认调用路径。
/api/v1/template-render
当流程需要相关 API、模板契约或能力查询时再使用。
最小请求示例
POST /api/v1/pdf/render - 带追踪条码的最小 4×6 英寸面单。
{
"pages": [
{
"size": "label_4_6_in",
"elements": [
{
"type": "text",
"x": 4,
"y": 6,
"content": "SHIP TO",
"style": { "font_size": 8, "font_family": "NotoSans-Regular" }
},
{
"type": "text",
"x": 4,
"y": 13,
"content": "Acme Warehouse\n1200 Logistics Pkwy\nMemphis TN 38116",
"style": { "font_size": 11, "font_family": "NotoSans-Regular" }
},
{
"type": "barcode",
"format": "code128",
"content": "1Z999AA10123456784",
"x": 4,
"y": 62,
"width": 92,
"height": 22,
"barcode_text": { "enabled": true, "position": "bottom" }
}
]
}
]
}
gPdf 负责什么
- 生成 4×6 英寸等标签尺寸 PDF 页面。
- 为承运商和仓库面单内容渲染矢量条码。
- 处理文本、地址块、服务标记、线条、边框和可选模板绑定。
- 为仓库重打提供确定性 PDF 输出。
你的系统负责什么
- 承运商账号、邮资购买、服务选择和追踪号创建。
- 正确的条码 payload、人可读文本、地址和路由数据。
- 打印机设置、标签纸、扫码测试和承运商验收检查。
上线前检查
- 在真实打印机型号和标签纸上打印测试面单。
- 按目标 DPI 和扫码距离验证条码扫描率。
- 根据重打策略保存源发货数据或返回的 PDF。
- 面单版式批准并跨系统复用后，使用 Template Render。
- 把承运商专属逻辑留在渲染请求之外。
能力边界
- gPdf 渲染面单 PDF；不购买邮资，也不直接与承运商通信。
- gPdf 不是承运商面单认证机构。
- API 输出 PDF，不输出 ZPL、EPL 或其他热敏打印机命令流。
快递面单 API 的形态
快递面单页面不是单独的承运商 endpoint。你调用 JSON Render，传入标签尺寸页面、文本块、线条、可选图片和条码元素。对于复用面单，把已批准版式发布为模板，再用发货数据调用 Template Render。
这样所有权很清楚。gPdf 负责 PDF 渲染和条码绘制。你的系统负责承运商交易、发货状态和 payload 语义。
JSON Render 与 Template Render
当履约系统生成完整版式，或运营团队还在调整坐标时，使用 JSON Render。当仓库已经批准稳定面单版式，并且每个调用方都应发送相同数据字段时，使用 Template Render。
两条路径都返回 PDF 输出。区别在于调用方是每次都描述版式，还是引用已发布的 template_id。
打印测试很重要
热敏面单质量是物理问题。请使用真实标签纸、真实打印机和真实扫码设备验证输出。条码 payload 正确性、静区、打印深浅和承运商专属规则，都是渲染 API 之外的生产责任。
常见问题
- gPdf 会帮我创建承运商面单吗？
- 不会。承运商或发货系统创建承运商货件和条码 payload。gPdf 把这些数据渲染成 PDF 面单。
- 快递面单可以用 Template Render 吗？
- 可以。设计或测试面单时使用 JSON Render；当版式稳定、调用方只应发送数据时，使用 Template Render。
- gPdf 输出 ZPL 吗？
- 不输出。公开 render API 输出 PDF。如果你的打印链路需要 ZPL，请在 gPdf 之外转换或路由 PDF。
- 上线前应该验证什么？
- 用真实打印机和标签纸打印，用生产扫码设备扫描条码，并确认承运商专属文本和 payload 来自你的发货系统。